feat(agents): add ZCode as a first-class supported agent - #13965
feat(agents): add ZCode as a first-class supported agent#13965guanbear wants to merge 6 commits into
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughThe pull request adds ZCode as a supported TUI and CLI agent. It defines ZCode launch, detection, labeling, telemetry, session, and hook-event behavior. It adds managed hook configuration, platform-specific scripts, local and remote installation, removal, refresh, and status reporting. Desktop, preload, and web APIs expose ZCode hook status. It adds ZCode rate-limit fetching and status-bar usage controls. It adds deferred orchestration startup for ZCode workers. Tests cover startup, lifecycle normalization, configuration preservation, installation, removal, remote setup, rate-limit handling, UI migration, and IPC status handling. Documentation and localized agent catalogs include ZCode. 🚥 Pre-merge checks | ✅ 2 | ❌ 3❌ Failed checks (3 warnings)
✅ Passed checks (2 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 698ae131-54f9-459b-9792-1959fa4825fa
📒 Files selected for processing (45)
README.mdconfig/tsconfig.cli.jsondocs/readme/README.es.mddocs/readme/README.fr.mddocs/readme/README.ja.mddocs/readme/README.ko.mddocs/readme/README.pt.mddocs/readme/README.zh-CN.mdmobile/src/tasks/mobile-tui-agents.tssrc/main/agent-hooks/managed-agent-hook-registry.tssrc/main/agent-hooks/managed-hook-local-filesystem.test.tssrc/main/agent-hooks/remote-hook-service-installers.test.tssrc/main/agent-hooks/remote-managed-hook-installers.tssrc/main/ipc/agent-hooks.test.tssrc/main/ipc/agent-hooks.tssrc/main/zcode/hook-service.test.tssrc/main/zcode/hook-service.tssrc/main/zcode/zcode-hook-config.test.tssrc/main/zcode/zcode-hook-config.tssrc/preload/api-types.tssrc/preload/index.tssrc/renderer/src/i18n/locales/en.jsonsrc/renderer/src/i18n/locales/es.jsonsrc/renderer/src/i18n/locales/ja.jsonsrc/renderer/src/i18n/locales/ko.jsonsrc/renderer/src/i18n/locales/zh.jsonsrc/renderer/src/lib/agent-catalog.tsxsrc/renderer/src/lib/agent-status.tssrc/renderer/src/web/web-preload-api.tssrc/shared/agent-hook-listener.test.tssrc/shared/agent-hook-listener.tssrc/shared/agent-hook-relay.tssrc/shared/agent-hook-types.tssrc/shared/agent-kind.tssrc/shared/agent-name-token-match.tssrc/shared/agent-session-resume.tssrc/shared/agent-status-types.tssrc/shared/agent-type-label.tssrc/shared/skills-cli-agent-keys.tssrc/shared/telemetry-events.tssrc/shared/tui-agent-config.tssrc/shared/tui-agent-display-names.tssrc/shared/tui-agent-selection.tssrc/shared/tui-agent-startup.test.tssrc/shared/types.ts
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
src/main/runtime/orca-runtime.ts (1)
21919-21941: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winExtract the repeated deferred-agent-terminal creation block into a shared helper.
The try/catch block that calls
createDeferredAgentTerminaland records the startup terminal fields repeats three times, once per creation branch (folder-repo, local-git, remote). Each copy differs only in the targetworktreeSelector/worktreePathand in whether the result is stored in astartupTerminalobject or in separatestartupTerminalHandle/startupTerminalTabId/startupTerminalPaneKey/startupTerminalPtyIdvariables.Extract a private helper that takes the worktree id, path, agent, launch preferences, and a warning-message template, and returns either the created terminal or a warning string. Call it from all three sites to keep the failure-warning wording and spawn logic in one place.
♻️ Sketch of a shared helper
private async spawnDeferredAgentTerminal( worktreeSelector: string, worktreePath: string, args: { startupAgent: TuiAgent; startupLaunchPreferences?: AgentLaunchPreferences } ): Promise< | { terminal: RuntimeTerminalCreate; warning?: undefined } | { terminal?: undefined; warning: string } > { try { const terminal = await this.createDeferredAgentTerminal(worktreeSelector, { agent: args.startupAgent, ...(args.startupLaunchPreferences ? { launchPreferences: args.startupLaunchPreferences } : {}), surfaceOwner: false }) return { terminal } } catch (err) { const message = err instanceof Error ? err.message : String(err) return { warning: `Failed to create the deferred agent terminal for ${worktreePath}: ${message}` } } }Also applies to: 22694-22714, 23064-23083
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 3e815c5b-fb1e-4d7b-8b3f-d592627e7cc8
📒 Files selected for processing (11)
src/main/ipc/preflight.test.tssrc/main/runtime/orca-runtime.tssrc/main/runtime/orchestration/preamble.test.tssrc/main/runtime/orchestration/preamble.tssrc/main/runtime/rpc/methods/orchestration-worker-topology.tssrc/main/runtime/rpc/methods/orchestration-workers-new-worktree.test.tssrc/main/runtime/rpc/methods/orchestration-workers.tssrc/main/runtime/rpc/methods/orchestration.test.tssrc/shared/local-agent-install-dir-detection.tssrc/shared/tui-agent-config.tssrc/shared/tui-agent-startup.test.ts
| ) | ||
| } | ||
| let terminalHandle = params.terminal | ||
| let promptDelivery: 'agent-input' | 'startup-command' = 'agent-input' |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Handle explicit ZCode terminals with startup-command delivery.
If params.terminal is set for ZCode, promptDelivery remains 'agent-input'. Lines 241-248 then call sendTerminalAgentPrompt instead of sendTerminalAgentStartupPrompt.
Select the delivery mode from requiresOrchestrationStartupPrompt(agent) before the explicit-terminal branch. If an existing terminal cannot support startup-command delivery, reject --terminal for this agent instead of marking a worker ready with an undeliverable dispatch. Add a regression test for agent: 'zcode' with terminal set.
Also applies to: 241-248
1 participant
ELI5
Orca can now run ZCode as a first-class agent from the agent picker and as a supervised orchestration worker, while showing its running/waiting/completed lifecycle instead of treating it as an opaque terminal process.
On macOS, Orca does not require a personal shim or the community
zcode-app-clipackage. It can launch the official signed ZCode Desktop runtime directly for prompted one-shot work.When the user has independently installed an interactive
zcode-app-clionPATH, Orca detects that capability and uses its persistent TUI for supervised workers. The official Desktop runtime, remote hosts, and custom command overrides stay on the supported one-shot--promptpath.What Changed
zcode, then fall back to the official app-bundled runtime atResources/glm/zcode.cjsfor dependency-free one-shot execution.zcode-app-clistarts as a persistent TUI, receives the complete Dispatch contract as agent input, and remains observable.--promptexecution.~/.zcode/cli/config.json./hook/zcodeingestion and normalized ZCode's Claude-compatible lifecycle/tool events into Orca agent status.hooks.enabledvalue on removal.Why
ZCode users currently cannot select ZCode as a first-class Orca agent or see its lifecycle in Orca. A command-only plugin would not cover native agent selection, process detection, managed hooks, SSH installation, shared status types, or mobile support; Orca's experimental plugin manifest reserves
contributes.agents, but there is no runtime Agent Provider extension point yet.This is increasingly relevant to Orca's user base: Z.ai recently reported that ZCode reached one million users (official announcement). The number is cited as Z.ai's reported figure rather than an independently audited active-user metric.
This refreshes the intent of #10654 against current
mainand credits @innocarpe's earlier implementation. The current hook and agent-status architecture has moved enough that a fresh patch is easier to review than reviving the conflicting branch.Linked Issue
Fixes #10564
Visual Behavior
Before: ZCode is absent from Orca's agent picker and its hook events are not recognized.
After: ZCode is a catalog option when either a PATH-based executable or the macOS ZCode Desktop bundle is detected. Interactive supervised workers expose their task display label and live TUI/model activity. Without an interactive PATH client, the official Desktop bundle remains the transparent one-shot fallback.
The production renderer and web client build successfully. An automated screenshot is not attached because macOS Accessibility permission is unavailable to the isolated local Electron validation process.
How To Test
macOS Desktop bundle
/Applications/ZCode.appavailable, select ZCode with an initial prompt and confirm the official one-shot runtime completes without a shim or community package.--agent zcodeand confirm the one-shot worker receives the Dispatch contract and exits normally afterworker_done.Optional interactive PATH client
zcode-app-clionPATHand verifyzcode --versionincludes thezcode-app-climarker.--agent zcodeand confirm it reachesready/input_accepted, shows the task label and live TUI activity, and keeps thezcode-cliprocess alive.Other platforms and SSH
zcodeexecutable is onPATH.~/.zcode/cli/config.jsonretains existing user hook definitions.Validation
zcode-app-cliPATH launch tested through a real multi-turn-capable TUI, including a completed GLM-5.2 turn and resumable session.~/.local/bin/zcode.completedafterworker_done.ready/input_accepted, keptzcode-clialive, exposed live model activity, and was explicitly stopped afterward.git diff --checkpass.The repository-wide Vitest suite was also attempted earlier. It reaches unrelated local-environment failures in existing Zsh shell-ready, native
node-pty, 7za, Electron rebuild, and performance tests; focused affected suites are green and CI remains the authoritative full matrix.Security And Compatibility
zcode-app-cli; it only uses a client the user independently placed onPATH.Known External Limitation
ZCode Desktop 3.7.5's bundled interactive TUI currently fails because
@zcode/tuiis missing (zai-org/feedback#51). Orca therefore uses the official bundle for one-shot--promptexecution and only enables persistent TUI behavior when it positively detects the optional interactive PATH distribution.AI Disclosure
Implemented with OpenAI Codex. The earlier full patch was independently reviewed by Kiro CLI using Claude Opus 5 with high reasoning; no GLM or Codex fallback was used.
Checklist
Author