zcode-provider

Turn the ZCode agent (zcodex app-server, an OpenCode-derived CLI agent) into a pi model provider. pi is the chat frontend; the ZCode agent keeps its own session, runs its own tools (bash, edits, plugins, ...), and its reply is streamed back into pi in real time — the reasoning, the tool calls and the final text all arrive as they happen, not as one chunk at the end. Reasoning, text, tool calls and their results are rendered inline, interleaved in the exact order ZCode produced them (ZCode executes the tools itself; pi only displays the call/results as formatted transcript blocks).

Each ZCode provider/model configured in ZCode becomes a selectable pi model, and the list auto-syncs from ZCode's config — no hardcoded model list, no pi reload when you add or change providers.

Install

# from npm (recommended)
pi install npm:zcode-provider

# or from the GitHub repo:
pi install git:github.com/ZhouXiaolin/zcode-provider
# pinned to a release:
pi install git:github.com/ZhouXiaolin/[email protected]

Requirements:

• ZCode CLI (zcodex / zcode app-server) installed and functional — this is a bridge to the local ZCode agent, not a cloud API.
• pi (obviously).

After installing, run /reload inside pi, then /model and pick a ZCode model, e.g. 火山/glm-latest or Z.ai - Coding Plan/GLM-5.3. Switching models mid-conversation works via ZCode's session/setModel.

How model selection works

ZCode's app-server resolves models only from its settings file (~/.zcode/cli/config.json), while the ZCode UI writes providers to ~/.zcode/v2/config.json. This extension:

1. Merges enabled providers from the v2 config into the settings file at server spawn and whenever either config.json changes (the app-server re-reads its settings file live, so newly merged providers work immediately).
2. Bootstraps the settings file's model field. The app-server validates the settings file against a strict schema that requires a top-level model — a "provider/model" ref — and refuses to run a turn with "Model config is missing" when it is absent or invalid. The extension keeps an existing valid ref (the app-server persists session/setModel choices back to this field), else falls back to the v2 config's own model selection, else the first enabled provider's first model. The settings file is also created from scratch when it does not exist yet.
3. Publishes the catalog to pi via refreshModels, so opening /model always shows the current providers/models without a reload.
4. Switches the ZCode session model with session/setModel when you pick a different pi model. The choice also persists back to ZCode's config (model.main), so the model you last used in pi is ZCode's default.

Provider edits are additive and every write to the settings file is backed up first (config.json.bak-<timestamp>).

Configuration

Environment variables (set before starting pi):

