Skip to content

feat(agents): add ZCode as a first-class supported agent - #13965

Closed
guanbear wants to merge 5 commits into
stablyai:mainfrom
guanbear:codex/zcode-first-class
Closed

guanbear wants to merge 5 commits into
stablyai:mainfrom
guanbear:codex/zcode-first-class

Conversation

@guanbear

@guanbear guanbear commented Aug 12, 2026 •

Copy link
Copy Markdown

Summary

Adds ZCode to Orca's first-class agent contract: catalog selection, launch settings, process recognition, managed hooks, normalized lifecycle status, SSH hook installation, mobile/web labels, and telemetry.

This refreshes #10654 against current main and credits @innocarpe's earlier implementation.

Fixes #10564.

Scope

This PR is now the reviewable core only. It does not include:

Those pieces are split into draft follow-ups so the first-class agent contract can be reviewed independently.

Follow-ups

What Changed

  • Registers zcode across desktop, web, mobile, selection, labels, telemetry, and resume/status types.
  • Detects the zcode launcher and zcode-cli process identity.
  • Adds automatic/manual permission mapping through Orca's existing agentDefaultArgs flow.
  • Installs Orca-managed hooks in ~/.zcode/cli/config.json locally and over SSH.
  • Normalizes ZCode's Claude-compatible lifecycle and tool events into Orca status updates.
  • Preserves user-authored hooks and restores the previous hooks.enabled value when Orca hooks are removed.

Runtime Support

Capability This PR
Interactive zcode executable on PATH Yes
Agent picker and launch settings Yes
Local and SSH managed hooks Yes
Running/waiting/completed status Yes
ZCode Desktop prompt-only fallback Follow-up
Supervised workers and transcript reads Follow-up
Coding Plan usage meter #14556

Visual Proof

Before After
Agent picker before ZCode Agent picker with ZCode

Validation

  • Focused startup, permissions, hook configuration, hook service, process identity, and status tests pass.
  • Node, web, and CLI typechecks pass on Node 24.
  • Formatting, lint, and git diff --check pass.
  • No credentials or quota data are introduced by this PR.

Security And Compatibility

  • Hook installation is idempotent and removes only Orca-managed commands.
  • Hook payloads use the existing authenticated loopback hook path.
  • Remote installation reuses Orca's atomic SFTP config writer.
  • ZCode's automatic mode is configured through the shared permission map; users can select manual mode or override arguments using existing Orca settings.

AI Disclosure

Implemented with OpenAI Codex and validated with focused tests and typechecks.

@coderabbitai

coderabbitai Bot commented Aug 12, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Important

Review skipped

We couldn't safely recover the incremental review. No full review was started, and the last reviewed checkpoint was preserved. Retry later, or explicitly request a full review by commenting @coderabbitai full review.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Note

Reviews paused

It 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 reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

The pull request adds ZCode as a supported agent. It updates shared types, detection, startup behavior, UI catalogs, localization, documentation, and mobile selection. It adds local and remote hook installation with status APIs. It adds SQLite transcript reading through worker-backed native chat and orchestration paths. Worker orchestration now supports deferred ZCode startup, readiness checks, startup-command fallback, provider-session warnings, and one-shot workers. Tests cover these new behaviors.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 7.41% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly and concisely summarizes the primary change: adding ZCode as a fully supported agent.
Description check ✅ Passed The description covers the main changes, rationale, issue link, visual proof, validation, security, compatibility, and AI disclosure, with equivalent content for most template sections.

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between 5ea7df1 and 77a2a5f07c78e8689945a3cad5b8160414d48b93.

📒 Files selected for processing (45)
  • README.md
  • config/tsconfig.cli.json
  • docs/readme/README.es.md
  • docs/readme/README.fr.md
  • docs/readme/README.ja.md
  • docs/readme/README.ko.md
  • docs/readme/README.pt.md
  • docs/readme/README.zh-CN.md
  • mobile/src/tasks/mobile-tui-agents.ts
  • src/main/agent-hooks/managed-agent-hook-registry.ts
  • src/main/agent-hooks/managed-hook-local-filesystem.test.ts
  • src/main/agent-hooks/remote-hook-service-installers.test.ts
  • src/main/agent-hooks/remote-managed-hook-installers.ts
  • src/main/ipc/agent-hooks.test.ts
  • src/main/ipc/agent-hooks.ts
  • src/main/zcode/hook-service.test.ts
  • src/main/zcode/hook-service.ts
  • src/main/zcode/zcode-hook-config.test.ts
  • src/main/zcode/zcode-hook-config.ts
  • src/preload/api-types.ts
  • src/preload/index.ts
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/i18n/locales/es.json
  • src/renderer/src/i18n/locales/ja.json
  • src/renderer/src/i18n/locales/ko.json
  • src/renderer/src/i18n/locales/zh.json
  • src/renderer/src/lib/agent-catalog.tsx
  • src/renderer/src/lib/agent-status.ts
  • src/renderer/src/web/web-preload-api.ts
  • src/shared/agent-hook-listener.test.ts
  • src/shared/agent-hook-listener.ts
  • src/shared/agent-hook-relay.ts
  • src/shared/agent-hook-types.ts
  • src/shared/agent-kind.ts
  • src/shared/agent-name-token-match.ts
  • src/shared/agent-session-resume.ts
  • src/shared/agent-status-types.ts
  • src/shared/agent-type-label.ts
  • src/shared/skills-cli-agent-keys.ts
  • src/shared/telemetry-events.ts
  • src/shared/tui-agent-config.ts
  • src/shared/tui-agent-display-names.ts
  • src/shared/tui-agent-selection.ts
  • src/shared/tui-agent-startup.test.ts
  • src/shared/types.ts

Comment thread src/main/zcode/hook-service.test.ts Outdated
Comment thread src/main/zcode/zcode-hook-config.ts Outdated
Comment thread src/shared/agent-name-token-match.ts Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
src/main/runtime/orca-runtime.ts (1)

21919-21941: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract the repeated deferred-agent-terminal creation block into a shared helper.

