zai-vision — FALLBACK for text-only models (NOT GLM-5.3)

STOP — native VLM gate

If the current model id contains glm-5.3 (including glm-5.3-flash, zai/glm-5.3*):
close this skill. Look at the image yourself. Do not call any zai-vision / @z_ai/mcp-server tool.
GLM-5.3 is a native multimodal model (https://docs.z.ai/guides/vlm/glm-5.3-flash): images are
messages[].content[] with type: image_url (URL or base64). Routing them through
glm-4.6v-flash is a downgrade and a bug.

This skill exists only because older GLM-5.2 is text-only. Keep reading only if you are
on GLM-5.2 or another text-only model.

Why this exists: omp used to default to zai/glm-5.2 — text-only, it cannot read pixels. 8sync harness auto-installs and registers the zai-vision MCP (@z_ai/mcp-server, npm) as a fallback for those text-only sessions. The current default is zai/glm-5.3-flash, which does NOT need this bridge. For a text-only session the pattern is:

image (screenshot / PDF page / diff render / chart) → zai-vision tool → TEXT → GLM-5.2 acts on the text

Never hand raw image bytes to GLM-5.2 expecting it to "look" — it can't. Always route through a vision tool first. GLM-5.3 / 5.3-Flash already look — do not use this bridge.

Verified working setup (tested end-to-end on 2026-07-01)

8sync harness registers the server in ~/.omp/agent/mcp.json:

"zai-vision": {
  "type": "stdio",
  "command": "zai-mcp-server",           // installed via `bun add -g @z_ai/mcp-server`
  "args": [],
  "env": {
    "Z_AI_MODE": "ZAI",                   // api.z.ai endpoint (matches the zai/glm-5.2 key)
    "Z_AI_VISION_MODEL": "glm-4.6v-flash", // THE ONLY MODEL VERIFIED WORKING ON A STOCK KEY
    "Z_AI_API_KEY": "<pulled from `omp token zai`>"
  }
}

Model choice is load-bearing. Per Z.AI's pricing page (docs.z.ai/guides/overview/pricing), vision models are: GLM-5V-Turbo ($1.2/M), GLM-4.6V ($0.3/M), GLM-4.5V ($0.6/M), GLM-OCR ($0.03/M), GLM-4.6V-FlashX ($0.04/M), and GLM-4.6V-Flash — completely FREE. A stock zai/glm-5.2 Coding-Plan key has NO vision resource package, so every paid model 400s with "1113: Insufficient balance or no resource package" until you buy one. glm-4.6v-flash is the only one that works out of the box — that's why 8sync harness defaults Z_AI_VISION_MODEL to it. If you buy a vision package, override it in ~/.omp/agent/mcp.json → mcpServers.zai-vision.env.Z_AI_VISION_MODEL.

The free model is occasionally overloaded ("1305: service may be temporarily overloaded", transient, unrelated to thinking mode — both were tested independently). Retry 2-3× with a short backoff before concluding it's broken.

Real proof (actually run, not illustrative)

A local HTML card ("Weekly Plan / Mon Review notes / Tue Design draft / Wed Team sync / Thu Write docs / Fri Ship") was screenshotted with the browser tool and fed through the REAL zai-mcp-server stdio process (JSON-RPC tools/call, not just the raw API):

tool: extract_text_from_screenshot
args: {"image_source":"/tmp/zai-clean.png","prompt":"List the text you see, verbatim."}

<output>
**Extracted Text**

Weekly Plan
Team summary

Mon Review notes
Tue Design draft
Wed Team sync
Thu Write docs
Fri Ship

**Content Type**
A text-based weekly plan or schedule UI component.
...
</output>

Text extracted verbatim, matching the source HTML exactly. analyze_image on the same screenshot ("Describe the layout, colors, and purpose") correctly identified the two-column layout, the exact hex-ish colors (blue title, gray subtitle, green "Ship" tag), and inferred it was a team task tracker — all from pixels GLM-5.2 alone cannot see.

Tool catalog (exact params, from the installed package source)

All 8 tools take image_source (or video_source) as a local file path OR a remote URL (not base64 — the server reads the file / fetches the URL itself) + a prompt describing the ask:

Tool	Extra params	Use for
extract_text_from_screenshot	programming_language (optional hint)	OCR: code, terminal output, logs, docs
analyze_image	—	Fallback / general description, layout, colors
diagnose_error_screenshot	—	Root-cause a stack trace / error dialog screenshot
understand_technical_diagram	—	Architecture diagrams, flowcharts, UML, ER, sequence diagrams
analyze_data_visualization	—	Charts/graphs → trends, anomalies, business read
ui_to_artifact	—	UI screenshot → frontend code / design spec / NL description
ui_diff_check	—	Visual regression: compare expected vs actual UI
analyze_video	video_source instead of image_source	Video content understanding

Combination matrix — every way this plugs into the existing stack

8sync shot/browser → image is only ONE case. All of these route the SAME way (image → zai-vision tool → text → act):

Source (produces an image)	zai-vision tool	Then
omp browser tool screenshot (tab.screenshot)	extract_text_from_screenshot / analyze_image	Feed text back into the conversation; GLM-5.2 reasons over it
8sync shot <url> (render a live page)	ui_to_artifact (design→code) or analyze_image (review)	Generate/compare frontend code with impeccable skill
8sync pdf-img <file> (long PDF → per-page PNG)	extract_text_from_screenshot per page	Concatenate extracted text; treat as normal text doc
8sync diff-img <ref> (git diff render, >500 lines)	ui_diff_check (visual regression) or extract_text_from_screenshot (read the diff)	Review/comment as if reading the raw diff
Codegraph/codebase-memory-mcp get_architecture rendered as a diagram image	understand_technical_diagram	Cross-check the graph's textual answer against the rendered picture
serena symbol edits guided by a UI mock	ui_to_artifact → get a code skeleton	Hand the skeleton to serena rename/code_actions for precise symbol-level edits, not blind rewrites
Long/garbled vision tool output (>50 lines)	—	Pipe through headroom headroom_compress before it enters context (STEP 0 rule applies to vision output too)
omp's built-in inspect_image tool	—	Generic fallback when a specialized zai-vision tool doesn't fit (rare — zai-vision's 8 tools cover almost everything)
Chart/graph screenshot from a dashboard	analyze_data_visualization	Feed the trend/anomaly summary into retain if it's a durable project fact
Terminal error screenshot (can't copy-paste the text)	diagnose_error_screenshot	Root cause + fix, then act on the fix directly
A fact learned from any of the above worth remembering	—	retain it (Mnemopi long-term memory) so future sessions recall it without re-running vision
Any vision-guided edit before committing	—	--advisor (omp's passive turn reviewer) catches misrouted or hallucinated vision-derived changes
Deciding image vs text in the first place	—	Consult the image-routing skill's decision table FIRST; this skill is what happens AFTER that table says "image"

Setup / troubleshooting

• Auto-setup: 8sync harness (bare or init) installs @z_ai/mcp-server via bun add -g, resolves the key via omp token zai (falls back to $Z_AI_API_KEY/$ZAI_API_KEY env), and registers it in ~/.omp/agent/mcp.json. Re-run 8sync harness any time; it self-heals if the command/env drifted.
• 8sync doctor reports zai-vision MCP ON/OFF and whether it's registered.
• No omp Z.AI auth yet? The server registers WITHOUT a key (doctor/harness warns); run omp token zai once you've authed zai/glm-5.2 in omp, then re-run 8sync harness to pick it up.
• 1113 insufficient balance → you're on a paid vision model without a purchased vision package. Either buy one on z.ai, or stay on the default free glm-4.6v-flash.
• 1305 temporarily overloaded → transient; retry 2-3× with ~5s backoff (with_retry is already built into the server's analyze_image/etc. for network errors, but NOT for this HTTP 429-style overload — the caller must retry).
• 1211 unknown model → wrong Z_AI_VISION_MODEL string. Valid vision codes as of this writing: glm-5v-turbo, glm-4.6v, glm-4.6v-flash, glm-4.6v-flashx, glm-4.5v, glm-ocr. (glm-4v, glm-4v-plus, glm-4v-flash, glm-4.5v-flash do NOT exist on the api.z.ai endpoint — verified by direct testing.)
• omp's live capability surface (advisor/inspect_image/model-role flags, refreshed every 8sync harness run) is at ~/.omp/capabilities.md.