| Variable | Default | Meaning | | --- | --- | --- | | ZCODE_SERVE_CMD | node <zcode.cjs> app-server (auto-detected: /opt/ZCode/resources/glm/zcode.cjs on Linux, /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs on macOS) | Command that starts the ZCode stdio app server | | ZCODE_SETTINGS | ~/.zcode/cli/config.json | Settings file the app-server reads models from | | ZCODE_V2_CONFIG | ~/.zcode/v2/config.json | ZCode UI config whose enabled providers are merged in | | ZCODE_AUTO_ALLOW | 1 (enabled) | Auto-answer ZCode permission prompts. Set to 0 to deny tool permission requests | | ZCODE_TURN_TIMEOUT_MS | 1800000 (30 min) | Per-turn budget. On timeout the bridge interrupts the turn (session/stop) and sends the session go on, so long tasks keep progressing instead of failing. Raise it for turns that need to run longer uninterrupted | | ZCODE_STEER_MODE | auto | How a message typed in pi while a ZCode turn is running is handled, using ZCode's own two delivery modes: queue (processed as a new turn after the current one completes — pi's standard behavior) or guide (sent to the running session via ZCode's v4 command channel and injected at the next tool/message boundary inside the same turn, falling back to a queue when the turn is not steerable). Default follows ZCode's own UI setting (zcodeInteractionBehavior in ~/.zcode/v2/setting.json): guide when ZCode is configured for guide-mode interaction, else queue. Set explicitly to override |

Security

This bridge gives pi the full power of your ZCode agent. ZCode runs its own tools (bash, file edits, plugins) with your configured model. By default the bridge auto-answers ZCode's permission prompts with "allow" — that is the point of the bridge, but review what you let it do. Set ZCODE_AUTO_ALLOW=0 to have it deny permission requests instead. Review the source before use.

No API keys are stored in this package; the bridge reads ZCode's own local config. The dummy provider key zcode-bridge is only a pi placeholder.

Debugging

Run /zcode-probe in pi: it runs one full turn against the app-server and dumps the raw protocol lines to /tmp/zcode-probe.jsonl.

How it works (wire protocol)

zcodex app-server speaks a private NDJSON protocol over stdio (not standard JSON-RPC). The bridge implements the subset:

session/create → answer session/requestRuntimePreferences → session/resume (no-op while resident, rehydrates after idle eviction) → session/subscribe → session/send → stream session/event notifications: model.streaming (text/reasoning/tool-input deltas), tool.updated, turn.completed — done on state.updated (reason prompt_completed). Model switching uses session/setModel.

The ZCode app-server evicts idle sessions from memory (resident pool: 10 min idle timeout, LRU beyond 16 sessions) and would otherwise reject stale session ids with "Session is not active"; the bridge resumes the persisted session before every turn, so multi-turn continuity survives idle gaps.

Session continuity across pi restarts. The bridge remembers the ZCode session id per pi session (a small sidecar file ~/.zcode/cli/zcode-provider-sessions.json, keyed by pi session UUID). When you exit pi and restore the same conversation with pi --session <id> (or /resume), the bridge calls session/resume on the remembered ZCode session instead of session/create, so the ZCode agent keeps its full session history (session memory, accumulated context, tool state). A fresh pi session in the same project, or a restore from a different working directory, still gets a new ZCode session as before.

Updates while a turn is running

Messages typed in pi while the ZCode agent is mid-task are delivered using ZCode's own two delivery modes (its followupMode setting):

• queue: pi queues the message and runs it as a new ZCode turn once the current one completes — nothing is injected mid-run. This is ZCode's queue followupMode and pi's standard model-provider flow.
• guide: the bridge enables ZCode's guide followupMode on the session (v4 conversation subscription + CAS setFollowupMode) and hooks pi's input event. A message typed while the turn is running is sent to the running session via the v4 sendText command; ZCode injects it at the next tool/message boundary inside the same turn (turn.steerQueued → turn.steerDrained), falling back to a queue when the turn is not steerable or already has queued input. pi marks the message as handled, so it is not duplicated into the next turn. The steered run's reply streams into pi as usual.

Which mode applies is decided by ZCODE_STEER_MODE: an explicit ZCODE_STEER_MODE=guide / =queue wins, otherwise the bridge follows ZCode's own UI setting (zcodeInteractionBehavior in ~/.zcode/v2/setting.json). If your ZCode desktop app is set to guide-mode interaction (its default is queue), pi steers too — no extra env var needed.

Asking you questions (ZCode's askUserQuestion)

When the ZCode agent calls its askUserQuestion tool, the app-server asks the bridge for user input (interaction/requestUserInput). The bridge shows the question as a pi dialog — options with descriptions, Space toggles for multi-select, plus a free-text "Type something." entry — and answers the request with your choice. The ZCode agent then continues in the same session with your answer (the tool returns "User has answered your questions: ...").

• The dialog appears mid-turn; the stream stays open until you answer or press Esc to cancel (cancelling answers the request with cancel).
• Up to 4 questions per interaction are asked one after another.
• The server auto-resolves unanswered interactions after 5 minutes (askUserQuestionAutoResolutionEnabled), so a dialog left open will not hang the turn forever.
• The tool call is still rendered in the transcript (🔧 askUserQuestion with the question text) followed by the answer.

Known limitations

• A turn that exceeds ZCODE_TURN_TIMEOUT_MS (default 30 min) is checkpointed: the bridge interrupts it (session/stop) and sends the session go on, so the ZCode agent continues the task with its full session history. The pi stream stays open until the task completes. Stopping the turn in pi aborts the server-side turn too, and cancels any background tasks (run_in_background bash etc.) the agent started in the session — ZCode's own stop leaves those running, so the bridge stops them explicitly (session/cancelBackgroundTask per running task).
• Upstream model/API failures are surfaced with the real reason. When the ZCode turn fails (model API timeout, auth error, ...), the app-server's turn.failed event carries the structured error; the bridge forwards its message (plus the HTTP status code when the app-server reports one, e.g. zcode turn failed: Origin Time-out (HTTP 524)) to pi instead of a generic "turn ended with failure". Cancelling a turn (session/stop) is reported as a cancellation, never as a failure.
• The app-server streams reasoning, tool calls and text live (model.streaming and tool.updated events after session/subscribe); deltas arrive chunked, and the final text is also reconciled from the messages store when no live deltas were seen (e.g. subscription failed).
• Tool calls are display-only, rendered inline in stream order. ZCode runs them inside its own session; the bridge never emits pi toolCall blocks (pi's harness would try to execute them itself, and pi's TUI renders every toolCall block as a box appended below the assistant message — splitting the transcript into a text part on top and a tool part below). Instead each tool call (model.streaming tool_input_*) and its result (tool.updated kind=result) are rendered as formatted markdown text blocks appended in the exact order the app-server reports them, so reasoning, tools, results and the final answer interleave in the transcript like ZCode's own output: thinking block → text block → tool call → tool result → next thinking block → … Each tool call renders as **🔧 Name** — summary (one-line command/path summary for the common tools, fenced JSON for complex args, the question text for askUserQuestion); each result renders as a fenced text block capped at 6k chars with truncation and failure markers.
• Results mirror pi's own tool display, not the full tool output — the full result stays inside the ZCode session (the agent's model already consumed it), so the transcript only shows a readable preview:
  • read-like tools (read/read_file/view_file): the call line shows the requested range like pi's collapsed read box — 🔧 read — /path:80-220 — and the result collapses to nothing (failures still show the error text).
  • bash: command + output are merged into one fenced block in pi's style — $ cmd, then ... (N earlier lines) with the last 10 lines of the output (tail preview, like pi's bash display), closed with a Took 0.0s duration line measured by the bridge between the call and its result.
  • everything else: fenced text capped at 6k chars of the head, with truncation and failure markers. A turn that ends with a bash call whose result never arrived (aborted/timeout) closes the fence so every block stays well-formed.
• MCP / skill / plugin tools are handled too. ZCode namespaces MCP tools as mcp__<server>__<tool> (e.g. mcp__codegraph__codegraph_explore); the bridge maps that to a clean display name <server>__<tool> for the inline heading, and any tool name is rendered through the same generic formatter. ZCode's own environment — its MCP servers, skills and tools — always runs the real call; pi only mirrors the name, arguments and result text.
• pi's RPC/print mode has a model-resolver crash in some pi 0.84.2 builds that also affects built-in providers; interactive /model is unaffected.
• The resident-pool eviction cannot be configured from outside the app-server; idle recovery relies on session/resume (one extra round-trip only after the session was evicted).

License

MIT