The try/catch block that calls createDeferredAgentTerminal and records the startup terminal fields repeats three times, once per creation branch (folder-repo, local-git, remote). Each copy differs only in the target worktreeSelector/worktreePath and in whether the result is stored in a startupTerminal object or in separate startupTerminalHandle/startupTerminalTabId/startupTerminalPaneKey/startupTerminalPtyId variables.

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

📥 Commits

Reviewing files that changed from the base of the PR and between bdb38accf922c2d92c893fca0e9e3f973dc5f3c4 and cd3772b7dcb4febb3c2d07ae46d5a81398b93e29.

📒 Files selected for processing (11)
  • src/main/ipc/preflight.test.ts
  • src/main/runtime/orca-runtime.ts
  • src/main/runtime/orchestration/preamble.test.ts
  • src/main/runtime/orchestration/preamble.ts
  • src/main/runtime/rpc/methods/orchestration-worker-topology.ts
  • src/main/runtime/rpc/methods/orchestration-workers-new-worktree.test.ts
  • src/main/runtime/rpc/methods/orchestration-workers.ts
  • src/main/runtime/rpc/methods/orchestration.test.ts
  • src/shared/local-agent-install-dir-detection.ts
  • src/shared/tui-agent-config.ts
  • src/shared/tui-agent-startup.test.ts

Comment thread src/main/runtime/rpc/methods/orchestration-workers.ts Outdated
@guanbear
guanbear force-pushed the codex/zcode-first-class branch from 1b84643 to 4d51c6a Compare August 12, 2026 15:34
@guanbear

Copy link
Copy Markdown
Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Aug 12, 2026 •

Copy link
Copy Markdown
Contributor
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@guanbear

Copy link
Copy Markdown
Author

@coderabbitai summary

@coderabbitai

coderabbitai Bot commented Aug 12, 2026

Copy link
Copy Markdown
Contributor
✅ Action performed

Summary regeneration triggered.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
src/main/runtime/rpc/methods/orchestration-worker-topology.ts (1)

111-113: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Condense the comment.

Keep the rationale in one concise line.

As per coding guidelines, “Comments must be concise, non-obvious, and brief—prefer one line.”

Source: Coding guidelines

🔇 Additional comments (14)
src/shared/tui-agent-config.ts (1)

33-35: LGTM!

Also applies to: 333-353, 356-358

src/main/zcode/interactive-client.test.ts (1)

1-60: LGTM!

src/main/zcode/interactive-client.ts (1)

1-38: LGTM!

src/main/runtime/orca-runtime.ts (8)

9-9: 🎯 Functional Correctness

⚠️ Unverified finding
Sandbox verification was unavailable.

Verify the isOpenCodeNativeTitle fast-path is symmetric between the pty-based and leaf-based agent-detection paths.

isPtyRunningAgent (used when a live RuntimePtyWorktreeRecord exists) has an explicit fast path: isOpenCodeNativeTitle(openCodeMarkerTitle) && pty.launchAgent === 'opencode' returns true immediately. The parallel leaf-based branch inside isTerminalRunningAgent (used when the handle only resolves through the renderer graph leaf, not a PTY record) has no equivalent check — it always falls through to the foreground-process probe for an OpenCode-native title.

If RuntimeSyncedLeaf carries a comparable launchAgent field, this is an inconsistency that can make OpenCode-agent detection slower or less reliable on the leaf-based path. If it does not carry that field, the asymmetry is structural and expected — but that should be confirmed, not assumed.

Do you want me to check RuntimeSyncedLeaf's definition in src/shared/runtime-types.ts to confirm this?

Also applies to: 16794-16795, 16821-16831, 31705-31788, 37031-37032


26163-26226: 🗄️ Data Integrity & Integration

⚠️ Unverified finding
Sandbox verification was unavailable.

Verify that the deferred ZCode terminal's launchConfig/launchToken reflect the eventually-delivered prompt, not the empty-prompt startup plan.

createDeferredAgentTerminal builds the startup plan with an empty prompt (buildStartupForAgent(repo, opts.agent, undefined, opts.launchPreferences)) and forwards only env, launchConfig, and launchAgent to createTerminal. The actual task prompt is delivered later by sendTerminalAgentStartupPrompt, which types the real prompt-embedded launch command as terminal input via sendTerminalAgentPrompt — this path never updates pty.launchConfig or pty.launchToken.

Any later reader of pty.launchConfig (for example getAgentStatusLaunchConfigForPaneKey, used by the hook-token exchange, or a sleep/resume flow) sees the empty-prompt launch configuration, not the configuration that actually launched the agent with its task. If ZCode session resume or hook-driven relaunch relies on this stored launchConfig, resuming this pane could drop the original task context.

Please confirm whether src/main/zcode/hook-service.ts or src/main/zcode/interactive-client.ts read pty.launchConfig/getAgentStatusLaunchConfigForPaneKey for this pane in a way that depends on the prompt being present.


16449-16469: 🩺 Stability & Availability

⚠️ Unverified finding
Sandbox verification was unavailable.

Verify that callers handle rejection from worktree/repo resolution in resolveOrchestrationPromptDelivery.

resolveOrchestrationPromptDelivery calls this.resolveWorktreeSelector(id:${worktreeId}), which throws (for example selector_not_found) if the worktree no longer exists. This method is async and the exception surfaces as a promise rejection to the caller.

The orchestration dispatch code that calls this method (for example in orchestration-workers.ts or orchestration-worker-topology.ts) is not part of this file. Please confirm the caller wraps this call so a deleted/renamed worktree during dispatch does not crash the orchestration flow instead of failing that one dispatch gracefully.


37239-37252: 🎯 Functional Correctness

⚠️ Unverified finding
Sandbox verification was unavailable.

Fix the stale comment and verify the reused 'codex-interactive-prompt' reason code for the new permission-prompt heuristic.

The comment // Why: preserve the existing remote receipt value for mixed-version clients. does not describe the code below it. That code detects a generic "permission required"/"requires permission" prompt corroborated by two or more decision options ("allow once", "allow always", "reject", "deny"). This looks like a copy-pasted comment left over from an unrelated change.

