an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
fix(onboarding): check engine availability before the pick is committed
Chaitanya Giri7903ae908da8
diff --git a/package.json b/package.jsonindex 97bb375a..63d9f75a 100644--- a/package.json+++ b/package.json@@ -19,7 +19,7 @@"typecheck:node": "tsc --noEmit -p tsconfig.node.json","typecheck:web": "tsc --noEmit -p tsconfig.web.json","typecheck": "npm run typecheck:node && npm run typecheck:web",- "test:focused": "node --test test/codex-remote.test.cjs test/control.test.cjs test/provider-automation.test.cjs test/provider-config.test.cjs test/queue-delivery.test.cjs test/terminal-automation.test.cjs test/terminal-recovery.test.cjs test/terminal-selection.test.cjs test/roster.test.cjs test/proc-kill.test.cjs test/expand-tilde.test.cjs test/hive-cwd.test.cjs test/hive-task-mutation.test.cjs test/hive-hook-node.test.cjs test/hive-roster-injection.test.cjs test/hive-runtime-path.test.cjs test/cli-install-ladder.test.cjs test/node-install.test.cjs test/office-gl-recovery.test.cjs test/update-state.test.cjs test/release-notes.test.cjs test/transcript-project-dir.test.cjs test/commit-graph.test.cjs test/ide-image.test.cjs test/win-cmd-shim.test.cjs test/hive-windows-prompt.test.cjs test/release-drop.test.cjs test/skills.test.cjs test/skills-install.test.cjs test/hero-payload.test.cjs",+ "test:focused": "node --test test/engine-availability.test.cjs test/codex-remote.test.cjs test/control.test.cjs test/provider-automation.test.cjs test/provider-config.test.cjs test/queue-delivery.test.cjs test/terminal-automation.test.cjs test/terminal-recovery.test.cjs test/terminal-selection.test.cjs test/roster.test.cjs test/proc-kill.test.cjs test/expand-tilde.test.cjs test/hive-cwd.test.cjs test/hive-task-mutation.test.cjs test/hive-hook-node.test.cjs test/hive-roster-injection.test.cjs test/hive-runtime-path.test.cjs test/cli-install-ladder.test.cjs test/node-install.test.cjs test/office-gl-recovery.test.cjs test/update-state.test.cjs test/release-notes.test.cjs test/transcript-project-dir.test.cjs test/commit-graph.test.cjs test/ide-image.test.cjs test/win-cmd-shim.test.cjs test/hive-windows-prompt.test.cjs test/release-drop.test.cjs test/skills.test.cjs test/skills-install.test.cjs test/hero-payload.test.cjs","check:links": "node tools/check-release-links.cjs","dist": "npm run build && electron-builder","dist:mac": "npm run build && electron-builder --mac",diff --git a/src/renderer/src/components/OnboardingWizard.tsx b/src/renderer/src/components/OnboardingWizard.tsxindex 6f8979e4..bd6ba81b 100644--- a/src/renderer/src/components/OnboardingWizard.tsx+++ b/src/renderer/src/components/OnboardingWizard.tsx@@ -6,6 +6,10 @@ import { SpritePortrait } from './SpritePortrait';import { ProviderLogo } from './ProviderLogo';import { AGENT_PROVIDER_PRESETS, modelsForProvider, type AgentProvider, type HarnessConfig } from '@/store/config';import { canReceiveInbox, providerPreset } from '@shared/agentProvider';+import {+ classifyEngineAvailability, engineAvailabilityBadge, engineAvailabilityMessage, engineBlocksOnboarding+} from '@shared/engineAvailability';+import type { ToolStatus } from '@shared/toolCatalog';export interface OnboardingWizardProps {onComplete: (config: HarnessConfig) => void;@@ -99,6 +103,23 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {const [error, setError] = useState<string | undefined>();const [busy, setBusy] = useState(false);+ // Which engine CLIs are actually on this machine. The picker used to record the+ // choice blind; the first check happened when Michael spawned, and for a+ // provider with no installer that meant a first run where nothing ever booted.+ // `undefined` = probe not back yet (or failed): rows show no badge and nothing+ // is blocked, because a broken probe must not lock a new user out.+ const [engines, setEngines] = useState<ToolStatus[] | undefined>();+ const [probing, setProbing] = useState(false);+ const probeEngines = async () => {+ setProbing(true);+ try { setEngines(await window.cth.toolsStatus()); }+ catch { /* leave undefined: unknown, never blocking */ }+ finally { setProbing(false); }+ };+ useEffect(() => { void probeEngines(); }, []);+ const selectedEngine = classifyEngineAvailability(engines, godProvider);+ const engineBlocked = engineBlocksOnboarding(selectedEngine);+// Permissions & reliability toggles. These apply IMMEDIATELY on change (their// own IPC / OS state) — they are NOT part of finish()'s config write. First-run// defaults: notifications off (config default), login-item off (fresh install);@@ -163,6 +184,13 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {setError(undefined);const harnessHome = home.trim(); // whitespace-only is not a folderif (!harnessHome) { setError('Pick a harness home folder first.'); setBusy(false); setStep('home'); return; }+ // The orchestrator step already refuses to advance on this, but a late probe+ // result can change the answer after the user has moved on. Never write a+ // godProvider that is known to be unable to boot.+ if (engineBlocked) {+ setError(`${providerPreset(godProvider).label} is not installed. Install it and press "check again", or pick another engine.`);+ setBusy(false); setStep('orchestrator'); return;+ }const ensure = await window.cth.ensureHarnessHome(harnessHome);if (!ensure.ok) {setError(ensure.error ?? 'could not create harness home');@@ -393,10 +421,12 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {one that runs your whole office. We recommend Claude Code on Opus 4.8 (1M).You can add or switch the others later.</>) : (- <>Each option is a <strong>CLI engine</strong> you have installed (Claude Code,- Codex, Antigravity/Gemini, or a local proxy like Qwen).+ <>Each option is a <strong>CLI engine</strong> (Claude Code, Codex,+ Antigravity/Gemini, or a local proxy like Qwen). Engines marked+ INSTALLED are already on this machine; INSTALLS ON FIRST RUN means the app+ sets it up when Michael first starts.<strong> Your clone</strong> (Michael) is the engine that orchestrates the whole- hive. Recommended: Claude Code · Opus 4.8 · 1M — other providers can be wired+ hive. Recommended: Claude Code · Opus 4.8 · 1M. Other providers can be wiredper agent later.</>)}</span>@@ -442,6 +472,21 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {</span>)}</span>+ {(() => {+ const a = classifyEngineAvailability(engines, p.id);+ const badge = engineAvailabilityBadge(a);+ if (!badge) return null;+ const bad = a.state === 'not-installable';+ return (+ <span title={a.path ?? undefined} style={{+ fontSize: 10, padding: '1px 5px', lineHeight: '16px',+ background: a.state === 'installed' ? 'var(--cth-mint-light)' : bad ? 'var(--cth-paper-100)' : 'var(--cth-cream-200)',+ color: bad ? 'var(--cth-ink-500)' : 'var(--cth-ink-900)',+ boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)',+ fontFamily: 'var(--cth-font-display)', flexShrink: 0+ }}>{badge}</span>+ );+ })()}{p.id === 'claude' && (<span style={{fontSize: 10, padding: '1px 5px', lineHeight: '16px',@@ -454,6 +499,25 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {);})}</div>+ {engineBlocked && (+ <div style={{+ display: 'flex', flexDirection: 'column', gap: 8, padding: 10,+ background: 'var(--cth-paper-100)', boxShadow: 'inset 0 0 0 2px var(--cth-ink-900)',+ fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-900)'+ }}>+ <span>{engineAvailabilityMessage(selectedEngine, providerPreset(godProvider).label)}</span>+ <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>+ <PixelButton variant="secondary" size="sm" onClick={() => { void probeEngines(); }} disabled={probing}>+ {probing ? 'checking...' : 'check again'}+ </PixelButton>+ {selectedEngine.docsUrl && (+ <PixelButton variant="ghost" size="sm" onClick={() => { void window.cth.openExternal(selectedEngine.docsUrl!); }}>+ install instructions+ </PixelButton>+ )}+ </div>+ </div>+ )}<div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}><div style={{ fontSize: 12, color: 'var(--cth-ink-500)' }}>Model</div><select@@ -697,10 +761,17 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {setError('Pick a harness home folder first.');return;}+ // Same idea for the engine: refuse here, with the reason on+ // screen, instead of letting a pick that cannot boot through+ // to a Michael that never starts.+ if (step === 'orchestrator' && engineBlocked) {+ setError(`${providerPreset(godProvider).label} is not installed. Install it and press "check again", or pick another engine.`);+ return;+ }setError(undefined);setStep(nextStep(step));}}- disabled={step === 'persona' && !audience}+ disabled={(step === 'persona' && !audience) || (step === 'orchestrator' && engineBlocked)}>{step === 'welcome' ? 'set it up' : 'next'}</PixelButton>diff --git a/src/shared/engineAvailability.ts b/src/shared/engineAvailability.tsnew file mode 100644index 00000000..f0497cd3--- /dev/null+++ b/src/shared/engineAvailability.ts@@ -0,0 +1,78 @@+/**+ * Can the engine a user is about to pick actually boot on this machine?+ *+ * The onboarding wizard records Michael's engine and nothing checks it until the+ * first spawn. spawnAgentCore then runs the install ladder (cliInstall.ts), and+ * for a provider with no `installCommand` and no `nativeInstallCommand` that+ * ladder ends at the `manual` rung: a hint is printed in a terminal and the+ * orchestrator never starts. This module turns the setup catalog probe+ * (`tools:status`, which already resolves every engine binary on PATH) into one+ * answer per provider so the wizard can say so BEFORE the pick is committed.+ *+ * Pure and electron-free on purpose so it is testable from node --test.+ */+import type { AgentProvider } from './agentProvider';+import type { ToolStatus } from './toolCatalog';++export type EngineAvailabilityState =+ /** The binary resolves on this machine. */+ | 'installed'+ /** Not here yet, but the provider ships an installer the app runs on first spawn. */+ | 'installs-on-first-run'+ /** Not here and nothing we can run: the user has to install it by hand first. */+ | 'not-installable'+ /** The probe did not run or did not cover this provider. Never block on this. */+ | 'unknown';++export interface EngineAvailability {+ state: EngineAvailabilityState;+ /** Absolute path when installed. */+ path: string | null;+ /** The command the app would run (or the user could paste) to install it. */+ installCommand: string;+ docsUrl?: string;+}++/** Classify one provider from the catalog probe. `statuses` is what+ * `window.cth.toolsStatus()` returned; undefined means it has not run (yet). */+export function classifyEngineAvailability(+ statuses: readonly ToolStatus[] | undefined,+ provider: AgentProvider+): EngineAvailability {+ const row = statuses?.find((s) => s.id === `engine:${provider}`);+ if (!row) return { state: 'unknown', path: null, installCommand: '' };+ const installCommand = row.installCommand ?? '';+ if (row.found) return { state: 'installed', path: row.path, installCommand, docsUrl: row.docsUrl };+ return {+ state: installCommand ? 'installs-on-first-run' : 'not-installable',+ path: null,+ installCommand,+ docsUrl: row.docsUrl+ };+}++/** Whether the wizard must refuse to move on with this engine selected. Only the+ * proven dead end blocks; an unknown probe never locks a user out. */+export function engineBlocksOnboarding(a: EngineAvailability): boolean {+ return a.state === 'not-installable';+}++/** One short line for the badge on each engine row. */+export function engineAvailabilityBadge(a: EngineAvailability): string | null {+ switch (a.state) {+ case 'installed': return 'INSTALLED';+ case 'installs-on-first-run': return 'INSTALLS ON FIRST RUN';+ case 'not-installable': return 'NOT INSTALLED';+ default: return null;+ }+}++/** The explanation shown under the picker when the selected engine cannot boot.+ * Written for someone who does not know what a CLI engine is: what happened,+ * then what to do next. */+export function engineAvailabilityMessage(a: EngineAvailability, label: string): string | null {+ if (a.state !== 'not-installable') return null;+ return `${label} is not installed on this computer and the app has no installer for it, ` ++ `so Michael could not start. Install it first, then press "check again". ` ++ `Or pick Claude Code, which installs itself on first run.`;+}diff --git a/test/engine-availability.test.cjs b/test/engine-availability.test.cjsnew file mode 100644index 00000000..65d170b0--- /dev/null+++ b/test/engine-availability.test.cjs@@ -0,0 +1,75 @@+'use strict';++const test = require('node:test');+const assert = require('node:assert/strict');+const loadTs = require('./load-ts.cjs');++const {+ classifyEngineAvailability,+ engineBlocksOnboarding,+ engineAvailabilityBadge,+ engineAvailabilityMessage+} = loadTs('src/shared/engineAvailability.ts');+const { toolCatalog } = loadTs('src/shared/toolCatalog.ts');+const { AGENT_PROVIDER_PRESETS, canReceiveInbox } = loadTs('src/shared/agentProvider.ts');++// Build what `tools:status` returns for a machine where `found` lists the only+// binaries present. Mirrors the main-process handler's shape without electron.+function statusesFor(found) {+ return toolCatalog().map((spec) => ({+ ...spec,+ installCommand: spec.install.posix,+ found: !!spec.bin && found.includes(spec.bin),+ path: spec.bin && found.includes(spec.bin) ? `/usr/local/bin/${spec.bin}` : null+ }));+}++test('an installed engine is installed, whatever its installer story', () => {+ const s = statusesFor(['claude', 'grok']);+ assert.equal(classifyEngineAvailability(s, 'claude').state, 'installed');+ assert.equal(classifyEngineAvailability(s, 'grok').state, 'installed');+ assert.equal(classifyEngineAvailability(s, 'grok').path, '/usr/local/bin/grok');+});++test('a missing engine with an installer installs on first run and does not block', () => {+ const s = statusesFor([]);+ for (const id of ['claude', 'codex', 'opencode', 'crush', 'pi', 'copilot']) {+ const a = classifyEngineAvailability(s, id);+ assert.equal(a.state, 'installs-on-first-run', id);+ assert.ok(a.installCommand.length > 0, id);+ assert.equal(engineBlocksOnboarding(a), false, id);+ }+});++test('the repro: grok, antigravity and qwen are offered by the wizard but cannot install', () => {+ const s = statusesFor([]);+ const offered = AGENT_PROVIDER_PRESETS.filter((p) => canReceiveInbox(p.id)).map((p) => p.id);+ for (const id of ['grok', 'antigravity', 'qwen']) {+ assert.ok(offered.includes(id), `${id} is on the picker`);+ const a = classifyEngineAvailability(s, id);+ assert.equal(a.state, 'not-installable', id);+ assert.equal(engineBlocksOnboarding(a), true, id);+ assert.equal(engineAvailabilityBadge(a), 'NOT INSTALLED');+ const msg = engineAvailabilityMessage(a, 'Grok');+ assert.match(msg, /not installed/);+ assert.match(msg, /check again/);+ assert.match(msg, /Claude Code/);+ assert.doesNotMatch(msg, /[–—-]/, 'no dashes in user facing prose');+ }+});++test('no probe result means unknown, and unknown never blocks', () => {+ const a = classifyEngineAvailability(undefined, 'grok');+ assert.equal(a.state, 'unknown');+ assert.equal(engineBlocksOnboarding(a), false);+ assert.equal(engineAvailabilityBadge(a), null);+ assert.equal(engineAvailabilityMessage(a, 'Grok'), null);+ // a probe that ran but lacks the row behaves the same+ assert.equal(classifyEngineAvailability([], 'grok').state, 'unknown');+});++test('only the dead end has a message', () => {+ const s = statusesFor(['claude']);+ assert.equal(engineAvailabilityMessage(classifyEngineAvailability(s, 'claude'), 'Claude Code'), null);+ assert.equal(engineAvailabilityMessage(classifyEngineAvailability(s, 'codex'), 'Codex'), null);+});