ZCode → T3 Code: Native Provider Integration

1. Executive summary

2. What ZCode is

2.1 Protocol version history (community-documented, breaks are real)

Sources: supermomongo/zcode-acp, tizerluo/zcode-open-bridge, ExMCP ZCode adapter docs.

2.2 Prior art: GUIs already wrapping ZCode (proof the approach works)

3. The integration surface: spawn zcode.cjs app-server --stdio

3.1 Process architecture (verified live + from asar/host code) FRESH

ZCode (Electron main)
├─ Renderer (iframe UI)  ←→ host via Electron MessagePortMain (NOT network)
├─ utilityProcess forks:
│   ├─ "zcode-host-local-1"   = out/host/index.js (from app.asar) — the service layer
│   │    └─ "zcode-cli" child = Resources/glm/zcode.cjs
│   │         spawned as:  <electron-execPath> zcode.cjs app-server --stdio
│   │         env: ELECTRON_RUN_AS_NODE=1 (+ --surface desktop)
│   └─ "zcode-cron-scheduler" = automation cron
└─ ZCode Computer Use.app (CUA helper, unix socket + token file)

zcode-server.cjs = the SAME host layer packaged standalone, for REMOTE Linux hosts
(SSH push via ssh2 + CDN download). NOT an HTTP API — VSCode-style binary channels.

There is no meaningful HTTP API anywhere. UI→host is MessagePort IPC; host→agent is a stdio child. ZCode's own desktop app is "just another client" of the agent CLI — which is exactly the position T3 would occupy. The host even exposes env overrides for alternative hosts: ZCODE_AGENT_SERVER_COMMAND / ZCODE_AGENT_SERVER_ARGS_JSON (default ["app-server","--stdio"]) and GLM_BINARY_PATH, with runtime candidates $ZCODE_SERVER_RUNTIME_ROOT/glm/zcode.cjs, ~/.zcode/server/agents/glm/zcode.cjs, process.resourcesPath/glm/zcode.cjs.

3.2 The V4 protocol (host ↔ agent, NDJSON over stdio) FROM HOST BUNDLE

Transport: newline-delimited JSON on the child's stdout (stderr → logs). Envelope is zod-.strict():

request      {id, method, params?, trace?}
notification {method, params?, trace?}
response     {id, result}
error        {id, error: {code, …}}
— preceded on boot by:
  → stdout: {"type":"zcode-hello","version":…,"platform":…,"arch":…,"pid":…}
  ← stdin:  {"type":"zcode-hello-ack","version":…,"clientId":…}   (≤10s window)

Methods (V4_METHODS, exact strings from the host bundle):

v4/connection/flow                    backpressure {connectionId, state: saturated|drained|closed}
v4/controller/subscribe|resync|unsubscribe
v4/conversation/subscribe|resync|unsubscribe|frame|rowsRange|plans|fileChanges|
                  fileRewindPreview|usage
v4/attachment/begin|chunk|commit|abort|read|previewSource    (chunks ≤512 KiB)
v4/commands/query   v4/command   v4/usage/stats   v4/telemetry/event
v4/cua/permission-observation

Commands ride a CAS envelope (optimistic-concurrency, "10-protocol-spec §6.4") via v4/command:

{commandId: uuidv7 (stable across retries), clientId, sessionId|null,
 baseRevision?, baseLogEpoch?, type, payload, issuedAt}
ack: accepted|duplicate|noop  else error ZCODE_V4_COMMAND_REJECTED

26 command types: createSession, createSelectionSideSession, sendText, sendGoalCommand, stop, compact, forkAssistant, applyFileRewind, editUserQuery, retryTurn, setAssistantFeedback, sendQueuedNow, editQueueItem, reorderQueueItem, deleteQueueItem, setAutoDrain, resolveInteraction, revokeWorkspaceHookTrust, snoozeInteractionAutoResolution, switchModelConfig, switchCollaborationMode, setFollowupMode, pauseGoal, resumeGoal, cancelBackgroundWork, renameSession, deleteSession. CAS-gated (require baseRevision): file rewind, fork, queue edits, model/mode switches, goal pause/resume, feedback.