Separately, this new heuristic labels the match with the 'codex-interactive-prompt' reason, but unlike the neighboring interactivePromptIndex block, it does not require any Codex-specific context (hasCodexInteractiveContext) before assigning that reason. A permission prompt from a different agent (for example ZCode's own interactive client, which can show comparable "Permission required... Allow once/Allow always" text) would be classified with a reason value named for Codex. If any consumer of RuntimeTerminalWaitBlockedReason renders Codex-specific text for this reason, this misattributes the source agent to the user.

Please confirm how RuntimeTerminalWaitBlockedReason consumers render 'codex-interactive-prompt', and consider a more neutral reason name for this generic permission-prompt pattern.

📝 Proposed fix for the stale comment
   if (permissionPromptIndex !== -1) {
     const permissionSegment = normalized.slice(permissionPromptIndex, permissionPromptIndex + 1_500)
     const decisionCount = ['allow once', 'allow always', 'reject', 'deny'].filter((choice) =>
       permissionSegment.includes(choice)
     ).length
     if (decisionCount >= 2) {
-      // Why: preserve the existing remote receipt value for mixed-version clients.
+      // Why: a generic "Permission required" prompt with 2+ decision options is a
+      // real blocking signal even outside Codex; reuse the interactive-prompt reason
+      // until a dedicated non-Codex reason value exists.
       candidates.push({ reason: 'codex-interactive-prompt', index: permissionPromptIndex })
     }
   }

12096-12101: 🎯 Functional Correctness

⚠️ Unverified finding
Sandbox verification was unavailable.

Verify parseTerminalKittyKeyboardFlags's return semantics before relying on the discarded parsed value.

This validates snapshot.modes?.kittyKeyboardFlags through parseTerminalKittyKeyboardFlags but then assigns the raw snapshot.modes.kittyKeyboardFlags field instead of the parser's return value. This is safe against a null/undefined snapshot.modes (the ternary's condition is falsy first, so the true branch never runs), but if parseTerminalKittyKeyboardFlags normalizes or clamps the value rather than doing a pure pass-through validity check, the stored kittyKeyboardFlags would not match what was validated.

Please confirm parseTerminalKittyKeyboardFlags is a pure validity check (returns the input unchanged or undefined). If it normalizes the value, use its return value directly instead of re-reading the raw field.


461-461: LGTM!

Also applies to: 16449-16469, 461-461


122-126: LGTM!

Also applies to: 2007-2007, 15544-15561


21839-21840: LGTM!

Also applies to: 21874-21874, 21996-22019, 22772-22793, 22995-22998, 23144-23164

src/main/runtime/rpc/methods/orchestration-workers.ts (1)

2-2: LGTM!

Also applies to: 67-73, 135-135, 158-165, 179-185, 247-257

src/main/runtime/rpc/methods/orchestration.test.ts (1)

2188-2221: LGTM!

Also applies to: 2262-2315, 2521-2539

src/main/runtime/rpc/methods/orchestration-workers-new-worktree.test.ts (1)

67-83: LGTM!

Also applies to: 195-241


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 12852d17-e1e9-4887-9749-d1b5761b3d2c

📥 Commits

Reviewing files that changed from the base of the PR and between cd3772b7dcb4febb3c2d07ae46d5a81398b93e29 and 4d51c6a3dcc5b065f32d059ab1fb0ed1a9d6d9c8.

📒 Files selected for processing (15)
  • src/main/runtime/orca-runtime.ts
  • src/main/runtime/rpc/methods/orchestration-worker-topology.ts
  • src/main/runtime/rpc/methods/orchestration-workers-new-worktree.test.ts
  • src/main/runtime/rpc/methods/orchestration-workers.ts
  • src/main/runtime/rpc/methods/orchestration.test.ts
  • src/main/zcode/interactive-client.test.ts
  • src/main/zcode/interactive-client.ts
  • src/preload/api-types.ts
  • src/preload/index.ts
  • src/renderer/src/i18n/locales/en.json
  • src/shared/agent-hook-listener.ts
  • src/shared/agent-hook-relay.ts
  • src/shared/tui-agent-config.ts
  • src/shared/tui-agent-startup.test.ts
  • src/shared/types.ts
🚧 Files skipped from review as they are similar to previous changes (7)
  • src/preload/api-types.ts
  • src/preload/index.ts
  • src/shared/agent-hook-relay.ts
  • src/renderer/src/i18n/locales/en.json
  • src/shared/agent-hook-listener.ts
  • src/shared/tui-agent-startup.test.ts
  • src/shared/types.ts

Comment thread src/main/runtime/rpc/methods/orchestration-worker-topology.ts Outdated
@guanbear
guanbear force-pushed the codex/zcode-first-class branch 3 times, most recently from ed977a9 to b6d01e0 Compare August 14, 2026 07:07
@guanbear

Copy link
Copy Markdown
Author

Rebased onto current upstream/main and added the live ZCode orchestration fixes found during end-to-end testing:

  • launch supervised interactive ZCode workers with --mode yolo
  • allow 30 seconds for the zcode-cli process to become observable
  • recognize the stable zcode-app-cli/bin/zcode.js -> zcode-cli process chain without release-version checks
  • record created terminals before TUI startup so failed launches remain visible to cleanup/recovery
  • remove the unrelated web Kimi hook stub introduced by the earlier branch
  • split lifecycle logic to remain within repository file-size gates

Validation after rebase: Node/CLI/Web typecheck passed, formatting passed, changed-code quality passed with zero new findings, and 23 affected test files passed (890 tests).

@guanbear

Copy link
Copy Markdown
Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Aug 14, 2026 •

Copy link
Copy Markdown
Contributor
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai

coderabbitai Bot commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

@guanbear

Copy link
Copy Markdown
Author

Fresh cross-model review after the latest rebase is clean: native Kiro / Claude Opus 5 High reviewed the full 180,518-byte branch bundle in 5 bounded passes after a clean TruffleHog scan. All 5 passes returned zero accepted/actionable findings; no fallback reviewer was used.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
src/main/runtime/orca-runtime.ts (1)

22282-22305: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract the duplicated deferStartupAgent terminal-creation block into a shared helper.

