feat: add macOS ZCode runtime support

[jzhishu]

Fixes #4692

Scope note: this PR implements and validates ZCode support for the macOS app-bundle install path only. Windows discovery/launch support is intentionally left to a follow-up issue/PR once the Windows install layout and app-server entrypoint are verified.

Why

This PR adds first-class zcode runtime support to Open Design.

The original issue asked for Zhipu ZCode support in OD. During investigation, I found that the macOS ZCode install does not behave like the existing PATH-based local CLI agents: users install ZCode.app, and the usable integration entrypoint is the bundled app-server inside the app bundle. The normal --prompt path is not viable for OD because ZCode's real GUI flow uses the app-server protocol.

The first cut is scoped to ZCode's saved API-key provider configuration. OAuth/account-login token refresh is GUI-private, so this PR does not reverse-engineer app.asar and does not add OD-owned API-key fields.

What users will see

Users with ZCode installed in the standard macOS app locations can select zcode as an Open Design agent after detection.

If ZCode is installed somewhere else, Settings now shows a ZCode-specific Choose ZCode.app action instead of asking users to find or paste the internal zcode.cjs executable path. OD stores the selected app bundle path and derives the bundled app-server entrypoint internally.

ZCode runs stream into the normal OD chat UI: thinking/text deltas, tool calls, tool results, usage, completion, and run errors. ZCode model choices are read from the user's saved ZCode provider config and used for both connection tests and runs.

Connection testing now verifies model availability through the real app-server flow instead of relying on a shallow session/list probe.

Implementation notes

• Adds a dedicated zcode runtime using app-server over stdio.
• Maps ZCode session/event / state.updated frames into OD chat events.
• Drops model-request telemetry frames so request/response headers are not forwarded to the frontend.
• Injects saved ZCode API-key provider/model config during workspace/upsertModelProvider and workspace/setDefaultModel.
• Persists and reuses native ZCode sessionIds across compatible turns.
• Auto-discovers ~/Applications/ZCode.app and /Applications/ZCode.app.
• Adds a native macOS app-bundle picker for non-standard install locations.
• Keeps ZCODE_BIN as a process-level diagnostic/development override only; it is not exposed or saved through Settings.
• Rejects invalid explicit app selections such as Claude.app; an invalid explicit zcodeAppPath does not silently fall back to PATH/auto-discovery.
• Adds a bundled ZCode agent icon for Settings, the avatar menu, model switchers, and assistant messages.

Surface area

• UI — Settings exposes a ZCode-specific app bundle picker and agent detection/connection behavior.
• Keyboard shortcut — new or changed
• CLI / env var — no new od subcommand or OD_* env var. CLI dual-track is not applicable for the ZCode app bundle picker: standard installs are auto-discovered, non-standard installs require a desktop/macOS ZCode.app picker, and ZCODE_BIN remains a process-level diagnostic override only.
• API / contract — adds zcodeAppPath to app config / connection-test contracts and adds the native dialog endpoint.
• Extension point — no new skills/, design-systems/, design-templates/, or craft/ entry, and no skills protocol change.
• i18n keys — added Settings copy for ZCode app selection.
• New top-level dependency — none.
• Default behavior change — none for users without ZCode installed.
• None — not applicable.

Screenshots

1. A successful ZCode connection test.

2. A real ZCode chat run with streamed output, tool events, and the generated file preview. 3. Not Detected 4.Setup failture 5. Ready

Bug fix verification

This is a feature PR, not a bug fix.

Validation

• pnpm guard
• pnpm typecheck
• pnpm --filter @open-design/daemon test
• pnpm --filter @open-design/web test
• Focused daemon coverage:
  • ZCode protocol client
  • ZCode stream parser
  • ZCode provider config
  • ZCode session/resume helper
  • connection test model availability probe
  • runtime env/detection
  • native app picker endpoint
  • /api/runs + SSE smoke using a fake zcode app-server
• Focused web coverage:
  • Settings ZCode app selection
  • invalid app rejection
  • config persistence
  • agent refresh
  • ZCode agent icon rendering