Representative payloads: createSession {workspaceId, firstInput:{text, attachments[]}, config?, runtimeModel?, mcpServers?} · sendText {text, attachments?, requestedDelivery: startNow|queue|guide, heldQueueDisposition: clearQueueAndSend|keepQueueAndSend} · stop {expectedForegroundExecutionId?} · editUserQuery {target, newText, workspaceMode: preserve|rewind}.

Streaming: v4/conversation/frame delivers snapshot + deltas. Conversation row kinds: turnHeader, userInput, assistantText, reasoning, toolCall, subagent, hookInvocation, timelineMarker. Delta event kinds: row.appended / row.delta / row.removed / row.upserted, turn.started / turn.terminal, tool.lifecycle, subagent.lifecycle, permission.lifecycle, usage.delta, stream.chunk, state.updated, compaction.terminal, config.updated, session.upserted / session.removed, task.upserted / task.removed, phase.completed / phase.error, checkpoint.created, mode.set/list, model.set/streaming, mcp.servers.

Approvals: permission.requested → permission.respond → permission.resolved, plus elicitation.respond. Images: v4/attachment/begin|chunk|commit (≤512 KiB chunks). Interrupt: stop command. Compaction: compact command + compaction.terminal event. Model switch: switchModelConfig (CAS-gated). Rewind/fork: applyFileRewind / forkAssistant + v4/conversation/fileRewindPreview.

3.3 Why not the alternatives

3.4 Live verification — VERIFIED END-TO-END 2026-09-09

Independent probe (driver written from scratch, not reusing sub-agent scripts) against the installed 3.11.2 bundle, run as plain system Node:

node /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs app-server --stdio   # cwd = workspace

Redacted transcript of the successful run (full logs: /tmp/zcode-t3-verify/run4.log):

>>> {"id":"c1","method":"session/create","params":{"workspace":{"workspaceKey":"<ws>","workspacePath":"<ws>"}}}
<<< {"id":"server-1","method":"session/requestRuntimePreferences","params":{"sessionId":"sess_…","scope":"runtime-materialization"}}
>>> {"id":"server-1","result":{"nativeSearchEnhancementsEnabled":false,"memoryEnabled":false,
       "askUserQuestionAutoResolutionEnabled":true,"modelContextBudgetStrategy":"preflight-v1"}}
<<< {"id":"c1","result":{
       "protocol":{"name":"ZCode Protocol","version":1},
       "session":{"sessionId":"sess_74f1…","mode":"build","sessionKind":"interactive",
                   "model":{"modelId":"glm-5.1","providerId":"builtin:zai"}},
       "settings":{"model":{"available":[
          {"label":"glm-5.1","ref":{…},"supportsImages":false,"reasoning":{"levels":["0","1"]}},
          {"label":"glm-5v-turbo","ref":{…},"supportsImages":true,…}, …]}},
       "projection":{"status":…,"pendingPermissions":…,"contextWindow":200000,…}}}
>>> {"id":"c2","method":"session/subscribe","params":{"sessionId":"sess_74f1…","deliveryKind":"desktop-continuous"}}
<<< {"id":"c2","result":{"eventSeq":0,"events":[]}}          ← replay cursor (remote reconnect support)
>>> {"id":"c3","method":"session/send","params":{"sessionId":"sess_74f1…","content":"Reply with exactly: T3_ZCODE_OK"}}
<<< {"method":"state.updated","params":{"patch":{"status":"running"},"reason":"prompt_started","revision":1}}
<<< {"id":"c3","result":{"accepted":true,"stateRevision":1}}
<<< {"method":"session/event","params":{"type":"session.titleUpdated","payload":{"source":"first_input",…}}}
<<< {"method":"session/event","params":{"type":"turn.started","payload":{"foregroundExecutionId":"runtime_command_1","queryId":"query_…"}}}
<<< {"method":"session/event","params":{"type":"session.updated","payload":{"messageCount":6,"toolCount":161,…}}}
<<< {"method":"v4/telemetry/event","params":{"kind":"model.request.status","status":"model_request_started",
       "providerKind":"anthropic","providerHostname":"api.z.ai","transport":"sse","querySource":"main_turn","attempt":1,"maxAttempts":11}}