The same createDeferredAgentTerminal and warning-on-failure logic appears at three locations. Extract a shared private helper that accepts the worktree selector, agent options, and warning-message prefix, returning the created terminal or a structured failure. This keeps future fixes consistent across all deferred-agent startup paths.


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e4b6b119-f9f3-441e-80fc-20b942cf498a

📥 Commits

Reviewing files that changed from the base of the PR and between b6d36c2 and b6d01e0a93def4d2a7668826a6791dc37f1e926a.

📒 Files selected for processing (90)
  • README.md
  • config/tsconfig.cli.json
  • docs/readme/README.es.md
  • docs/readme/README.fr.md
  • docs/readme/README.ja.md
  • docs/readme/README.ko.md
  • docs/readme/README.pt.md
  • docs/readme/README.zh-CN.md
  • mobile/src/tasks/mobile-tui-agents.ts
  • src/main/agent-hooks/managed-agent-hook-registry.ts
  • src/main/agent-hooks/managed-hook-local-filesystem.test.ts
  • src/main/agent-hooks/remote-hook-service-installers.test.ts
  • src/main/agent-hooks/remote-managed-hook-installers.ts
  • src/main/codex-accounts/service.test.ts
  • src/main/ipc/agent-hooks.test.ts
  • src/main/ipc/agent-hooks.ts
  • src/main/ipc/preflight.test.ts
  • src/main/ipc/zcode-hook-status-ipc.ts
  • src/main/providers/agent-foreground-process-zcode.test.ts
  • src/main/rate-limits/service.test.ts
  • src/main/rate-limits/service.ts
  • src/main/rate-limits/zcode-usage-fetcher.test.ts
  • src/main/rate-limits/zcode-usage-fetcher.ts
  • src/main/runtime/orca-runtime.ts
  • src/main/runtime/orchestration/preamble.test.ts
  • src/main/runtime/orchestration/preamble.ts
  • src/main/runtime/rpc/methods/client-ui-schemas.ts
  • src/main/runtime/rpc/methods/orchestration-federation-setup.ts
  • src/main/runtime/rpc/methods/orchestration-worker-lifecycle.ts
  • src/main/runtime/rpc/methods/orchestration-worker-setup-gate.ts
  • src/main/runtime/rpc/methods/orchestration-worker-start-receipt.ts
  • src/main/runtime/rpc/methods/orchestration-worker-topology.ts
  • src/main/runtime/rpc/methods/orchestration-workers-new-worktree.test.ts
  • src/main/runtime/rpc/methods/orchestration-workers.ts
  • src/main/runtime/rpc/methods/orchestration.test.ts
  • src/main/zcode/hook-service.test.ts
  • src/main/zcode/hook-service.ts
  • src/main/zcode/interactive-client.test.ts
  • src/main/zcode/interactive-client.ts
  • src/main/zcode/zcode-hook-config.test.ts
  • src/main/zcode/zcode-hook-config.ts
  • src/preload/api/agent-hook-api.ts
  • src/preload/index.ts
  • src/renderer/src/components/settings/appearance-status-bar-grok-toggle-search.ts
  • src/renderer/src/components/settings/appearance-status-bar-search.ts
  • src/renderer/src/components/stats/GrokUsagePane.test.tsx
  • src/renderer/src/components/status-bar/StatusBar.tsx
  • src/renderer/src/components/status-bar/status-bar-agent-gating.test.ts
  • src/renderer/src/components/status-bar/status-bar-agent-gating.ts
  • src/renderer/src/components/status-bar/status-bar-provider-visibility.test.ts
  • src/renderer/src/components/status-bar/status-bar-provider-visibility.ts
  • src/renderer/src/components/status-bar/tooltip.tsx
  • src/renderer/src/components/status-bar/usage-error-copy.ts
  • src/renderer/src/components/status-bar/usage-provider-settings-target.ts
  • src/renderer/src/components/terminal-pane/title-agent-identity.test.ts
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/i18n/locales/es.json
  • src/renderer/src/i18n/locales/ja.json
  • src/renderer/src/i18n/locales/ko.json
  • src/renderer/src/i18n/locales/zh.json
  • src/renderer/src/lib/agent-catalog.tsx
  • src/renderer/src/lib/agent-status.ts
  • src/renderer/src/store/slices/rate-limits.ts
  • src/renderer/src/store/slices/ui.test.ts
  • src/renderer/src/store/slices/ui.ts
  • src/renderer/src/web/web-preload-api.ts
  • src/shared/agent-hook-listener.test.ts
  • src/shared/agent-hook-listener.ts
  • src/shared/agent-hook-relay.ts
  • src/shared/agent-hook-types.ts
  • src/shared/agent-kind.ts
  • src/shared/agent-name-token-match.ts
  • src/shared/agent-node-entrypoint-identities.ts
  • src/shared/agent-process-recognition.test.ts
  • src/shared/agent-session-resume.ts
  • src/shared/agent-status-types.ts
  • src/shared/agent-type-label.ts
  • src/shared/local-agent-install-dir-detection.ts
  • src/shared/persisted-ui-state-types.ts
  • src/shared/rate-limit-types.test.ts
  • src/shared/rate-limit-types.ts
  • src/shared/skills-cli-agent-keys.ts
  • src/shared/status-bar-defaults.ts
  • src/shared/telemetry-events.ts
  • src/shared/tui-agent-config.ts
  • src/shared/tui-agent-display-names.ts
  • src/shared/tui-agent-selection.ts
  • src/shared/tui-agent-startup.test.ts
  • src/shared/tui-agent.ts
  • src/shared/ui-chrome-types.ts