• Manual UI validation:
  • real ZCode connection test passes
  • real ZCode run streams thinking/text/tool events
  • generated files render in the right-side preview
  • provider error diagnostics render correctly
  • retry/continue, same-conversation multi-turn, and cancel-then-continue paths were checked manuall

Bug fix verification

This is a feature PR, not a bug fix.

Validation

• pnpm guard
• pnpm typecheck
• pnpm --filter @open-design/daemon test
• pnpm --filter @open-design/web test
• Focused daemon coverage:
  • ZCode protocol client
  • ZCode stream parser
  • ZCode provider config
  • ZCode session/resume helper
  • connection test model availability probe
  • runtime env/detection
  • native app picker endpoint
  • /api/runs + SSE smoke using a fake zcode app-server
• Focused web coverage:
  • Settings ZCode app selection
  • invalid app rejection
  • config persistence
  • agent refresh
  • ZCode agent icon rendering
• Manual UI validation:
  • real ZCode connection test passes
  • real ZCode run streams thinking/text/tool events
  • generated files render in the right-side preview
  • provider error diagnostics render correctly
  • retry/continue, same-conversation multi-turn, and cancel-then-continue paths were checked manually

[lefarcen]

Hey @jzhishu — thanks for opening this as a draft.

The protocol notes in the body are useful, especially the app-server entrypoint and the session/* method mapping. We'll hold off on deeper review until this is marked ready for review.

[jzhishu]

Hi, sharing a quick status update for this draft PR.

Right now this PR is mostly ZCode groundwork: runtime registration, ZCODE_BIN detection, a minimal zcode-protocol request/response client, session/list connection probing, local app-server smoke coverage, and a temporary Settings entry for configuring the bundled ZCode CLI path.

Since opening the PR, I continued digging into the protocol. The current conclusion is that app-server is the right path, not --prompt. The ZCode GUI appears to drive the engine through session/create / session/send, with provider/model injected at runtime through the protocol.

I can now drive the real app-server flow up to:

workspace/upsertModelProvider → workspace/setDefaultModel → session/create → session/send

session/send returns accepted:true, so the handshake and core protocol shape are mostly understood.

The blocker is auth. My local ZCode is using account/OAuth login, and the real upstream model request currently returns 401 Unauthorized. It looks like the effective runtime header / credential handling may live in the GUI layer rather than being fully exposed by the bundled CLI.

So I’m keeping this PR as a draft while we decide the right next step: wait for a stable headless credential path from Zhipu, investigate the GUI app.asar auth flow, try API-key-based ZCode configuration, or consider BYOK / standard Z.AI API key support as a fallback if that still fits the issue goal.

[lefarcen]

Thanks for the detailed update — this is exactly the kind of draft-state note that's helpful.

The session/send -> accepted:true result is a strong signal that the transport shape is mostly right, and the 401 Unauthorized result does seem to narrow the remaining blocker down to auth/runtime packaging rather than protocol wiring. Keeping this as a draft while we sort out whether the right path is native ZCode auth, API-key-based ZCode configuration, or a BYOK-style fallback makes sense.

I’m routing this update for product/maintainer eyes so we can get a direction on which auth path we actually want to back before you push further into the implementation.

[jzhishu]

Update: tested the API-key approach — full headless round-trip works

I tested the documented API-key path first. The result: it works end-to-end, and the auth blocker from yesterday is resolved on this path.

API-key path — full headless round-trip (verified independent of the GUI)

Driving a standalone app-server child process over the protocol (with an API key in the provider config): upsertModelProvider → setDefaultModel → session/create → session/send → session/read.

Concretely: bigmodel API key + open.bigmodel.cn/api/anthropic → GLM-5.2 replied (finish: stop, 203 output tokens); engine log shows Model request completed / finishReason: stop. I also fully quit the ZCode desktop app and re-ran it — it still replies, confirming the GUI isn't required (which matches our daemon's no-GUI environment).

One key point: the API key's platform must match the endpoint (bigmodel key → open.bigmodel.cn, z.ai key → api.z.ai). Part of my earlier 401 was simply sending a bigmodel token to a z.ai endpoint.

OAuth / account login — confirmed not viable headlessly

I took the raw OAuth access_token and sent it directly to both endpoints (the matched public endpoint + the subscription endpoint); both returned 401 — open.bigmodel.cn responded "令牌已过期或验证不正确" ("token expired or invalid"), and the subscription endpoint returned an empty 401. The per-request token refresh/exchange is GUI-private logic (refreshBeforeModelRequest in app.asar); the engine only delegates it to the client via a callback and doesn't expose it. Per your guidance I'm not reverse-engineering app.asar, so I'm treating OAuth/account login as out of scope for the first cut.

What I'm planning to do next:

1. Implement the native zcode adapter: an app-server runtime definition + a dedicated state.updated parser, scoped to API-key config, wiring up the create → send → read main path.
2. Add a config entry for the API key + endpoint (Settings and the matching od CLI), with platform/endpoint matching.

[lefarcen]

This materially changes the picture — thanks for doing the API-key verification end-to-end.

The headless app-server round-trip plus the endpoint/key matching note makes the first cut much better scoped: API-key-backed native zcode support looks viable, while OAuth/account login sounds reasonable to leave out of scope for now if the engine only exposes that refresh path through the GUI callback.

Keeping this as a draft while you wire the create -> send -> read path and the matching API-key/endpoint config sounds right. The update is clear enough that maintainers can now judge the first-cut boundary from a much firmer base.

[jzhishu]

Hi there, quick status update on this draft PR.

With auth unblocked, I drove the real app-server frame by frame and pinned down the event contract. A couple of things that matter for the implementation:

• Events aren't pushed automatically — the client has to session/subscribe { deliveryKind: "desktop-continuous" } first, after which the server streams session/event frames.
• The streaming meaning lives in payload.kind: reasoning_delta / text_delta / tool_call / result.
• Turn completion is the single cumulative final-result frame (a failure shows up as an error frame); the per-iteration turn-result (stopReason) is not a turn end — it fires once per model round-trip inside a tool loop.

On top of that I landed two pieces of code:

• The zcode-protocol client now handles async traffic, not just request/response: an onNotification channel (separating replies from async notifications and server→client requests), a respond() answer channel, and AbortSignal-based cancellation.
• A dedicated stream parser that maps session/event + state.updated frames into the chat event set the UI already understands (text / thinking / tool calls / tool results / usage / status / errors / title). Model-request telemetry frames carry request/response headers, so the parser deliberately never forwards them.

Both are covered by unit tests built from the real captured frames (protocol client: 14, parser: 8). This part is internal plumbing with no UI surface yet, so it's verified through tests for now.

Next I'll wire this into the run pipeline so a real message round-trip is visible in the UI: per turn, spawn app-server, run the handshake, subscribe, send, and forward the parsed events to the frontend — along with settling the process lifecycle (one process per turn with resume vs. a longer-lived one), cancellation/teardown, and the tool-permission posture.

[lefarcen]

Thanks — this narrows the protocol shape a lot.

The session/subscribe requirement plus final-result being the only real turn-end signal makes the next integration step much clearer, and keeping the model-request telemetry frames out of the forwarded event stream is the right safety boundary. Keeping this as a draft while you wire the run pipeline, lifecycle, and cancellation path still sounds right; once the real round-trip is visible in the UI, this will be in a much better place for ready-for-review.

[jzhishu]

Here’s a quick update on the ZCode draft PR.

The main ZCode daemon path is now wired through streamFormat: "zcode-protocol", and I’ve added a daemon HTTP-boundary smoke test for it. The test uses a fake zcode app-server and covers the /api/runs + SSE round trip: provider injection, session create/setMode/subscribe/send, and forwarding text/tool/result/usage/completed events.

I’ve also verified the main UI flows end to end:

• ZCode connection test passes in Settings.
• Sending a normal message from the UI now returns a real ZCode response; the previous empty response / completed without output failures are fixed.
• Streaming output renders correctly in chat, including thinking/text deltas.
• TodoWrite plan cards appear and update as execution progresses.
• Tool calls show up in the UI, including Bash / Write events.
• ZCode can generate real HTML files, and the right-side preview opens and renders the generated UI correctly.
• Provider failure paths render properly: when the upstream provider returned an insufficient balance/resource package error, Open Design showed run error diagnostics instead of silently failing or returning an empty response.
• After topping up the provider balance, I also verified retry / continue remaining tasks.
• Multi-turn conversation in the same Open Design conversation works.
• User cancel / stop followed by continuing with the next run also works.

Still remaining:

• Native ZCode session/resume / session reuse is not wired yet. The UI multi-turn flow works, but that does not necessarily mean we’re using ZCode’s native resume semantics yet.
• Model list / model selection UX still needs cleanup.
• ZCode runtime/provider health checks should be made stronger; the current shallow session/list-style check can report green without proving model availability.
• The temporary Settings entry and copy need product cleanup.
• Retry/continue/cancel flows have been manually verified, and we can add more automation around them next.

If there are any other end-to-end cases you’d like covered, please suggest them and I’ll add them to the test pass.

[lefarcen]

Thanks — the /api/runs boundary smoke test plus the manual end-to-end pass closes most of the risky path here.

The two cases I'd still prioritize before this leaves draft are native session/resume / session reuse (since the UI multi-turn flow can still mask that gap) and a stronger health check that proves model availability rather than just a shallow session/list-style green light. Everything else in this update makes the first-cut boundary feel much clearer.

[nettee]

@jzhishu I'm holding off on generating review comments for #4819 because this pull request has merge conflicts right now.

Please resolve the conflicts with main and push the updated branch. Once that's done, request or wait for the review to run again and I'll take another look.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[nettee]

@jzhishu I found two blocking reliability issues in the new ZCode protocol lifecycle. The concrete fixes are in the inline comments.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[lefarcen]

Quick follow-up from our side: @nettee's current-head review already covers the blockers I would want fixed on this revision, so I'd use those inline comments as the gate for the next update. Once the stdin-failure handling and post-prompt_completed tail handling are addressed, the next pass should be much clearer.

[nettee]

Thanks for the substantial ZCode integration. I found three blocking runtime regressions that need resolution; the inline comments cover the Kimi adapter conversion and a ZCode connection-test failure path.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[lefarcen]

Quick follow-up: @nettee's latest current-head review is the one to drive on e0ad1b6 — the Kimi adapter regression, the missing prompt-argv budget/test contract, and the ZCode connection-test exit race are the blockers on this revision.

Once those inline comments are addressed, the next pass should be in much better shape.

💡 To drive this PR to merge hands-free, paste this to your AI coding agent (Claude Code / Codex / opencode / Cursor …):
Take over nexu-io/open-design#4819 until it merges — read https://raw.githubusercontent.com/nexu-io/looper/main/skills/pr-takeover/SKILL.md and follow it.

[nettee]

I found two blocking reliability issues in the new ZCode state and session lifecycle. The concrete fixes are in the inline comments.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[lefarcen]

Quick follow-up: @nettee's latest current-head review is the one to work from on 44d17fb — the two blockers are the expired-session resume recovery in the ZCode lifecycle and the Settings rescan/hydration path that can clear a saved ZCode.app selection too early.

Once those inline comments are addressed, the next pass should be in much better shape.

[nettee]

@jzhishu

I reviewed the ZCode runtime end to end: app-bundle resolution, saved-provider configuration, protocol/session lifecycle, connection-test behavior, Settings persistence, and the focused regression coverage. The changed ranges are coherent and I found no actionable correctness or safety issues.

Thank you for the thorough implementation and follow-up fixes—this is a substantial integration, and the coverage around protocol failures and session recovery is especially appreciated.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[nettee]

@jzhishu I found one blocking issue in the updated ZCode unavailable-card diagnostics. The inline comment covers the concrete fix.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[nettee]

@jzhishu I reviewed the current ZCode head end to end across the changed ranges: app-bundle detection and persistence, the saved-provider/runtime wiring, the protocol/session lifecycle, the connection-test path, and the focused regression coverage that landed with those pieces. The current implementation is internally consistent and I did not find any actionable correctness or safety issues on d13704d.

I wasn’t able to execute the Vitest suites in this worktree because node_modules are not installed here, but the new daemon and web tests in the diff cover the failure paths I would have expected to probe manually. Thanks for pushing a fairly deep runtime integration through with this much targeted coverage.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[jzhishu]

@jzhishu I reviewed the current ZCode head end to end across the changed ranges: app-bundle detection and persistence, the saved-provider/runtime wiring, the protocol/session lifecycle, the connection-test path, and the focused regression coverage that landed with those pieces. The current implementation is internally consistent and I did not find any actionable correctness or safety issues on d13704d.

I wasn’t able to execute the Vitest suites in this worktree because node_modules are not installed here, but the new daemon and web tests in the diff cover the failure paths I would have expected to probe manually. Thanks for pushing a fairly deep runtime integration through with this much targeted coverage.

🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.

Thanks for the thorough end-to-end review and the kind words. Appreciate you checking the latest head across the runtime wiring and failure-path coverage. I’ll keep an eye on CI for the Vitest results.

[open-design-crew]

Thanks for the ZCode follow-through. To verify the current head after the picker and diagnostics updates, could you add a short recording or a small labelled screenshot set of the Settings → Agents ZCode states: (1) the normal unavailable card with the ZCode-specific Choose ZCode.app action; (2) choosing a non-standard ZCode.app and the resulting saved selected-path or not-ready state, then Rescan/refresh; (3) the stale or invalid selected-bundle diagnostic and its recovery guidance; and (4) a successful connection-test result once a valid bundle is available. Please keep the relevant card, selected-path/diagnostic text, and action controls visible in each state. The native macOS picker itself does not need to be recorded. Once this current-head Settings coverage is in, the design side can review the remaining runtime flow with confidence.

[nettee]

@jzhishu I reviewed the current ZCode head end to end across the changed ranges: app-bundle detection and persistence, saved-provider/runtime wiring, the protocol and session lifecycle, the connection-test path, the Settings diagnostics flow, and the focused regression coverage that landed with those pieces. The implementation on 90008c83 is internally consistent and I did not find any actionable correctness or safety issues in scope.

I wasn’t able to execute the Vitest suites in this worktree because node_modules are not installed here, but the added daemon and web tests cover the failure paths I would have expected to probe manually. Thanks for pushing a fairly deep runtime integration through with this much targeted coverage.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[nettee]

@jzhishu I reviewed the current ZCode head end to end across the changed ranges: app-bundle detection and persistence, saved-provider/runtime wiring, the protocol and session lifecycle, the connection-test path, the Settings diagnostics flow, and the focused regression coverage that landed with those pieces. The implementation on 55a3812b is internally consistent and I did not find any actionable correctness or safety issues in scope.

I wasn’t able to execute the Vitest suites in this worktree because node_modules are not installed here, but the added daemon and web tests cover the failure paths I would have expected to probe manually. Thanks for pushing a fairly deep runtime integration through with this much targeted coverage.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

[jzhishu]

Thanks for the continued work on the ZCode runtime! 🙏 Since my earlier design approval (Jul 4), the branch added new UI in the Settings ZCode card — the AgentDiagnosticRow component (new module styles) plus the "align zcode unavailable card actions" change — which the current screenshots don't cover. Could you post updated screenshots of the Settings › Execution ZCode card in these states: (1) available/ready with the Test action, (2) unavailable/not-detected showing the aligned card actions, and (3) the diagnostic row when a setup failure is surfaced? Once those are in this should be a quick re-approve. (Heads up: the branch is also showing merge conflicts, so a merge/rebase from main is needed too.)

Thanks! I’ve added updated screenshots for all three requested states: ready with the Test action, not detected with aligned card actions, and the setup-failure diagnostic row. The branch is also up to date with main and conflict-free.

[lefarcen]

Thanks for adding the updated screenshots and rebasing on main — that directly closes the last design follow-up. The three Settings › Execution ZCode states are covered now, so this head should be ready for design re-check.

[jzhishu]

Thanks for adding the updated screenshots and rebasing on main — that directly closes the last design follow-up. The three Settings › Execution ZCode states are covered now, so this head should be ready for design re-check.

Thanks for confirming! Appreciate the re-check.