<<< {"method":"session/event","params":{"type":"session.updated","payload":{"content":"T3_ZCODE_OK","stopReason":"stop",
       "usage":{"inputTokens":50809,"outputTokens":7,"totalTokens":50816,"cacheReadTokens":10368,"cacheWriteTokens":0},
       "contextUsageBreakdown":[{"source":"system_prompt","chars":6663},{"source":"meta_user_context","chars":25194},
         {"source":"skills","chars":8942},{"source":"system_tool_schemas","chars":86042},
         {"source":"mcp_tool_schemas","chars":230308},{"source":"messages","chars":59}]}}}
<<< {"method":"session/event","params":{"type":"turn.completed","payload":{"response":"T3_ZCODE_OK",
       "usage":{"source":"provider","modelRequestCount":1,"inputTokens":50809,"outputTokens":7,
                 "totalTokens":50816,"cacheReadTokens":10368,"reasoningTokens":0,
                 "webFetchRequests":0,"webSearchRequests":0},
       "toolCallCount":0,"historyRoundCount":1,"duration":6769,"resultType":"success",
       "cacheStats":{"totalMessages":7,"cachedMessages":6,"lastCacheHit":true}}}
>>> {"id":"c4","method":"session/messages","params":{"sessionId":"sess_74f1…"}}
<<< {"id":"c4","result":{"messages":[ {user msg with contextSnapshot.envInfo, tools:{Agent,Bash,Edit,Read,Write,
        TodoWrite,TodoRead,WebFetch,WebSearch,Skill,SendMessage,TaskOutput,TaskStop,AskUserQuestion,
        EnterPlanMode,ExitPlanMode,CronCreate,CronDelete,CronList,CronUpdate,ReadSessionContext,…},
        parts:[{type:"text","text":"Reply with exactly: T3_ZCODE_OK",…}]}, {assistant msg with completed ts,…} ]}}
>>> {"id":"c5","method":"session/list","params":{}}
<<< {"id":"c5","result":{"sessions":[{sessionId,title,titleSource:"generated",status:"idle",mode,
        workspace:{workspaceKey,workspacePath},createdAt,updatedAt}, …]}}

Verification findings (beyond the transcript)

• No hello handshake needed for the bare CLI — zcode-hello is the desktop host's transport; a JSON-RPC client connects by simply sending requests. My first probe stalled waiting for hello; driving directly works.
• Strict zod errors are self-documenting: an invalid deliveryKind returned -32602 enumerating the allowed values — "desktop-continuous" | "web-remote-replayable". The latter is a replayable event stream purpose-built for remote/replay consumers — an unusually good match for T3's relay/tunnel connection modes.
• Subscribe-before-send matters: without session/subscribe, turn state still broadcasts (state.updated, telemetry) but conversation content events (session/event stream) flow to subscribers. The subscribe result returns an eventSeq cursor for replay.
• Envelope omits jsonrpc — sending it yields -32600 "Invalid ZCode Protocol message".
• Auth just works via existing files: the probe copied only ~/.zcode/cli/config.json (provider apiKey) into a sandbox and completed real GLM calls (providerKind:"anthropic", providerHostname:"api.z.ai").
• The session DB is shared, not redirected: despite ZCODE_STORAGE_DIR, the probe's sessions were written to the live ~/.zcode/cli/db/db.sqlite WAL (72 string hits for the probe session id; main-db query at immutable=1 missed them because they live in the WAL). Only rollout/ and plugins/ honored the redirect. Implications: (a) T3 threads and desktop threads interoperate in one history — a feature (start in T3, continue in ZCode desktop), and WAL multi-process writing is exactly how ZCode's own desktop multiplexes its zcode-cli children; (b) test isolation must use a HOME override, not ZCODE_STORAGE_DIR, until the true DB override knob is identified.
• Cost profile: a trivial "reply OK" turn consumed 50,809 input tokens (86 KB system tool schemas + 230 KB MCP tool schemas + 25 KB user context) — cache reads already kicked in on request 1 (10,368 tokens). Expect heavy-but-cached context on every turn; surface contextUsageBreakdown in T3's context meter.

4. Prior research digest (July–Aug 2026 artifacts in ~/ZCodeProject/artifacts/)

4.1 Two headless surfaces exist (prior verification, v0.15.2)

Prior-verified app-server method surface (v0.15.2):

session/create          session/resume          session/list
session/send            session/stop            session/messages
session/events          session/fork            session/compact
session/setMode         session/setModel        session/goal
v4/conversation/subscribe     (start streaming)
v4/conversation/frame         (server→client streaming frames)
interaction/requestPermission (server→client request)
interaction/requestUserInput  (server→client request)
workspace/*   mcp/list   plugins/*   automation/create

Prior-verified env vars (found in bundle):

4.2 One-shot mode facts (prior-verified, v0.15.2)

• --mode <build|edit|plan|yolo> permission policy; default is yolo for --prompt (auto-approves everything; the branch is literally mode==="yolo" ? allow(...) "Yolo mode bypasses permission prompts"). plan is the safe headless mode.
• Read-only tools auto-allowed in every mode: Read, Glob, Grep, WebSearch, WebFetch, TodoRead, TodoWrite, AskUserQuestion, Agent, Task, Skill.
• Phantom flags advertised in --help but rejected by the strict parser (verified live): --print, --max-turns, --allowed-tools, --permission-mode, --allow-main-worktree-yolo.
• Functional flags: --cwd, --disallowed-tools (the ONLY allow/deny flag), --attach (repeatable), --resume <sess_…>, -c/--continue, --target (= /goal), --json, --no-color, --verbose.
• Prompt cannot be piped via stdin — falls through to TUI branch, fails on non-TTY.
• Exit codes: 0 success / 1 error / 130 SIGINT / 143 SIGTERM.

4.3 Session storage & history (prior-verified)

• History lives in SQLite: ~/.zcode/cli/db/db.sqlite — tables session, message, part, todo, session_target, usage. Grew 172 MB (Jul) → 731 MB (Aug) → 1.7 GB (now), ~495 sessions at first measurement.
• No built-in sync/backup/export/share — triple-verified on 3.4.2 (no sync slash command, no server sessions endpoint, session.share_url column dead, relay wss://zcode.z.ai/ws is live remote-control only). STALE-3.4 — re-check on 3.11.2.
• ~/.zcode/cli/rollout/ raw model-I/O JSONL is transient and embeds live Bearer tokens — never surface it in T3 UI.
• Secrets on disk (plaintext): ~/.zcode/v2/credentials.json (Z.AI OAuth+JWT), ~/.zcode/codex/auth.json, ~/.zcode/v2/acp-auth/, keys inside ~/.zcode/cli/config.json.
• Session rows embed absolute paths (session.directory, contextSnapshot.envInfo) — history import is readable cross-machine but -c resume is machine-local.

4.4 GLM inside T3 Code today (without native integration)

• The Claude-endpoint hack is live on this machine: ~/.claude/settings.json rewires the claude CLI that T3 spawns to ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic with a z.ai Coding Plan token, models glm-5.2[1m] / glm-4.7. So George already runs GLM in T3 through the Claude adapter. This is model-level routing, not ZCode-the-agent integration: no ZCode sessions, tools, workflows, or permissions.
• Codex → GLM direct is impossible: Codex 0.146.0 only speaks wire_api="responses"; z.ai returns 404 on all /responses paths (200 on /chat/completions). Working recipe needs a LiteLLM bridge (responses_api_bridge: true, api_base must include /api/coding/paas/v4 — the /coding/ segment selects flat-rate Coding Plan billing; wrong path silently burns pay-as-you-go credit).
• z.ai exposes Anthropic-compatible (/api/anthropic) and OpenAI-compatible endpoints, not Responses API.

4.5 Other prior findings relevant to a provider adapter

• Subagents: Explore-type (7 tools) vs general-purpose (["*"] → resolves to 215 tools); background mode with task-IDs, steering, notifications — vocabulary that parallels T3's own task model (turn_started, model_streaming, tool_call_scheduled, checkpoint_created, turn_complete … in ~/.zcode/cli/agents/*/transcript.jsonl).
• ZCode creates checkpoints (checkpoint_created events observed in subagent transcripts) — relevant to T3's per-turn checkpoint feature; needs fresh verification of mechanics (git refs? internal?).
• MCP: standard stdio/http transports; flat mcp.servers map in ~/.zcode/v2/config.json with drift vs legacy ~/.zcode/cli/config.json; project .mcp.json supported.
• Workflows runtime (QuickJS sandbox, agent()/pipeline()/parallel()) shipped in 3.3.6 — out of scope for a T3 provider v1 but a differentiator for later.
• Slash commands: compact, expert, fork, goal, init, login, logout, mcp, memory, mode, model, new, plugins, resume, rewind, skill, workflow.