🚧 Files skipped from review as they are similar to previous changes (75)
  • docs/readme/README.fr.md
  • src/shared/status-bar-defaults.ts
  • docs/readme/README.ja.md
  • src/renderer/src/store/slices/ui.test.ts
  • src/shared/telemetry-events.ts
  • docs/readme/README.ko.md
  • docs/readme/README.es.md
  • src/shared/agent-hook-listener.test.ts
  • src/main/agent-hooks/remote-managed-hook-installers.ts
  • src/main/ipc/preflight.test.ts
  • src/shared/local-agent-install-dir-detection.ts
  • docs/readme/README.pt.md
  • src/shared/agent-type-label.ts
  • src/renderer/src/i18n/locales/es.json
  • src/main/codex-accounts/service.test.ts
  • src/shared/agent-status-types.ts
  • src/main/agent-hooks/managed-hook-local-filesystem.test.ts
  • src/renderer/src/components/status-bar/tooltip.tsx
  • src/shared/tui-agent-display-names.ts
  • mobile/src/tasks/mobile-tui-agents.ts
  • src/renderer/src/components/stats/GrokUsagePane.test.tsx
  • README.md
  • src/shared/rate-limit-types.test.ts
  • src/main/rate-limits/zcode-usage-fetcher.test.ts
  • src/renderer/src/components/status-bar/status-bar-agent-gating.ts
  • src/main/runtime/rpc/methods/client-ui-schemas.ts
  • src/main/zcode/interactive-client.test.ts
  • src/shared/agent-hook-types.ts
  • src/main/zcode/zcode-hook-config.test.ts
  • src/shared/rate-limit-types.ts
  • src/shared/tui-agent-selection.ts
  • src/renderer/src/store/slices/rate-limits.ts
  • src/shared/agent-name-token-match.ts
  • src/renderer/src/components/status-bar/status-bar-provider-visibility.test.ts
  • src/main/ipc/zcode-hook-status-ipc.ts
  • src/shared/agent-session-resume.ts
  • src/main/rate-limits/service.test.ts
  • src/renderer/src/components/status-bar/status-bar-agent-gating.test.ts
  • src/renderer/src/store/slices/ui.ts
  • src/renderer/src/components/settings/appearance-status-bar-search.ts
  • config/tsconfig.cli.json
  • src/main/zcode/interactive-client.ts
  • src/main/runtime/orchestration/preamble.ts
  • src/renderer/src/components/status-bar/usage-error-copy.ts
  • src/renderer/src/components/terminal-pane/title-agent-identity.test.ts
  • src/renderer/src/lib/agent-catalog.tsx
  • src/shared/tui-agent-startup.test.ts
  • src/renderer/src/components/status-bar/StatusBar.tsx
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/components/status-bar/status-bar-provider-visibility.ts
  • src/main/ipc/agent-hooks.ts
  • src/renderer/src/web/web-preload-api.ts
  • src/main/zcode/hook-service.test.ts
  • docs/readme/README.zh-CN.md
  • src/shared/agent-kind.ts
  • src/main/ipc/agent-hooks.test.ts
  • src/main/zcode/zcode-hook-config.ts
  • src/renderer/src/lib/agent-status.ts
  • src/renderer/src/components/status-bar/usage-provider-settings-target.ts
  • src/preload/index.ts
  • src/main/agent-hooks/remote-hook-service-installers.test.ts
  • src/renderer/src/i18n/locales/zh.json
  • src/main/runtime/rpc/methods/orchestration-workers-new-worktree.test.ts
  • src/main/agent-hooks/managed-agent-hook-registry.ts
  • src/shared/tui-agent-config.ts
  • src/shared/agent-hook-relay.ts
  • src/renderer/src/components/settings/appearance-status-bar-grok-toggle-search.ts
  • src/main/rate-limits/zcode-usage-fetcher.ts
  • src/main/runtime/rpc/methods/orchestration.test.ts
  • src/main/rate-limits/service.ts
  • src/shared/agent-hook-listener.ts
  • src/shared/skills-cli-agent-keys.ts
  • src/renderer/src/i18n/locales/ko.json
  • src/main/zcode/hook-service.ts
  • src/renderer/src/i18n/locales/ja.json

Comment thread src/main/runtime/rpc/methods/orchestration-worker-setup-gate.ts Outdated
@guanbear

Copy link
Copy Markdown
Author

Thanks for triaging this! The open CodeRabbit finding is addressed in c7f6fe0d: setup stages are no longer recorded as settled unless the setup receipt actually reached a terminal state.

The branch is on the large side, so if it helps review I'm happy to split it — e.g. (1) ZCode agent catalog/launch + hooks/status and (2) orchestration worker support. Just let me know what shape works best. CI doesn't run from my fork, but the touched suites (src/main/runtime/rpc/methods, rate-limits, status-bar) pass locally with typecheck clean.

@guanbear

Copy link
Copy Markdown
Author

Added the final ZCode interactive TUI readiness and structured-output bridge in 7baffe1e, on top of the existing setup-receipt fix.

The PR description now includes the full live Orca -> ZCode TUI -> provider session -> SQLite transcript -> worker_done -> archived release evidence. Final local checks: Node/CLI/Web typecheck clean; targeted native and type-aware lint clean; 60 affected suites with 1,453 passing and 1 skipped; post-review owner-boundary rerun with 1,409 passing and 1 skipped. TruffleHog was clean.

Independent review found and we fixed two issues before push: explicit .sqlite paths being discarded, and ZCode SessionStart creating a false status row instead of provider-session-only metadata. The final immutable bundle was reviewed clean; Codex fallback was not used.

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Aug 14, 2026 •

Copy link
Copy Markdown
Contributor

@guanbear, I will review the latest changes, including the interactive TUI readiness and structured-output bridge.


✏️ Learnings added
Learnt from: guanbear
URL: https://github.com/stablyai/orca/pull/13965

Timestamp: 2026-08-14T10:37:19.142Z
Learning: For the ZCode integration in `stablyai/orca` PR `#13965`, explicit `.sqlite` transcript paths must be retained. ZCode `SessionStart` must store provider-session-only metadata and must not create a status row.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.


🧠 Learnings used
Learnt from: OrcaWin
Repo: stablyai/orca PR: 11271
File: src/main/runtime/orca-runtime.ts:10392-10403
Timestamp: 2026-07-29T06:55:53.254Z
Learning: In `src/main/runtime/orca-runtime.ts`, `OrcaRuntimeService.verifyOrchestrationCompatibilityCaller` must permit restored or adopted PTYs whose live terminal authority has no `launchTokenHash`: after restart, durable hydrated agent-hook commitments attest the caller-provided launch token, while exact pane key, host scope, terminal handle, and process-incarnation validation bind that proof to the retained live worker. The optional runtime `terminal.launchTokenHash` is an additional check only when available.

