diff --git a/src/main/ipc/preflight.ts b/src/main/ipc/preflight.ts index e8a678b40cd1..581a7a86c66a 100644 --- a/src/main/ipc/preflight.ts +++ b/src/main/ipc/preflight.ts @@ -16,6 +16,7 @@ import type { // ../preflight/agent-detection so the runtime can call it without ipcMain. // Re-exported here so existing importers of `ipc/preflight` keep working. export * from '../preflight/agent-detection' +import { readZCodeInteractiveCapability } from '../zcode/interactive-capability' export function registerPreflightHandlers(): void { ipcMain.handle( @@ -32,6 +33,12 @@ export function registerPreflightHandlers(): void { detectInstalledAgentsWithShellPathHydration(args) ) + // Why here: this is the one place that already answers "what can the installed agent CLIs + // do", and the probe is cached, so a repeat launch costs nothing. + ipcMain.handle('preflight:zcodeInteractiveCapability', async () => + readZCodeInteractiveCapability() + ) + ipcMain.handle('preflight:refreshAgents', async (_event, args?: PreflightRuntimeContext) => { return refreshShellPathAndDetectAgents(args) }) diff --git a/src/main/runtime/__fixtures__/zcode-missing-tui.meta.json b/src/main/runtime/__fixtures__/zcode-missing-tui.meta.json new file mode 100644 index 000000000000..5298b50be5e0 --- /dev/null +++ b/src/main/runtime/__fixtures__/zcode-missing-tui.meta.json @@ -0,0 +1,9 @@ +{ + "capturedAt": "2026-09-24T22:11:40.957Z", + "platform": "darwin", + "command": ["zcode"], + "cols": 120, + "rows": 32, + "note": "ZCode desktop-bundled runtime 0.16.5 (no @zcode/tui); interactive launch fails immediately", + "exitCode": 1 +} diff --git a/src/main/runtime/__fixtures__/zcode-missing-tui.txt b/src/main/runtime/__fixtures__/zcode-missing-tui.txt new file mode 100644 index 000000000000..a8a46b3ebbbc --- /dev/null +++ b/src/main/runtime/__fixtures__/zcode-missing-tui.txt @@ -0,0 +1 @@ +Error: Cannot find package '@zcode/tui' imported from /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs diff --git a/src/main/zcode/interactive-capability.live.test.ts b/src/main/zcode/interactive-capability.live.test.ts new file mode 100644 index 000000000000..09ee238d5b80 --- /dev/null +++ b/src/main/zcode/interactive-capability.live.test.ts @@ -0,0 +1,31 @@ +import { existsSync } from 'node:fs' +import { describe, expect, it, beforeEach } from 'vitest' +import { + readZCodeInteractiveCapability, + _resetZCodeInteractiveCapabilityForTests +} from './interactive-capability' + +// Two real ZCode builds on this machine: the desktop app's bundled runtime (no TUI) and a +// CLI built from zai-org/ZCode (has TUI). Skipped anywhere they are absent. +const WITHOUT_TUI = '/tmp/zcode-bin-notui/zcode' +const WITH_TUI = '/tmp/zcode-bin-tui/zcode' +const bothPresent = existsSync(WITHOUT_TUI) && existsSync(WITH_TUI) +const describeLive = bothPresent ? describe : describe.skip + +beforeEach(() => _resetZCodeInteractiveCapabilityForTests()) + +describeLive('readZCodeInteractiveCapability against real ZCode builds', () => { + it("reports missing-tui for the desktop app's bundled runtime", async () => { + await expect(readZCodeInteractiveCapability(WITHOUT_TUI)).resolves.toBe('missing-tui') + }, 30_000) + + it('reports interactive for a CLI built from source', async () => { + await expect(readZCodeInteractiveCapability(WITH_TUI)).resolves.toBe('interactive') + }, 30_000) + + it('fails open when the command does not exist', async () => { + await expect(readZCodeInteractiveCapability('/tmp/definitely-not-zcode')).resolves.toBe( + 'unknown' + ) + }, 30_000) +}) diff --git a/src/main/zcode/interactive-capability.ts b/src/main/zcode/interactive-capability.ts new file mode 100644 index 000000000000..d5b65851dae5 --- /dev/null +++ b/src/main/zcode/interactive-capability.ts @@ -0,0 +1,84 @@ +import { runProcess } from '../../shared/child-process/run-process' +import { + isZCodeMissingTuiOutput, + type ZCodeInteractiveCapability +} from '../../shared/zcode-missing-tui' + +/** + * Asking a `zcode` build whether it can open a session, before Orca opens a pane for it. + * + * Why a deliberate probe and not a rule over the pane's output: the failure lands within + * about half a second of spawn, so anything watching a live stream races it. Asking the + * question directly is race-free, answerable once, and can run before the user ever sees a + * terminal. + * + * Why running it is the only way to ask: ZCode's `--version` and `doctor` are identical + * between a build that has the TUI and one that does not (measured on both), because the + * TUI is only ever touched on the `tui` command path — `runTuiCommand` calls + * `loadTuiRuntime()` before anything else, and every other subcommand returns without it. + * + * That same ordering is what makes the answer unambiguous. With no TTY: + * - a build WITHOUT the TUI fails in `loadTuiRuntime` → Node's module-resolution error + * - a build WITH the TUI loads, then `runTui` rejects the missing TTY + * so the module error is present exactly when the terminal UI is absent. + * + * All three shipping shapes land correctly: an npm/node-bundle install resolves + * `@zcode/tui` as a real package (it is an esbuild external, never inlined); a SEA build + * always carries the TUI as embedded assets; and the desktop app's bundled runtime carries + * neither, which is the case worth catching. + */ +export type { ZCodeInteractiveCapability } + +// Why bounded: the answer arrives in well under a second on both builds measured. A hang +// means something unexpected, and an unexpected build must not be called broken. +const PROBE_TIMEOUT_MS = 6_000 + +let cached: ZCodeInteractiveCapability | undefined +let inFlight: Promise | undefined + +export function _resetZCodeInteractiveCapabilityForTests(): void { + cached = undefined + inFlight = undefined +} + +async function probe(command: string): Promise { + try { + const result = await runProcess({ + program: command, + args: [], + // Why an explicit empty stdin: the child gets a pipe at EOF rather than a terminal, so + // a build that HAS the TUI declines instead of taking the probe interactive. + input: '', + timeoutMs: PROBE_TIMEOUT_MS + }) + if (result.timedOut) { + return 'unknown' + } + return isZCodeMissingTuiOutput(`${result.stderr}\n${result.stdout}`) + ? 'missing-tui' + : 'interactive' + } catch { + // Why fail open: a spawn that never ran says nothing about the build. Reporting + // 'missing-tui' here would accuse a perfectly good CLI on an unrelated failure. + return 'unknown' + } +} + +/** Whether this `zcode` can open a session. Answered once per Orca run. */ +export function readZCodeInteractiveCapability( + command = 'zcode' +): Promise { + if (cached !== undefined) { + return Promise.resolve(cached) + } + inFlight ??= probe(command).then((verdict) => { + // Why only remember a definitive answer: 'unknown' is usually transient (a timeout, a + // spawn refused under load), and caching it would suppress the notice for the session. + if (verdict !== 'unknown') { + cached = verdict + } + inFlight = undefined + return verdict + }) + return inFlight +} diff --git a/src/preload/api/preflight-api.ts b/src/preload/api/preflight-api.ts index 8535bb35f8c8..d8582af13a74 100644 --- a/src/preload/api/preflight-api.ts +++ b/src/preload/api/preflight-api.ts @@ -1,3 +1,4 @@ +import type { ZCodeInteractiveCapability } from '../../shared/zcode-missing-tui' import type { ProjectExecutionRuntimeResolution } from '../../shared/project-execution-runtime' import type { PathSource, @@ -46,6 +47,8 @@ export type PreflightRuntimeContext = { export type PreflightApi = { check: (args?: PreflightRuntimeContext & { force?: boolean }) => Promise detectAgents: (args?: PreflightRuntimeContext) => Promise + /** Whether the installed `zcode` can open a session; cached in main per run. */ + zcodeInteractiveCapability: () => Promise refreshAgents: (args?: PreflightRuntimeContext) => Promise detectRemoteAgents: (args: { connectionId: string }) => Promise detectRemoteWindowsTerminalCapabilities: (args: { connectionId: string }) => Promise<{ diff --git a/src/preload/api/preflight-bridge.ts b/src/preload/api/preflight-bridge.ts index 64d317d139cf..843eec933314 100644 --- a/src/preload/api/preflight-bridge.ts +++ b/src/preload/api/preflight-bridge.ts @@ -1,5 +1,6 @@ import { ipcRenderer } from 'electron' import type { PreflightRuntimeContext, PreloadApi, RefreshAgentsResult } from '../api-types' +import type { ZCodeInteractiveCapability } from '../../shared/zcode-missing-tui' export const preflightApi = { check: (args?: { @@ -27,6 +28,8 @@ export const preflightApi = { }> => ipcRenderer.invoke('preflight:check', args), detectAgents: (args?: PreflightRuntimeContext): Promise => ipcRenderer.invoke('preflight:detectAgents', args), + zcodeInteractiveCapability: (): Promise => + ipcRenderer.invoke('preflight:zcodeInteractiveCapability'), refreshAgents: (args?: PreflightRuntimeContext): Promise => ipcRenderer.invoke('preflight:refreshAgents', args), detectRemoteAgents: (args: { connectionId: string }): Promise => diff --git a/src/renderer/src/components/terminal-pane/zcode-missing-tui-notice.ts b/src/renderer/src/components/terminal-pane/zcode-missing-tui-notice.ts new file mode 100644 index 000000000000..5d758d39a8b9 --- /dev/null +++ b/src/renderer/src/components/terminal-pane/zcode-missing-tui-notice.ts @@ -0,0 +1,33 @@ +import { toast } from 'sonner' +import { translate } from '@/i18n/i18n' + +/** + * Tell the user their `zcode` cannot open a session, before they stare at a dead pane. + * + * ZCode's desktop bundle answers `--version`, runs `-p`, and passes `zcode doctor`, so Orca + * detects it, launches it, and installs hooks against it — all successfully. Only the + * interactive session fails, leaving a bare Node stack trace that reads as a broken Orca + * integration. The capability probe in main answers the question; this reports it. + */ +export async function warnIfZCodeCannotOpenSession(): Promise { + // Why swallow: this is advisory. A probe that could not run must never interrupt a launch. + const capability = await window.api.preflight.zcodeInteractiveCapability().catch(() => 'unknown') + if (capability !== 'missing-tui') { + return + } + toast.error( + translate( + 'auto.components.terminal.pane.zcode.missing.tui.title', + 'This ZCode build has no terminal UI' + ), + { + // Why a stable id: launching several ZCode panes must not stack the same notice. + id: 'zcode-missing-tui', + description: translate( + 'auto.components.terminal.pane.zcode.missing.tui.description', + "Orca's hooks installed correctly — the zcode on your PATH just cannot open a session. The ZCode desktop app bundles the agent runtime without its terminal UI. Install a zcode that ships the TUI, then run zcode outside Orca to confirm." + ), + duration: 20_000 + } + ) +} diff --git a/src/renderer/src/i18n/locales/en.json b/src/renderer/src/i18n/locales/en.json index 72cf2a672176..055f62c90c85 100644 --- a/src/renderer/src/i18n/locales/en.json +++ b/src/renderer/src/i18n/locales/en.json @@ -3264,6 +3264,14 @@ "e2fcf07c0d": "Orca could not save this terminal session because local storage is full or not writable. Open the disk space analyzer to find workspace storage you can clean up.", "678c780a2c": "Disk space is unavailable" }, + "zcode": { + "missing": { + "tui": { + "title": "This ZCode build has no terminal UI", + "description": "Orca's hooks installed correctly \u2014 the zcode on your PATH just cannot open a session. The ZCode desktop app bundles the agent runtime without its terminal UI. Install a zcode that ships the TUI, then run zcode outside Orca to confirm." + } + } + }, "osc52": { "clipboard": { "blocked": { diff --git a/src/renderer/src/i18n/locales/es.json b/src/renderer/src/i18n/locales/es.json index 871cd611af5c..1988b85014e9 100644 --- a/src/renderer/src/i18n/locales/es.json +++ b/src/renderer/src/i18n/locales/es.json @@ -2798,6 +2798,14 @@ "e2fcf07c0d": "Orca no pudo guardar esta sesión de terminal porque el almacenamiento local está lleno o no permite escritura. Abre el analizador de espacio en disco para encontrar almacenamiento de espacios de trabajo que puedas limpiar.", "678c780a2c": "El espacio en disco no está disponible" }, + "zcode": { + "missing": { + "tui": { + "title": "This ZCode build has no terminal UI", + "description": "Orca's hooks installed correctly \u2014 the zcode on your PATH just cannot open a session. The ZCode desktop app bundles the agent runtime without its terminal UI. Install a zcode that ships the TUI, then run zcode outside Orca to confirm." + } + } + }, "osc52": { "clipboard": { "blocked": { diff --git a/src/renderer/src/i18n/locales/fr.json b/src/renderer/src/i18n/locales/fr.json index e6c60b41e593..ea3207be00a1 100644 --- a/src/renderer/src/i18n/locales/fr.json +++ b/src/renderer/src/i18n/locales/fr.json @@ -3211,6 +3211,14 @@ "e2fcf07c0d": "Orca n'a pas pu enregistrer cette session de terminal car le stockage local est plein ou inaccessible en écriture. Ouvrez l'analyseur d'espace disque pour trouver du stockage de espace de travail à nettoyer.", "678c780a2c": "Espace disque indisponible" }, + "zcode": { + "missing": { + "tui": { + "title": "This ZCode build has no terminal UI", + "description": "Orca's hooks installed correctly \u2014 the zcode on your PATH just cannot open a session. The ZCode desktop app bundles the agent runtime without its terminal UI. Install a zcode that ships the TUI, then run zcode outside Orca to confirm." + } + } + }, "osc52": { "clipboard": { "blocked": { diff --git a/src/renderer/src/i18n/locales/ja.json b/src/renderer/src/i18n/locales/ja.json index eadab74eb76b..3167a9e0ae52 100644 --- a/src/renderer/src/i18n/locales/ja.json +++ b/src/renderer/src/i18n/locales/ja.json @@ -3089,6 +3089,14 @@ "e2fcf07c0d": "ローカルストレージがいっぱいか書き込みできないため、Orca はこのターミナルセッションを保存できませんでした。ディスク容量アナライザーを開いて、クリーンアップできるワークスペースストレージを見つけます。", "678c780a2c": "ディスク容量が利用できません" }, + "zcode": { + "missing": { + "tui": { + "title": "This ZCode build has no terminal UI", + "description": "Orca's hooks installed correctly \u2014 the zcode on your PATH just cannot open a session. The ZCode desktop app bundles the agent runtime without its terminal UI. Install a zcode that ships the TUI, then run zcode outside Orca to confirm." + } + } + }, "osc52": { "clipboard": { "blocked": { diff --git a/src/renderer/src/i18n/locales/ko.json b/src/renderer/src/i18n/locales/ko.json index aafd2b76ebfc..488e10749e6c 100644 --- a/src/renderer/src/i18n/locales/ko.json +++ b/src/renderer/src/i18n/locales/ko.json @@ -3089,6 +3089,14 @@ "e2fcf07c0d": "로컬 저장소가 가득 찼거나 쓸 수 없기 때문에 Orca가 이 terminal 세션을 저장할 수 없습니다. 디스크 공간 분석기를 열어 정리할 수 있는 워크스페이스 저장소를 찾으세요.", "678c780a2c": "디스크 공간을 사용할 수 없습니다." }, + "zcode": { + "missing": { + "tui": { + "title": "This ZCode build has no terminal UI", + "description": "Orca's hooks installed correctly \u2014 the zcode on your PATH just cannot open a session. The ZCode desktop app bundles the agent runtime without its terminal UI. Install a zcode that ships the TUI, then run zcode outside Orca to confirm." + } + } + }, "osc52": { "clipboard": { "blocked": { diff --git a/src/renderer/src/i18n/locales/zh.json b/src/renderer/src/i18n/locales/zh.json index ed926dadb279..4a546a3aca4b 100644 --- a/src/renderer/src/i18n/locales/zh.json +++ b/src/renderer/src/i18n/locales/zh.json @@ -3089,6 +3089,14 @@ "e2fcf07c0d": "Orca 无法保存此终端会话，因为本地存储已满或不可写。打开磁盘空间分析器以查找可以清理的工作区存储。", "678c780a2c": "磁盘空间不可用" }, + "zcode": { + "missing": { + "tui": { + "title": "This ZCode build has no terminal UI", + "description": "Orca's hooks installed correctly \u2014 the zcode on your PATH just cannot open a session. The ZCode desktop app bundles the agent runtime without its terminal UI. Install a zcode that ships the TUI, then run zcode outside Orca to confirm." + } + } + }, "osc52": { "clipboard": { "blocked": { diff --git a/src/renderer/src/store/terminals/terminal-tab-creation.ts b/src/renderer/src/store/terminals/terminal-tab-creation.ts index c1e67a06ed6f..cbe42c62ee0f 100644 --- a/src/renderer/src/store/terminals/terminal-tab-creation.ts +++ b/src/renderer/src/store/terminals/terminal-tab-creation.ts @@ -1,3 +1,4 @@ +import { warnIfZCodeCannotOpenSession } from '@/components/terminal-pane/zcode-missing-tui-notice' import { clearWorktreeSleepIntent } from '@/lib/worktree-sleep-intent' import type { TerminalTab } from '../../../../shared/terminal-tab-types' import { isValidHostTerminalTabId } from '../../../../shared/terminal-tab-id' @@ -133,6 +134,11 @@ export function createTerminalTabCreationActions( // Why: mark click-caused (not work-caused) spawns so updateTabPtyId skips the activity/sortEpoch bump that would reorder Recent/Smart on click. ...(options?.pendingActivationSpawn ? { pendingActivationSpawn: true } : {}) } + if (options?.launchAgent === 'zcode') { + // Why here: this is where a ZCode launch is first known, and it runs before the + // pane connects, so the explanation can beat the stack trace to the screen. + void warnIfZCodeCannotOpenSession() + } const validTargetGroupId = targetGroupId && s.groupsByWorktree[worktreeId]?.some((group) => group.id === targetGroupId) diff --git a/src/renderer/src/web/preload-api/web-host-capability-api.ts b/src/renderer/src/web/preload-api/web-host-capability-api.ts index 3834d664d87a..8a736717c015 100644 --- a/src/renderer/src/web/preload-api/web-host-capability-api.ts +++ b/src/renderer/src/web/preload-api/web-host-capability-api.ts @@ -64,6 +64,9 @@ export function createPreflightApi(): NonNullable['preflight } return callRuntimeResult('preflight.check', args) }, + // Why 'unknown' rather than a runtime call: the probe spawns the host's own `zcode`, and + // a paired web client has no business deciding anything about the host's CLI install. + zcodeInteractiveCapability: async () => 'unknown' as const, detectAgents: async () => { if (!requireActiveEnvironmentOrNull()) { return [] diff --git a/src/shared/zcode-missing-tui.test.ts b/src/shared/zcode-missing-tui.test.ts new file mode 100644 index 000000000000..ad736c8a9b39 --- /dev/null +++ b/src/shared/zcode-missing-tui.test.ts @@ -0,0 +1,34 @@ +import { readFileSync } from 'node:fs' +import { join } from 'node:path' +import { describe, expect, it } from 'vitest' +import { isZCodeMissingTuiOutput } from './zcode-missing-tui' + +const FIXTURE = join(__dirname, '..', 'main', 'runtime', '__fixtures__', 'zcode-missing-tui.txt') + +describe('isZCodeMissingTuiOutput', () => { + it('matches the recorded desktop-bundle failure byte for byte', () => { + expect(isZCodeMissingTuiOutput(readFileSync(FIXTURE, 'utf8'))).toBe(true) + }) + + it('matches the CJS spelling of the same failure', () => { + expect(isZCodeMissingTuiOutput("Error: Cannot find module '@zcode/tui'")).toBe(true) + }) + + it('does not match a build that has the TUI but no TTY', () => { + // Why this case matters: it is the healthy build's stderr when stdin is not a terminal. + expect(isZCodeMissingTuiOutput('TUI requires an interactive terminal.')).toBe(false) + }) + + it('does not match the localized form of that same healthy message', () => { + // Why: ZCode translates it, which is exactly why this rule keys on Node's error instead. + expect(isZCodeMissingTuiOutput('TUI 需要交互式终端。')).toBe(false) + }) + + it('does not match an unrelated missing package', () => { + expect(isZCodeMissingTuiOutput("Cannot find package 'left-pad' imported from x.js")).toBe(false) + }) + + it('does not match prose that merely mentions the package', () => { + expect(isZCodeMissingTuiOutput('install @zcode/tui to get the terminal UI')).toBe(false) + }) +}) diff --git a/src/shared/zcode-missing-tui.ts b/src/shared/zcode-missing-tui.ts new file mode 100644 index 000000000000..29dc58418755 --- /dev/null +++ b/src/shared/zcode-missing-tui.ts @@ -0,0 +1,39 @@ +/** + * Recognizing a `zcode` build that cannot open a session. + * + * ZCode ships one agent runtime behind two front ends. The desktop app bundles the runtime + * without `@zcode/tui`, because it draws its own window in Electron and would never call a + * terminal renderer. Put that bundle on PATH as `zcode` and it answers `--version`, runs + * `-p` headlessly, and passes `zcode doctor` — but dies the moment Orca asks it for an + * interactive session. + * + * That combination is why this is worth detecting rather than documenting alone: Orca's own + * auto-setup reports success (the hooks really are installed correctly), so the only visible + * failure is a Node stack trace inside the pane, and it reads as a broken Orca integration. + * + * Evidence: `src/main/runtime/__fixtures__/zcode-missing-tui.txt`, a recorded PTY capture of + * the desktop bundle refusing to start. + */ + +// Why the module-resolution error and not the success path: a build that HAS the TUI but no +// TTY prints "TUI requires an interactive terminal.", which ZCode localizes (`TUI 需要交互式终端。` +// in zh-CN), so matching it would miss every non-English user. Node's own resolution failure +// is not localized and names the package directly. +// +// Both spellings are covered because the ESM loader reports `Cannot find package` while a CJS +// require path reports `Cannot find module`, and which one a given build hits depends on how +// it was bundled. +const ZCODE_MISSING_TUI_RE = /Cannot find (?:package|module) ['"]@zcode\/tui['"]/ + +/** + * What a `zcode` build can do when asked for a session. + * + * `unknown` is a real answer, not a failure: a probe that could not run says nothing about + * the build, and callers must not treat it as broken. + */ +export type ZCodeInteractiveCapability = 'interactive' | 'missing-tui' | 'unknown' + +/** True when this output is ZCode reporting that its terminal UI is not installed. */ +export function isZCodeMissingTuiOutput(output: string): boolean { + return ZCODE_MISSING_TUI_RE.test(output) +}