4.6 On-disk state, session store & credentials — FRESH 2026-09-09

Full read-only sweep of the live install (SQLite opened mode=ro&immutable=1; keychain probed by attribute lookup only — no entries exist, ZCode auth is entirely file-based).

Storage generations on this machine

The canonical session store: ~/.zcode/cli/db/db.sqlite

• 2032 sessions, 85,124 messages, 315,629 parts. Sessions span 2026-06-06 → 2026-09-08 across 50 project directories.
• session: id sess_<uuid>, project_id (proj_users-george-workspace-t3trade), absolute directory, title + title_source, task_type (interactive 493 / subagent_child 1536 / selection_side_chat), parent_id subagent linkage, compaction/archival timestamps, trace_id.
• message.data (JSON): user messages carry model:{providerID:"builtin:zai-coding-plan", modelID:"GLM-5.3", variant}, contextSnapshot.envInfo (cwd/platform/git), anchor:{turnId, sourceCommandId}; assistant messages carry tokens:{total,input,output,reasoning,cache:{read,write}}, finish, mode.
• part types: tool (callID/tool/state{status,input,output,title}/time), text, reasoning (with metadata.anthropic.signature — Anthropic reasoning blocks), step-start/step-finish, file, compaction (pre/post token counts, trigger, summaryMessageId).
• Aux tables: turn_usage (tokens + TTFT), model_usage (embeds anthropic.usage), tool_usage (top tools: Bash 22k, Edit 5k, Read 4.3k, Write, TodoWrite, mcp__playwright__*, Agent, SendMessage, Skill — read_only/destructive flags), todo, permission, session_target (objective/token budget), workflow_*.
• Large tool outputs are truncated in-row and offloaded to ~/.zcode/cli/artifacts/<sess>/call_*.txt (join via callID); raw per-call stdout under cli/exec/<sess>/; raw model I/O captures under cli/rollout/ only when enabled (only 3 files exist).