Learnt from: guanbear
Repo: stablyai/orca PR: 13965
File: src/main/runtime/rpc/methods/orchestration-workers.ts:135-135
Timestamp: 2026-08-12T15:36:45.442Z
Learning: For local `orchestration.workerStart` in `src/main/runtime/rpc/methods/orchestration-worker-start-validation.ts`, `prepareLocalWorkerStart` rejects `--terminal` together with `--agent`. An explicit terminal reuses its recognized running agent and uses agent-input delivery; it cannot select ZCode's startup-command delivery.
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 768fcb67-296d-4324-89bd-38a22000b6e2

📥 Commits

Reviewing files that changed from the base of the PR and between b6d01e0a93def4d2a7668826a6791dc37f1e926a and 7baffe1ea8fce771f6834e07ee72317f6dbdeb0c.

📒 Files selected for processing (29)
  • src/main/ai-vault/session-scanner-opencode-sqlite-worker-client.ts
  • src/main/ai-vault/session-scanner-opencode-sqlite-worker-entry.ts
  • src/main/ai-vault/session-scanner-opencode-sqlite-worker-protocol.ts
  • src/main/ai-vault/session-scanner-opencode-sqlite-worker-spawn.ts
  • src/main/ai-vault/zcode-sqlite-transcript.test.ts
  • src/main/ai-vault/zcode-sqlite-transcript.ts
  • src/main/native-chat/session-file-resolver.ts
  • src/main/native-chat/transcript-reader.ts
  • src/main/native-chat/transcript-tail-reader.ts
  • src/main/native-chat/transcript-watch.ts
  • src/main/native-chat/zcode-transcript-watch.ts
  • src/main/runtime/orca-runtime.test.ts
  • src/main/runtime/orca-runtime.ts
  • src/main/runtime/orchestration/worker-transcript-read.ts
  • src/main/runtime/rpc/methods/orchestration-federation-setup.test.ts
  • src/main/runtime/rpc/methods/orchestration-federation-setup.ts
  • src/main/runtime/rpc/methods/orchestration-worker-setup-gate.test.ts
  • src/main/runtime/rpc/methods/orchestration-worker-setup-gate.ts
  • src/main/runtime/rpc/methods/orchestration-workers.ts
  • src/main/runtime/rpc/methods/orchestration.test.ts
  • src/main/zcode/interactive-client.test.ts
  • src/main/zcode/interactive-client.ts
  • src/shared/agent-hook-listener.test.ts
  • src/shared/agent-hook-listener.ts
  • src/shared/draft-paste-ready-scanner.test.ts
  • src/shared/draft-paste-ready-scanner.ts
  • src/shared/native-chat-agent-support.test.ts
  • src/shared/native-chat-agent-support.ts
  • src/shared/tui-agent-config.ts
🚧 Files skipped from review as they are similar to previous changes (5)
  • src/shared/agent-hook-listener.test.ts
  • src/main/runtime/rpc/methods/orchestration-federation-setup.ts
  • src/shared/agent-hook-listener.ts
  • src/main/runtime/rpc/methods/orchestration.test.ts
  • src/main/runtime/orca-runtime.ts

Comment thread src/main/native-chat/transcript-watch.ts Outdated
Comment thread src/shared/draft-paste-ready-scanner.ts Outdated
@guanbear

Copy link
Copy Markdown
Author

Addressed both latest CodeRabbit findings in 8f009208:

  • moved the blank-session guard ahead of the ZCode transcript backend, with a whitespace-only ZCode regression test
  • strengthened TUI readiness to require the real ordered PTY sequence 2004h -> 2026h -> 2026l -> 25h, with negative tests for missing bracketed paste and cursor output before frame exit

Verification after the fixes: 41 suites passed, 1,318 tests passed, 1 skipped; Node/CLI/Web typecheck passed; targeted native and type-aware lint passed; TruffleHog passed; isolated GLM-5.2 Max review of the review-fix bundle returned clean. Both review threads are resolved.

@guanbear

Copy link
Copy Markdown
Author

@coderabbitai review

@greptile-apps

greptile-apps Bot commented Aug 31, 2026

Copy link
Copy Markdown

Greptile Summary

Adds ZCode as a first-class agent across launch selection, process recognition, permissions, managed local and SSH hooks, lifecycle normalization, presentation, and telemetry.

  • Registers ZCode throughout shared agent contracts and client-facing catalogs.
  • Installs authenticated loopback lifecycle hooks while preserving unrelated user hook definitions.
  • Normalizes Claude-compatible ZCode events into Orca’s shared status model.
  • Adds focused coverage for startup, permissions, hook configuration, remote installation, event routing, and process identity.

Confidence Score: 5/5

The PR appears safe to merge with no concrete blocking or independently actionable non-blocking defects identified.

The ZCode integration keeps its launch, hook transport, event attribution, configuration preservation, and client-facing contracts aligned, and the investigated edge cases did not establish a reachable changed-code failure.

Important Files Changed

Filename Overview
src/main/zcode/hook-service.ts Implements local and SSH managed-hook installation, status inspection, script refresh, and local removal with enabled-state restoration.
src/main/zcode/zcode-hook-config.ts Adds idempotent ZCode hook configuration merging and cleanup while retaining unrelated user-authored entries.
src/shared/agent-hook-listener/providers/zcode-events.ts Attributes ZCode’s Claude-compatible lifecycle events to the ZCode agent type.
src/shared/agent-hook-listener/provider-event-routing.ts Adds ZCode new-turn and Claude-compatible tool-field routing.
src/shared/tui-agent-config-zcode.ts Extracts the existing ZCode executable, process identity, and prompt-delivery profile into a dedicated module.
src/main/agent-hooks/remote-managed-hook-installers.ts Registers ZCode’s installer in the allowlisted SSH managed-hook installation flow.
src/shared/agent-session-resume.ts Captures ZCode’s provider session identifier without advertising unsupported resume behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Agent picker] --> B[ZCode launch profile]
  B --> C[zcode process]
  C --> D[Managed ZCode hooks]
  D --> E[Authenticated loopback listener]
  E --> F[ZCode event normalizer]
  F --> G[Shared agent status]
  G --> H[Desktop, web, and mobile presentation]
Loading

Reviews (1): Last reviewed commit: "refactor(zcode): keep integration within..." | Re-trigger Greptile

@guanbear

guanbear commented Aug 31, 2026 •

Copy link
Copy Markdown
Author

Hi @justforyoudear — thank you so much for the offer, and for sharing your Windows setup; that's exactly the platform this PR could use more eyes on. No rush or obligation at all — anything you try helps.

Whenever convenient, the current head can be tested without waiting for merge:

git clone https://github.com/stablyai/orca.git && cd orca
gh pr checkout 13965
pnpm install && pnpm dev

You already know the areas worth a look — detection, process recognition, managed hooks, and status reporting on your setup. Even a quick "works on my machine (Windows + your shell)" is valuable signal, and if anything looks off, just note it here and I'll take it from there.

Thanks again for helping push this forward! 🙏

@justforyoudear

Copy link
Copy Markdown

Windows validation — all three checkpoints from the testing invitation pass. Environment and findings below.

Environment

  • Windows 11 10.0.26200 (win32 x64), shell: Git Bash (MSYS2) with PowerShell available
  • node v22.23.2, pnpm 12.0.0 (repo-pinned), electron-vite dev build of this PR (1dbe685d)
  • zcode: zcode-app-cli 3.10.1-17 from npm (global, wraps the official desktop engine zcode.cjs 0.16.5; binary on PATH as zcode)

1. Detection & launch — ✅

  • ZCode shows up in the worktree-create agent picker (top suggestion).
  • Creating a worktree with agent=zcode worked; the terminal tab was recognized under the zcode-cli process identity (tab title zcode-cli), TUI launched in the fresh worktree.
  • Note: the fresh dev profile defaults to Manual permission mode, so no --mode yolo was appended at launch. Happy to flip to Yolo and re-verify the flag mapping if you want that path exercised.

2. Managed hooks — ✅

  • First launch wrote to ~/.zcode/cli/config.json: hooks.enabled=true with 6 events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Stop), each a PowerShell wrapper that invokes C:\Users\jj\.orca\agent-hooks\zcode-hook.cmd (975 B, created 18:12) plus zcode-hook-state.json (62 B) — same layout as the claude/codex/gemini hooks.
  • Haven't yet done the relaunch/no-dup/no-revert check; will do on the next launch in this dev instance.

3. Status reporting — ✅

  • While running: tab title Working ZC | <prompt>, sidebar row Working ZC | <prompt> - ZCode now, worktree card badge Working.
  • After the session was stopped: state transitioned live to Interrupted by user on the same row. (Screenshot saved locally; can post it here if useful.)

One anomaly to look at

  • Dev log during worktree creation: [worktree-create] Failed to create the startup terminal for C:/Users/jj/orca/workspaces/orca-demo/zcode-test: selector_not_found — yet the agent terminal did launch and everything above worked. Possibly a transient during the create flow; flagging in case it's a real path.