Lineage verdict (fresh)

Checkpoints — same mechanism as T3 VERIFIED

~/.zcode/v2/checkpoints/<projhash>/<uuid>.json: {refName: "refs/zcode/checkpoints/<projhash>/<uuid>", commitOid} — hidden git refs, the same trick T3's per-turn checkpoints use. v2 task JSONs also carry turnCheckpoints. Checkpoint parity in a T3 adapter is architectural alignment, not new invention.

Credential reuse for T3 (paths only — values never reproduced here)

No macOS keychain entries exist (probed by attribute: none for ZCode/zcode/ai.z.zcode/zai/Z.ai). Detection heuristic for T3: provider considered "logged in" iff ~/.zcode/v2/credentials.json has a zai OAuth token or ~/.zcode/cli/config.json has a provider apiKey. Copy, never lock — the running app writes these files.

History import feasibility: HIGH

Everything T3 renders per thread/turn exists: session id, project directory, titles, typed message parts (text/reasoning/tool with inputs+outputs), per-turn token counts incl. cache, todos, compaction boundaries. Gaps: cost always 0 (subscription billing — display "—" or compute from tokens), offloaded tool outputs need the artifacts join, compacted-away history not retained. ZCode's own Claude-Code importer proves the symmetric pattern; a T3 ← ZCode importer maps session→project/thread, message+part→turns/events, turn_usage/model_usage→token accounting. v2/v1 history needs separate (simpler) importers.

5. T3 Code integration map (server side)

5.1 Where the provider layer lives

apps/server/src/provider/
├── ProviderDriver.ts            # Driver SPI + ProviderInstance record (plain values, no tags)
├── builtInDrivers.ts            # BUILT_IN_DRIVERS array + BuiltInDriversEnv  ← THE registration point
├── providerSnapshot.ts          # shared probe helpers: buildServerProvider, spawnAndCollect…
├── makeManagedServerProvider.ts # generic snapshot lifecycle (probe/enrich/refresh/TTL)
├── Services/                    # interfaces: ProviderAdapter, ProviderService, ProviderRegistry,
│                                #   ProviderInstanceRegistry(+Mutator), ProviderAuthService…
├── Layers/                      # implementations + per-provider <X>Adapter.ts / <X>Provider.ts
├── Drivers/                     # per-provider <X>Driver.ts (config schema → instance factory)
├── acp/                         # shared ACP runtime: AcpSessionRuntime (1,294 ln), AcpRuntimeModel,
│                                #   AcpCoreRuntimeEvents, per-provider ACP glue
└── testFixtures/, testUtils/    # codex collab mock peer, fakeCli (acp-mock-agent)

packages/effect-acp/             # first-party ACP JSON-RPC-over-stdio client
packages/effect-codex-app-server # first-party Codex app-server JSON-RPC client

5.2 The two SPIs every provider implements

Materialization is provider-agnostic (no edits): ServerSettings → deriveProviderInstanceConfigMap (Layers/ProviderInstanceRegistryHydration.ts:73) → ProviderInstanceRegistryLive.buildEntry (:117) decodes config and runs driver.create; failures degrade to an "unavailable" shadow snapshot. ProviderAdapterRegistry resolves instanceId → adapter; ProviderService is the facade transports call.

5.3 The four existing protocol families

5.4 What a new provider gets for free (event-driven, provider-agnostic)

• Checkpoints/diffs/restore: orchestration/Layers/CheckpointReactor.ts reacts to turn.completed/turn.aborted and captures hidden git refs via checkpointing/CheckpointStore.ts. Emit correct turn events → checkpoints work with zero adapter code.
• Projection + receipts: ProviderRuntimeIngestion projects adapter events into orchestration events/activities.
• Shared plumbing: RuntimeInstructions (the <runtime_info> block), ProviderEventLoggers (native+canonical NDJSON protocol capture), userInputAttachments, thread-scoped MCP (McpProviderSession).
• Honest-capabilities rule (docs/internals/providers.md): if the provider can't rewind its conversation, set supportsConversationRollback = false so revert is rejected before files change. ZCode does have rewind (v2 checkpoints + session/fork) — verify before enabling.
• "Setup must not happen as a health-check side effect" — the status probe must not authenticate or open sessions. For Zcode: probe = resolve bundle path + --version; auth detection = read credential files (§4.6), never trigger login.

5.5 Exact ordered file list for zcode (server side)

server.ts needs no edit unless the driver introduces a new shared service beyond BuiltInDriversEnv.

5.6 Test patterns to imitate

• apps/server/src/provider/Layers/GrokAdapter.test.ts — full adapter lifecycle against testUtils/fakeCli.ts's acp-mock-agent (configurable via env flags like T3_ACP_EMIT_TOOL_CALLS). A zcode equivalent: a zcode-mock-app-server.ts script driven by env flags, exercising spawn/handshake/turn/interrupt/permission against TestClock.
• Layers/GrokProvider.test.ts — probe/parsing units + fake-CLI status tests (binary missing → installed:false; version parsing; auth states).
• Thick-provider pattern: ClaudeAdapter.test.ts injects a FakeClaudeQuery implements AsyncIterable<SDKMessage> — same idea as injecting a fake session-runtime factory (CodexAdapter.test.ts).

5.7 Adapter comparison & template recommendation GIT-VERIFIED

Pattern: adapter size tracks protocol delegation, not feature count. The three ACP adapters share ~2,500 lines of runtime (AcpSessionRuntime 1,294 + AcpRuntimeModel 887 + AcpCoreRuntimeEvents 234) and each pays only for CLI quirks.

Git archaeology — the ground-truth "add a provider" checklists

Shared-layer lineage: ACP+Cursor 9c64f12ea0 → OpenCode ce94feeea1 → multi-instance model 08e6d4cfbf → Grok 38ea6d483e → Antigravity 06336460c9.

Additional contract point discovered