Thanks for the branch — happy to test more (Yolo path, relaunch hook dedup, and the follow-up #16227/#16228 once they land).

@justforyoudear

Copy link
Copy Markdown

One more user-side finding from the Windows pass, worth recording for Orca+zcode workflows (not a PR bug — heads-up for docs/testing notes):

ZCode uses two config stores that don't auto-sync: the desktop app reads ~/.zcode/v2/config.json, while the CLI TUI (which is what runs inside Orca) reads ~/.zcode/cli/config.json. Custom providers configured on the desktop side (in my case an OpenAI-compatible endpoint at https://opencode.ai/zen/go/v1 with deepseek-v4-flash) do not show up in the model picker of the zcode TUI launched by Orca until ported into the CLI config manually. Separately, the engine catalog's built-in opencode-go entry requires OPENCODE_API_KEY in the environment to be selectable — without it the model rows are grayed out.

Practical takeaway: for Orca + zcode, configure providers/models in ~/.zcode/cli/config.json — that's the file the in-Orca TUI reads. Carried-over from my earlier report; happy to fold this into a docs PR if useful.

@surajmandalcell

Copy link
Copy Markdown

This would be great if merged, basically giving us 50% more quota if we go by their documentation 👏

@guanbear
guanbear force-pushed the codex/zcode-first-class branch from 1dbe685 to d9500a4 Compare September 2, 2026 06:35
@guanbear

guanbear commented Sep 2, 2026

Copy link
Copy Markdown
Author

Updated and rebased onto the latest main. I added a compatibility fallback for older SSH relays: if a relay rejects the expanded managed-hook allowlist with invalid_managed_hook_agents, the client retries without zcode, preserving installation for the hook targets that relay supports. A focused regression test covers the mixed-version path; the SSH managed-hook tests and Node typecheck pass.

@guanbear

guanbear commented Sep 2, 2026

Copy link
Copy Markdown
Author

Hi @justforyoudear — thank you so much for the thorough Windows validation. This is exceptionally helpful, and the detailed environment and hook information makes the result especially actionable.

It’s great to have confirmation that detection and launch, managed hooks, and live status transitions all work on Windows. I’ve also noted the selector_not_found message. Since the terminal still launched successfully, it may be a transient worktree-creation race rather than a ZCode-specific failure, but it is still worth tracking separately.

The two-config-store finding is also a valuable heads-up. I agree that it should not expand the scope of this core integration PR, but it would make a useful documentation note for Orca + ZCode users. A small follow-up docs PR would be very welcome if you’re interested, but absolutely no obligation—you’ve already contributed a lot here.

I’ve since rebased the branch and added a mixed-version SSH relay compatibility fallback. Your results against 1dbe685d remain directly relevant because the core Windows integration is unchanged. If you happen to test the current head again, the single most useful additional check would be the relaunch/no-duplicate/no-revert hook behavior; there’s no need to repeat the full pass or test Yolo mode unless you want to.

Thanks again for spending the time on this and for helping move the PR forward! 🙏

@guanbear

guanbear commented Sep 7, 2026

Copy link
Copy Markdown
Author

Gentle ping for review when someone has a cycle 🙂

Quick recap since the thread has grown:

  • The branch is current with main and conflict-free; the latest update added the compatibility fallback for older SSH relays (retry without zcode when a relay rejects the expanded managed-hook allowlist), with a regression test for the mixed-version path.
  • Windows validation is in thanks to @justforyoudear — detection/launch, managed hooks, and live status transitions all confirmed working, with detailed environment notes.
  • A couple of community +1s above as well.

@Jinwoo-H is anything blocking review here, or anything you'd like scoped differently (e.g. split further) to make it easier to land? Happy to adjust.

@caiolrm

caiolrm commented Sep 14, 2026

Copy link
Copy Markdown

Great addition, looking forward to this.

Is there a different way to use zcode in orca today?

@guanbear

Copy link
Copy Markdown
Author

Hi @caiolrm — thanks!

Unfortunately not today: zcode isn't in the built-in agent catalog, and the custom agent presets from #2284 haven't shipped yet, so there's no first-class way to register it. The only workaround is launching the zcode CLI manually in a plain terminal pane — the agent itself works fine that way, but you lose everything this PR wires up: managed hooks, live status reporting in the pane and status bar, and the launch/permission integration (@justforyoudear described the same workaround on Windows upthread).

If you'd like it before review + merge lands, the branch builds locally — same steps as upthread (gh pr checkout 13965 then pnpm install && pnpm dev). Would be glad to hear how it behaves on your setup.

@kacperpaczos

Copy link
Copy Markdown

Hey, would love to see this land in Orca.

Right now I run GLM through Claude Code pointed at the Z.ai endpoint. It works, but Orca treats it as a plain terminal – no idea if the agent is working, waiting or done. With a few workers running in parallel that gets annoying. This PR fixes exactly that, and since Z.AI Coding Plan limits are already tracked (#18556), ZCode being on the agent list is the obvious next step.

@Jinwoo-H any chance this can get a review? Happy to test further builds.

@JulienJBO

Copy link
Copy Markdown

Can't wait... So painful without that

@guanbear
guanbear force-pushed the codex/zcode-first-class branch from d9500a4 to 846bb93 Compare September 20, 2026 03:29
@guanbear

Copy link
Copy Markdown
Author

Rebased onto current main (1,516 commits of drift). Adaptations: WellKnownAgentType now takes upstream's TuiAgent-derived form inside the extracted agent-status-agent-type.ts module (zcode flows through TuiAgent), and the SSH relay test keeps both upstream's Claude-version forwarding case and the older-relay Zcode retry case. Validation: Node + Web typechecks pass, zcode/relay/vendors/mobile suites 100/100, changed-file oxlint clean, size ratchet clean.

@guanbear
guanbear force-pushed the codex/zcode-first-class branch from 846bb93 to 30ecf5f Compare September 20, 2026 09:21
@guanbear

Copy link
Copy Markdown
Author

Refreshed onto current upstream main (ee61e3bd4) while preserving the older-SSH-relay compatibility path.

Validation on the refreshed core stack:

  • Node/CLI/Web/mobile TypeScript projects pass typecheck.
  • ssh-relay-session-managed-hooks.test.ts: 3/3 pass, including retry without ZCode when an older relay rejects the expanded hook allowlist.
  • The PR remains the first-class agent core only; prompt-only Desktop behavior, orchestration/transcripts, and usage reporting remain in their documented follow-ups.

@nwparker

Copy link
Copy Markdown
Contributor

ZCode harness is green — please try it and comment on #22464

Test instructions: #22464 (comment)

Build: https://github.com/stablyai/orca-adhoc/releases/tag/v1.4.210-adhoc.20260923230858
orca-macos-arm64.dmg · orca-macos-x64.dmg · orca-windows-setup.exe (unsigned on Windows — SmartScreen → More info → Run anyway)

CI is now fully green (31/31). Please comment on #22464 with what you find — whether it works or breaks. Include your OS and zcode --version. Once a few people confirm it works on real machines, we approve and merge.

The two gaps I can't close myself:

  • A live session with a real Z.ai account. My test box has no model configured, so I proved the status pipeline with ZCode's own hook payloads rather than real turns. Nobody has watched an actual ZCode session drive Orca end to end.
  • Windows, Linux, and SSH on real hardware. Covered by contract tests, never run on a real host.

@nwparker

Copy link
Copy Markdown
Contributor

Closing this one — ZCode landed in #22464, now on main.

I want to be straight that your PR got there first on the part that mattered most. You worked out that the install target is ~/.zcode/cli/config.json with the seven hooks.events entries, and that ZCode's Claude-compatible payloads meant it could route through the existing vendor path rather than needing a new parser. I reached the same conclusions independently and only realised afterwards, reading your diff, that you'd already mapped it — including the SSH install and the zcode-cli process identity.

What let #22464 finish was timing, not insight: Z.ai open-sourced the CLI in the interim, so I could check the assumptions your PR had to take on faith. The big one was the hooks blocker — DefaultRuntimeConfig ships hooks.enabled: false, so registering events was never going to be enough on its own. Your installer had the right shape and would have worked with that one flag flipped.

You're credited in the PR body and the issue. Thank you for the groundwork — and please do come back for the follow-ups if you're interested; there's more below on #14556.

@guanbear

Copy link
Copy Markdown
Author

@nwparker Thank you for the thoughtful closeout and for crediting the earlier work. Your source-backed note about hooks.enabled clarified the extra step needed for the first-class integration.

I followed the scope you suggested for the remaining work: #23513 is AI Vault only on current main, and #23520 is the separate quota meter. Both are now ready for review. #23520 also has a successful read-only live quota fetch; its remaining UI visual check is stated in the PR body. I appreciate the detailed guidance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: Add ZCode (Z.ai / GLM-5.2) as a first-class supported agent

9 participants