packages/contracts/src/providerRuntime.ts:19-28 — add a RuntimeEventRawSource literal (e.g. "zcode.jsonrpc") so native raw events round-trip through protocol logging.

6. T3 Code integration map (UI / contracts / all surfaces)

6.1 How provider selection flows today

6.2 Icons & detection UI

• Web icons: inline React SVG components in apps/web/src/components/Icons.tsx (Antigravity precedent: base64 PNG wrapped in SVG <image>). Map lives in providerIconUtils.ts:12-19.
• Mobile icons: apps/mobile/src/components/ProviderIcon.tsx:13 — inline react-native-svg branches with dark/light fills; PNG via expo-image precedent (assets/antigravity.png). Unknown drivers fall back to the OpenAI glyph — a branch is required or Zcode shows the wrong logo.
• Install/login status UI is fully generic (providerStatus.ts:32: "Not found / CLI not detected on PATH", "Not authenticated", "Authenticated · label" from ServerProvider.installed/auth). No per-provider work.
• No i18n layer — plain string labels.

6.3 Exhaustive file checklist for provider zcode

A. Contracts (packages/contracts)

B. Client-runtime / shared

C. Web (apps/web)

D. Mobile (apps/mobile)

E. Desktop — nothing (provider-agnostic shell). F. Server — see §5. G. Docs — docs/user/providers-zcode.md only if setup has user-facing quirks (pattern: providers-{claude,codex,opencode,antigravity}.md).

7. Per-T3-feature support plan

Every capability T3's other providers expose, mapped to the verified zcode surface. LIVE = observed in the verification probe or sub-agent live captures; DOC = in the bundle method table / community docs, not yet exercised; DECIDE = product decision required.

8. Actionable build plan

Phase 0 — spike ✅ (this report)

Protocol verified, transcript captured, architecture mapped, file lists enumerated.

Phase 1 — contracts + skeleton (provider appears in UI)

Phase 2 — protocol client + session runtime (core loop)

Phase 3 — full feature parity

Phase 4 — polish + docs

9. Risks, unknowns & security notes

10. Evidence log

10.1 Live commands executed (this session)

# Process observation (read-only)
ps aux | grep -i zcode; ps -ww -p <pid> -o command=; lsof -p <pid>   → one zcode-cli per project cwd + zcode-host-local-1 broker

# Independent protocol verification (isolated workspace /tmp/zcode-t3-verify)
node /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs --version      # → 0.16.5
node …/zcode.cjs app-server --stdio                                        # driven by /tmp/zcode-t3-verify/driver.mjs
#   run2: proved no hello handshake; run3: deliveryKind enum via -32602 zod detail;
#   run4: full transcript — create/subscribe/send/turn.completed("T3_ZCODE_OK", 50,816 tokens)/messages/list
sqlite3 "file:…db.sqlite?mode=ro&immutable=1" …                            # DB location forensics
strings ~/.zcode/cli/db/db.sqlite-wal | grep -c sess_74f13653               # → 72 (DB not redirected by ZCODE_STORAGE_DIR)

Probe disclosure: the verification wrote 3 trivial sessions into the shared live ZCode history (titles "Reply with exactly: T3_ZCODE_OK" / "Request for exact T3_ZCODE_OK reply", workspace /tmp/zcode-t3-verify/ws). They are visible in ZCode desktop and deletable there; the live DB was never opened read-write by this investigation.

10.2 Primary sources (local)

10.3 Investigation lanes (8 parallel sub-agents)

10.4 Key external references

• docs.z.ai/devpack/quick-start — official Coding Plan endpoints (Anthropic + OpenAI base URLs), supported-tools list, key policy
• zcode.z.ai/en/changelog — version currency (3.11.2, Sep 4 2026)
• tizerluo/zcode-open-bridge — deepest written account of the app-server protocol and 0.14→0.16 breaking changes
• getpaseo/paseo#1670 — the full prior-art arc ending in a shipped ZCode provider in a T3-like orchestrator
• ExMCP ZCode adapter docs — independent protocol documentation (streaming kinds, permissions)

Report generated by Claude Code (GLM-5.3 via T3 Code) · 8 parallel investigation sub-agents + independent live verification · 2026-09-09