@gobing-ai/ts-ai-runner 0.2.1

package/README.md

@@ -0,0 +1,3 @@
+# @gobing-ai/ts-ai-runner
+
+Coding-agent command shims, detection, doctor checks, and prompt execution for Bun/Node CLIs.

package/dist/agent-detector.d.ts

@@ -0,0 +1,34 @@
+import { type AgentName } from './agents/shims';
+import { AiRunner } from './ai-runner';
+/** Installation/version probe result for one coding agent. */
+export interface DetectedAgent {
+    /** Agent identifier. */
+    name: AgentName | string;
+    /** Whether the agent CLI was found and returned a parseable version. */
+    installed: boolean;
+    /** First version-output line when installed. */
+    version: string | null;
+    /** Agent-specific channels or models when available. */
+    channels: string[];
+    /** Detection error when unavailable. */
+    error: string | null;
+}
+/** Constructor options for AgentDetector. */
+export interface AgentDetectorOptions {
+    /** Shared AiRunner instance. */
+    runner?: AiRunner;
+    /** Per-agent version probe timeout in milliseconds. */
+    timeout?: number;
+}
+/** Probes supported coding-agent CLIs for installation and version state. */
+export declare class AgentDetector {
+    private readonly runner;
+    private readonly timeout;
+    constructor(options?: AgentDetectorOptions);
+    /** Probe all bundled agents in display order. */
+    detectAll(): Promise<DetectedAgent[]>;
+    /** Probe one agent by name. */
+    detectOne(agent: string): Promise<DetectedAgent>;
+    private parseResult;
+}
+//# sourceMappingURL=agent-detector.d.ts.map

package/dist/agent-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-detector.d.ts","sourceRoot":"","sources":["../src/agent-detector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAA4C,MAAM,gBAAgB,CAAC;AAC1F,OAAO,EAAuB,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5D,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC1B,wBAAwB;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB,gDAAgD;IAChD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wCAAwC;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACjC,gCAAgC;IAChC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD,6EAA6E;AAC7E,qBAAa,aAAa;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,GAAE,oBAAyB;IAK9C,iDAAiD;IAC3C,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAI3C,+BAA+B;IACzB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAiBtD,OAAO,CAAC,WAAW;CAiDtB"}

package/dist/agent-detector.js

@@ -0,0 +1,84 @@
+import { DISPLAY_ORDER, getAgentShim, isAgentName } from './agents/shims.js';
+import { AiRunner } from './ai-runner.js';
+const DEFAULT_TIMEOUT_MS = 5_000;
+const VERSION_PATTERN = /(?<version>\d+\.\d+(?:\.\d+)?)/;
+/** Probes supported coding-agent CLIs for installation and version state. */
+export class AgentDetector {
+    runner;
+    timeout;
+    constructor(options = {}) {
+        this.runner = options.runner ?? new AiRunner();
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    }
+    /** Probe all bundled agents in display order. */
+    async detectAll() {
+        return await Promise.all(DISPLAY_ORDER.map((agent) => this.detectOne(agent)));
+    }
+    /** Probe one agent by name. */
+    async detectOne(agent) {
+        if (!isAgentName(agent)) {
+            return { name: agent, installed: false, version: null, channels: [], error: `Unknown agent: ${agent}` };
+        }
+        try {
+            return this.parseResult(agent, await this.runner.runVersionCommand(agent, { timeout: this.timeout }));
+        }
+        catch (error) {
+            return {
+                name: agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    parseResult(agent, result) {
+        const command = getAgentShim(agent).command;
+        const output = `${result.stdout}\n${result.stderr}`.trim();
+        const lower = output.toLowerCase();
+        if (lower.includes('command not found') || lower.includes('enoent') || lower.includes('not recognized')) {
+            return {
+                name: agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: `${command}: command not found`,
+            };
+        }
+        if (result.signal !== undefined || result.exitCode === null) {
+            return {
+                name: agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: result.signal ?? 'Process timed out',
+            };
+        }
+        if (result.exitCode !== 0) {
+            return {
+                name: agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: `Non-zero exit code ${result.exitCode}: ${result.stderr.slice(0, 200)}`,
+            };
+        }
+        const match = VERSION_PATTERN.exec(output);
+        if (match?.groups?.version === undefined) {
+            return {
+                name: agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: 'Could not parse version output',
+            };
+        }
+        return {
+            name: agent,
+            installed: true,
+            version: output.split('\n')[0] ?? match.groups.version,
+            channels: [],
+            error: null,
+        };
+    }
+}

package/dist/agents/shims.d.ts

@@ -0,0 +1,52 @@
+/** Identifier for one supported coding agent. */
+export type AgentName = 'claude' | 'codex' | 'gemini' | 'pi' | 'opencode' | 'antigravity' | 'openclaw';
+/** Output mode for prompt invocations. */
+export type OutputMode = 'text' | 'json';
+/** Concrete executable and argv pair returned by an agent shim. */
+export interface ShimCommand {
+    /** Executable to invoke. */
+    command: string;
+    /** Arguments to pass to the executable. */
+    args: string[];
+}
+/** Options for prompt-style invocations. */
+export interface PromptOptions {
+    /** Prompt text or slash command to send to the agent. */
+    input?: string;
+    /** Continue the previous session if the agent supports it. */
+    continue?: boolean;
+    /** Model identifier passed through to the agent CLI. */
+    model?: string;
+    /** Output mode passed through to the agent CLI. */
+    mode?: OutputMode;
+}
+/** Pure command builder for one coding-agent CLI. */
+export interface AgentShim {
+    /** Stable agent identifier. */
+    readonly name: AgentName;
+    /** Executable command name. */
+    readonly command: string;
+    /** Capability tier: 1 = direct CLI, 2 = gateway/TUI constrained. */
+    readonly tier: 1 | 2;
+    /** Build a help-display command. */
+    getHelpCommand(): ShimCommand;
+    /** Build a version-detection command. */
+    getVersionCommand(): ShimCommand;
+    /** Build a prompt invocation command. */
+    getPromptCommand(options: PromptOptions): ShimCommand;
+    /** Build an auth-status command, or null when unsupported. */
+    getAuthCommand(): ShimCommand | null;
+}
+/** All bundled agent shims keyed by agent name. */
+export declare const AGENT_SHIMS: Readonly<Record<AgentName, AgentShim>>;
+/** Tier-1 auto-selection priority. */
+export declare const TIER1_PRIORITY: readonly AgentName[];
+/** Display order for doctor and list commands. */
+export declare const DISPLAY_ORDER: readonly AgentName[];
+/** Set of gateway/TUI-constrained agents. */
+export declare const TIER2_AGENTS: ReadonlySet<AgentName>;
+/** Return true when a value is a supported agent identifier. */
+export declare function isAgentName(value: string): value is AgentName;
+/** Look up a bundled agent shim. */
+export declare function getAgentShim(agent: AgentName): AgentShim;
+//# sourceMappingURL=shims.d.ts.map

package/dist/agents/shims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/agents/shims.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,IAAI,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,CAAC;AAEvG,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC,mEAAmE;AACnE,MAAM,WAAW,WAAW;IACxB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACtB,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB,oCAAoC;IACpC,cAAc,IAAI,WAAW,CAAC;IAC9B,yCAAyC;IACzC,iBAAiB,IAAI,WAAW,CAAC;IACjC,yCAAyC;IACzC,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW,CAAC;IACtD,8DAA8D;IAC9D,cAAc,IAAI,WAAW,GAAG,IAAI,CAAC;CACxC;AA0GD,mDAAmD;AACnD,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAQ9D,CAAC;AAEF,sCAAsC;AACtC,eAAO,MAAM,cAAc,EAAE,SAAS,SAAS,EAAoD,CAAC;AAEpG,kDAAkD;AAClD,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAQ7C,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,SAAS,CAAwC,CAAC;AAEzF,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D;AAED,oCAAoC;AACpC,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAExD"}

package/dist/agents/shims.js

@@ -0,0 +1,141 @@
+const claudeShim = {
+    name: 'claude',
+    command: 'claude',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'claude', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'claude', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['-p', options.input ?? ''];
+        if (options.continue === true)
+            args.push('--continue');
+        if (options.model !== undefined)
+            args.push('--model', options.model);
+        args.push('--output-format', options.mode ?? 'text');
+        return { command: 'claude', args };
+    },
+    getAuthCommand: () => ({ command: 'claude', args: ['auth', 'status'] }),
+};
+const codexShim = {
+    name: 'codex',
+    command: 'codex',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'codex', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'codex', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        if (options.continue === true && options.input !== undefined) {
+            throw new Error('Codex resume mode does not accept a new prompt');
+        }
+        const args = options.continue === true ? ['exec', 'resume', '--last'] : ['exec', options.input ?? ''];
+        if (options.model !== undefined)
+            args.push('-m', options.model);
+        if ((options.mode ?? 'text') === 'json')
+            args.push('--json');
+        return { command: 'codex', args };
+    },
+    getAuthCommand: () => ({ command: 'codex', args: ['login', 'status'] }),
+};
+const geminiShim = {
+    name: 'gemini',
+    command: 'gemini',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'gemini', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'gemini', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['-p', options.input ?? ''];
+        if (options.continue === true)
+            args.push('-r', 'latest');
+        if (options.model !== undefined)
+            args.push('-m', options.model);
+        args.push('-o', options.mode ?? 'text');
+        return { command: 'gemini', args };
+    },
+    getAuthCommand: () => null,
+};
+const piShim = {
+    name: 'pi',
+    command: 'pi',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'pi', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'pi', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = [];
+        if (options.continue !== true)
+            args.push('--no-session');
+        args.push('-p', options.input ?? '');
+        if (options.continue === true)
+            args.push('-c');
+        if (options.model !== undefined)
+            args.push('--model', options.model);
+        args.push('--mode', options.mode ?? 'text');
+        return { command: 'pi', args };
+    },
+    getAuthCommand: () => ({ command: 'pi', args: ['--list-models'] }),
+};
+const opencodeShim = {
+    name: 'opencode',
+    command: 'opencode',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'opencode', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'opencode', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['run', options.input ?? ''];
+        if (options.continue === true)
+            args.push('-c');
+        if (options.model !== undefined)
+            args.push('-m', options.model);
+        if ((options.mode ?? 'text') === 'json')
+            args.push('--format', 'json');
+        return { command: 'opencode', args };
+    },
+    getAuthCommand: () => ({ command: 'opencode', args: ['providers'] }),
+};
+const antigravityShim = {
+    name: 'antigravity',
+    command: 'agy',
+    tier: 2,
+    getHelpCommand: () => ({ command: 'agy', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'agy', args: ['--version'] }),
+    getPromptCommand: (options) => ({ command: 'agy', args: ['chat', options.input ?? ''] }),
+    getAuthCommand: () => null,
+};
+const openclawShim = {
+    name: 'openclaw',
+    command: 'openclaw',
+    tier: 2,
+    getHelpCommand: () => ({ command: 'openclaw', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'openclaw', args: ['--version'] }),
+    getPromptCommand: (options) => ({ command: 'openclaw', args: ['agent', '--local', '-m', options.input ?? ''] }),
+    getAuthCommand: () => ({ command: 'openclaw', args: ['health'] }),
+};
+/** All bundled agent shims keyed by agent name. */
+export const AGENT_SHIMS = {
+    claude: claudeShim,
+    codex: codexShim,
+    gemini: geminiShim,
+    pi: piShim,
+    opencode: opencodeShim,
+    antigravity: antigravityShim,
+    openclaw: openclawShim,
+};
+/** Tier-1 auto-selection priority. */
+export const TIER1_PRIORITY = ['pi', 'codex', 'gemini', 'claude', 'opencode'];
+/** Display order for doctor and list commands. */
+export const DISPLAY_ORDER = [
+    'claude',
+    'codex',
+    'gemini',
+    'pi',
+    'opencode',
+    'antigravity',
+    'openclaw',
+];
+/** Set of gateway/TUI-constrained agents. */
+export const TIER2_AGENTS = new Set(['antigravity', 'openclaw']);
+/** Return true when a value is a supported agent identifier. */
+export function isAgentName(value) {
+    return Object.hasOwn(AGENT_SHIMS, value);
+}
+/** Look up a bundled agent shim. */
+export function getAgentShim(agent) {
+    return AGENT_SHIMS[agent];
+}

package/dist/ai-runner.d.ts

@@ -0,0 +1,48 @@
+import { type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { type AgentName, type PromptOptions } from './agents/shims';
+/** Result returned by every AI runner dispatch method. */
+export interface AgentRunResult {
+    /** Process exit code; null indicates signal or timeout termination. */
+    exitCode: number | null;
+    /** Captured stdout. */
+    stdout: string;
+    /** Captured stderr. */
+    stderr: string;
+    /** Signal description when the process was terminated by signal. */
+    signal?: string;
+    /** Wall-clock duration in milliseconds. */
+    durationMs: number;
+}
+/** Per-invocation runtime options. */
+export interface AgentRunOptions {
+    /** Working directory for the invocation. */
+    cwd?: string;
+    /** Timeout in milliseconds. */
+    timeout?: number;
+}
+/** Constructor options for AiRunner. */
+export interface AiRunnerOptions {
+    /** Process executor used for all subprocess invocations. */
+    processExecutor?: ProcessExecutor;
+    /** Default working directory for invocations. */
+    defaultCwd?: string;
+    /** Default timeout in milliseconds. */
+    defaultTimeout?: number;
+}
+/** Dispatches coding-agent CLI commands through pure command shims. */
+export declare class AiRunner {
+    private readonly processExecutor;
+    private readonly defaultCwd;
+    private readonly defaultTimeout;
+    constructor(options?: AiRunnerOptions);
+    /** Run an agent help command. */
+    runHelpCommand(agent: AgentName, options?: AgentRunOptions): Promise<AgentRunResult>;
+    /** Run an agent version command. */
+    runVersionCommand(agent: AgentName, options?: AgentRunOptions): Promise<AgentRunResult>;
+    /** Run an agent prompt command. */
+    runPromptCommand(agent: AgentName, promptOptions: PromptOptions, options?: AgentRunOptions): Promise<AgentRunResult>;
+    /** Run an agent authentication command, or return null when unsupported. */
+    runAuthCommand(agent: AgentName, options?: AgentRunOptions): Promise<AgentRunResult> | null;
+    private invoke;
+}
+//# sourceMappingURL=ai-runner.d.ts.map

package/dist/ai-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-runner.d.ts","sourceRoot":"","sources":["../src/ai-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAsB,MAAM,uBAAuB,CAAC;AACtG,OAAO,EAAE,KAAK,SAAS,EAAgB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAElF,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC3B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC5B,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC5B,4DAA4D;IAC5D,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,uEAAuE;AACvE,qBAAa,QAAQ;IACjB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;gBAExC,OAAO,GAAE,eAAoB;IAMzC,iCAAiC;IACjC,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAIxF,oCAAoC;IACpC,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAI3F,mCAAmC;IACnC,gBAAgB,CACZ,KAAK,EAAE,SAAS,EAChB,aAAa,EAAE,aAAa,EAC5B,OAAO,GAAE,eAAoB,GAC9B,OAAO,CAAC,cAAc,CAAC;IAI1B,4EAA4E;IAC5E,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;YAKjF,MAAM;CAwBvB"}

package/dist/ai-runner.js

@@ -0,0 +1,48 @@
+import { NodeProcessExecutor } from '@gobing-ai/ts-runtime';
+import { getAgentShim } from './agents/shims.js';
+/** Dispatches coding-agent CLI commands through pure command shims. */
+export class AiRunner {
+    processExecutor;
+    defaultCwd;
+    defaultTimeout;
+    constructor(options = {}) {
+        this.processExecutor = options.processExecutor ?? new NodeProcessExecutor();
+        this.defaultCwd = options.defaultCwd;
+        this.defaultTimeout = options.defaultTimeout;
+    }
+    /** Run an agent help command. */
+    runHelpCommand(agent, options = {}) {
+        return this.invoke(agent, 'help', getAgentShim(agent).getHelpCommand(), options, true);
+    }
+    /** Run an agent version command. */
+    runVersionCommand(agent, options = {}) {
+        return this.invoke(agent, 'version', getAgentShim(agent).getVersionCommand(), options, true);
+    }
+    /** Run an agent prompt command. */
+    runPromptCommand(agent, promptOptions, options = {}) {
+        return this.invoke(agent, 'prompt', getAgentShim(agent).getPromptCommand(promptOptions), options, false);
+    }
+    /** Run an agent authentication command, or return null when unsupported. */
+    runAuthCommand(agent, options = {}) {
+        const command = getAgentShim(agent).getAuthCommand();
+        return command === null ? null : this.invoke(agent, 'auth', command, options, true);
+    }
+    async invoke(agent, operation, command, options, forceBuffered) {
+        const result = await this.processExecutor.run({
+            command: command.command,
+            args: command.args,
+            label: `ai-runner.${agent}.${operation}`,
+            rejectOnError: false,
+            forceBuffered,
+            cwd: options.cwd ?? this.defaultCwd,
+            timeout: options.timeout ?? this.defaultTimeout,
+        });
+        return {
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            ...(result.signal !== undefined ? { signal: result.signal } : {}),
+            durationMs: result.durationMs,
+        };
+    }
+}

package/dist/doctor-runner.d.ts

@@ -0,0 +1,48 @@
+import { AgentDetector } from './agent-detector';
+import { AiRunner } from './ai-runner';
+/** Health-check result for one coding agent. */
+export interface DoctorResult {
+    /** Agent identifier. */
+    agent: string;
+    /** Whether the CLI is installed. */
+    installed: boolean;
+    /** Human-readable version when installed. */
+    version: string | null;
+    /** Whether the agent appears authenticated. */
+    authenticated: boolean;
+    /** Whether the agent is ready for direct use. */
+    usable: boolean;
+    /** Capability tier: 1 = direct CLI, 2 = gateway/TUI constrained. */
+    tier: 1 | 2;
+    /** Agent-specific channels or models when available. */
+    channels: string[];
+    /** Probe error when unavailable. */
+    error: string | null;
+}
+/** Constructor options for DoctorRunner. */
+export interface DoctorRunnerOptions {
+    /** Shared detector. */
+    agentDetector?: AgentDetector;
+    /** Shared runner. */
+    runner?: AiRunner;
+    /** Auth probe timeout in milliseconds. */
+    timeout?: number;
+    /** Environment map for file/env auth checks. */
+    env?: Record<string, string | undefined>;
+}
+/** Runs installation and auth health checks for supported coding agents. */
+export declare class DoctorRunner {
+    private readonly detector;
+    private readonly runner;
+    private readonly timeout;
+    private readonly env;
+    private readonly fs;
+    constructor(options?: DoctorRunnerOptions);
+    /** Run a health check on all supported agents. */
+    runAll(): Promise<DoctorResult[]>;
+    /** Run a health check on one agent. */
+    runOne(agent: string): Promise<DoctorResult>;
+    private buildResult;
+    private checkAuth;
+}
+//# sourceMappingURL=doctor-runner.d.ts.map

package/dist/doctor-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-runner.d.ts","sourceRoot":"","sources":["../src/doctor-runner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAsB,MAAM,kBAAkB,CAAC;AAErE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,gDAAgD;AAChD,MAAM,WAAW,YAAY;IACzB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,+CAA+C;IAC/C,aAAa,EAAE,OAAO,CAAC;IACvB,iDAAiD;IACjD,MAAM,EAAE,OAAO,CAAC;IAChB,oEAAoE;IACpE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACZ,wDAAwD;IACxD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oCAAoC;IACpC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAChC,uBAAuB;IACvB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,qBAAqB;IACrB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC5C;AAID,4EAA4E;AAC5E,qBAAa,YAAY;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqC;IACzD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAwB;gBAE/B,OAAO,GAAE,mBAAwB;IAO7C,kDAAkD;IAC5C,MAAM,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAKvC,uCAAuC;IACjC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;YAIpC,WAAW;YAgBX,SAAS;CAa1B"}

package/dist/doctor-runner.js

@@ -0,0 +1,58 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getProcessEnv, NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { AgentDetector } from './agent-detector.js';
+import { isAgentName, TIER2_AGENTS } from './agents/shims.js';
+import { AiRunner } from './ai-runner.js';
+const DEFAULT_TIMEOUT_MS = 5_000;
+/** Runs installation and auth health checks for supported coding agents. */
+export class DoctorRunner {
+    detector;
+    runner;
+    timeout;
+    env;
+    fs = new NodeFileSystem();
+    constructor(options = {}) {
+        this.runner = options.runner ?? new AiRunner();
+        this.detector = options.agentDetector ?? new AgentDetector({ runner: this.runner });
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.env = options.env ?? getProcessEnv();
+    }
+    /** Run a health check on all supported agents. */
+    async runAll() {
+        const detected = await this.detector.detectAll();
+        return await Promise.all(detected.map((agent) => this.buildResult(agent)));
+    }
+    /** Run a health check on one agent. */
+    async runOne(agent) {
+        return this.buildResult(await this.detector.detectOne(agent));
+    }
+    async buildResult(detected) {
+        const tier = TIER2_AGENTS.has(detected.name) ? 2 : 1;
+        const authenticated = detected.installed && isAgentName(detected.name) ? await this.checkAuth(detected.name) : false;
+        return {
+            agent: detected.name,
+            installed: detected.installed,
+            version: detected.version,
+            authenticated,
+            usable: detected.installed && detected.version !== null && authenticated,
+            tier,
+            channels: detected.channels,
+            error: detected.error,
+        };
+    }
+    async checkAuth(agent) {
+        if (agent === 'gemini')
+            return this.fs.exists(join(homedir(), '.gemini', 'settings.json'));
+        if (agent === 'codex' && (await this.fs.exists(join(homedir(), '.codex', 'auth.json'))))
+            return true;
+        if (agent === 'pi' && (this.env.GOOGLE_API_KEY !== undefined || this.env.ANTHROPIC_API_KEY !== undefined))
+            return true;
+        const command = this.runner.runAuthCommand(agent, { timeout: this.timeout });
+        if (command === null)
+            return false;
+        const result = await command;
+        return (result.exitCode === 0 &&
+            !/not authenticated|not logged|unauthenticated/i.test(`${result.stdout}\n${result.stderr}`));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './agent-detector';
+export * from './agents/shims';
+export * from './ai-runner';
+export * from './doctor-runner';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './agent-detector.js';
+export * from './agents/shims.js';
+export * from './ai-runner.js';
+export * from './doctor-runner.js';

package/package.json

@@ -0,0 +1,58 @@
+{
+    "name": "@gobing-ai/ts-ai-runner",
+    "version": "0.2.1",
+    "description": "@gobing-ai/ts-ai-runner — Coding-agent shims, detection, doctor checks, and prompt execution.",
+    "keywords": [
+        "typescript",
+        "ai",
+        "agent",
+        "cli",
+        "runner"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gobing-ai/ts-libs.git",
+        "directory": "packages/ai-runner"
+    },
+    "author": "Robin Min <minlongbing@gmail.com>",
+    "contributors": [
+        "Robin Min <minlongbing@gmail.com>"
+    ],
+    "type": "module",
+    "private": false,
+    "sideEffects": false,
+    "license": "Apache-2.0",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json && bun ../../scripts/builder.ts fix-dist-esm-extensions dist",
+        "test": "NODE_ENV=test bun test --coverage --coverage-dir=.coverage --reporter=dots",
+        "test:full": "NODE_ENV=test bun test --update-snapshots --coverage --coverage-dir=.coverage",
+        "typecheck": "tsc --noEmit",
+        "lint": "biome check . && bun run typecheck",
+        "format": "biome check . --write",
+        "check": "bun run lint && bun run test",
+        "prepublishOnly": "bun run build",
+        "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-ai-runner-v<version> && git push --tags' && exit 1"
+    },
+    "dependencies": {
+        "@gobing-ai/ts-runtime": "workspace:*"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/agent-detector.ts

@@ -0,0 +1,111 @@
+import { type AgentName, DISPLAY_ORDER, getAgentShim, isAgentName } from './agents/shims';
+import { type AgentRunResult, AiRunner } from './ai-runner';
+
+/** Installation/version probe result for one coding agent. */
+export interface DetectedAgent {
+    /** Agent identifier. */
+    name: AgentName | string;
+    /** Whether the agent CLI was found and returned a parseable version. */
+    installed: boolean;
+    /** First version-output line when installed. */
+    version: string | null;
+    /** Agent-specific channels or models when available. */
+    channels: string[];
+    /** Detection error when unavailable. */
+    error: string | null;
+}
+
+/** Constructor options for AgentDetector. */
+export interface AgentDetectorOptions {
+    /** Shared AiRunner instance. */
+    runner?: AiRunner;
+    /** Per-agent version probe timeout in milliseconds. */
+    timeout?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+const VERSION_PATTERN = /(?<version>\d+\.\d+(?:\.\d+)?)/;
+
+/** Probes supported coding-agent CLIs for installation and version state. */
+export class AgentDetector {
+    private readonly runner: AiRunner;
+    private readonly timeout: number;
+
+    constructor(options: AgentDetectorOptions = {}) {
+        this.runner = options.runner ?? new AiRunner();
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    }
+
+    /** Probe all bundled agents in display order. */
+    async detectAll(): Promise<DetectedAgent[]> {
+        return await Promise.all(DISPLAY_ORDER.map((agent) => this.detectOne(agent)));
+    }
+
+    /** Probe one agent by name. */
+    async detectOne(agent: string): Promise<DetectedAgent> {
+        if (!isAgentName(agent)) {
+            return { name: agent, installed: false, version: null, channels: [], error: `Unknown agent: ${agent}` };
+        }
+        try {
+            return this.parseResult(agent, await this.runner.runVersionCommand(agent, { timeout: this.timeout }));
+        } catch (error) {
+            return {
+                name: agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+
+    private parseResult(agent: AgentName, result: AgentRunResult): DetectedAgent {
+        const command = getAgentShim(agent).command;
+        const output = `${result.stdout}\n${result.stderr}`.trim();
+        const lower = output.toLowerCase();
+        if (lower.includes('command not found') || lower.includes('enoent') || lower.includes('not recognized')) {
+            return {
+                name: agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: `${command}: command not found`,
+            };
+        }
+        if (result.signal !== undefined || result.exitCode === null) {
+            return {
+                name: agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: result.signal ?? 'Process timed out',
+            };
+        }
+        if (result.exitCode !== 0) {
+            return {
+                name: agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: `Non-zero exit code ${result.exitCode}: ${result.stderr.slice(0, 200)}`,
+            };
+        }
+        const match = VERSION_PATTERN.exec(output);
+        if (match?.groups?.version === undefined) {
+            return {
+                name: agent,
+                installed: false,
+                version: null,
+                channels: [],
+                error: 'Could not parse version output',
+            };
+        }
+        return {
+            name: agent,
+            installed: true,
+            version: output.split('\n')[0] ?? match.groups.version,
+            channels: [],
+            error: null,
+        };
+    }
+}

package/src/agents/shims.ts

@@ -0,0 +1,185 @@
+/** Identifier for one supported coding agent. */
+export type AgentName = 'claude' | 'codex' | 'gemini' | 'pi' | 'opencode' | 'antigravity' | 'openclaw';
+
+/** Output mode for prompt invocations. */
+export type OutputMode = 'text' | 'json';
+
+/** Concrete executable and argv pair returned by an agent shim. */
+export interface ShimCommand {
+    /** Executable to invoke. */
+    command: string;
+    /** Arguments to pass to the executable. */
+    args: string[];
+}
+
+/** Options for prompt-style invocations. */
+export interface PromptOptions {
+    /** Prompt text or slash command to send to the agent. */
+    input?: string;
+    /** Continue the previous session if the agent supports it. */
+    continue?: boolean;
+    /** Model identifier passed through to the agent CLI. */
+    model?: string;
+    /** Output mode passed through to the agent CLI. */
+    mode?: OutputMode;
+}
+
+/** Pure command builder for one coding-agent CLI. */
+export interface AgentShim {
+    /** Stable agent identifier. */
+    readonly name: AgentName;
+    /** Executable command name. */
+    readonly command: string;
+    /** Capability tier: 1 = direct CLI, 2 = gateway/TUI constrained. */
+    readonly tier: 1 | 2;
+    /** Build a help-display command. */
+    getHelpCommand(): ShimCommand;
+    /** Build a version-detection command. */
+    getVersionCommand(): ShimCommand;
+    /** Build a prompt invocation command. */
+    getPromptCommand(options: PromptOptions): ShimCommand;
+    /** Build an auth-status command, or null when unsupported. */
+    getAuthCommand(): ShimCommand | null;
+}
+
+const claudeShim: AgentShim = {
+    name: 'claude',
+    command: 'claude',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'claude', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'claude', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['-p', options.input ?? ''];
+        if (options.continue === true) args.push('--continue');
+        if (options.model !== undefined) args.push('--model', options.model);
+        args.push('--output-format', options.mode ?? 'text');
+        return { command: 'claude', args };
+    },
+    getAuthCommand: () => ({ command: 'claude', args: ['auth', 'status'] }),
+};
+
+const codexShim: AgentShim = {
+    name: 'codex',
+    command: 'codex',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'codex', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'codex', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        if (options.continue === true && options.input !== undefined) {
+            throw new Error('Codex resume mode does not accept a new prompt');
+        }
+        const args = options.continue === true ? ['exec', 'resume', '--last'] : ['exec', options.input ?? ''];
+        if (options.model !== undefined) args.push('-m', options.model);
+        if ((options.mode ?? 'text') === 'json') args.push('--json');
+        return { command: 'codex', args };
+    },
+    getAuthCommand: () => ({ command: 'codex', args: ['login', 'status'] }),
+};
+
+const geminiShim: AgentShim = {
+    name: 'gemini',
+    command: 'gemini',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'gemini', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'gemini', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['-p', options.input ?? ''];
+        if (options.continue === true) args.push('-r', 'latest');
+        if (options.model !== undefined) args.push('-m', options.model);
+        args.push('-o', options.mode ?? 'text');
+        return { command: 'gemini', args };
+    },
+    getAuthCommand: () => null,
+};
+
+const piShim: AgentShim = {
+    name: 'pi',
+    command: 'pi',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'pi', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'pi', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args: string[] = [];
+        if (options.continue !== true) args.push('--no-session');
+        args.push('-p', options.input ?? '');
+        if (options.continue === true) args.push('-c');
+        if (options.model !== undefined) args.push('--model', options.model);
+        args.push('--mode', options.mode ?? 'text');
+        return { command: 'pi', args };
+    },
+    getAuthCommand: () => ({ command: 'pi', args: ['--list-models'] }),
+};
+
+const opencodeShim: AgentShim = {
+    name: 'opencode',
+    command: 'opencode',
+    tier: 1,
+    getHelpCommand: () => ({ command: 'opencode', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'opencode', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['run', options.input ?? ''];
+        if (options.continue === true) args.push('-c');
+        if (options.model !== undefined) args.push('-m', options.model);
+        if ((options.mode ?? 'text') === 'json') args.push('--format', 'json');
+        return { command: 'opencode', args };
+    },
+    getAuthCommand: () => ({ command: 'opencode', args: ['providers'] }),
+};
+
+const antigravityShim: AgentShim = {
+    name: 'antigravity',
+    command: 'agy',
+    tier: 2,
+    getHelpCommand: () => ({ command: 'agy', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'agy', args: ['--version'] }),
+    getPromptCommand: (options) => ({ command: 'agy', args: ['chat', options.input ?? ''] }),
+    getAuthCommand: () => null,
+};
+
+const openclawShim: AgentShim = {
+    name: 'openclaw',
+    command: 'openclaw',
+    tier: 2,
+    getHelpCommand: () => ({ command: 'openclaw', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'openclaw', args: ['--version'] }),
+    getPromptCommand: (options) => ({ command: 'openclaw', args: ['agent', '--local', '-m', options.input ?? ''] }),
+    getAuthCommand: () => ({ command: 'openclaw', args: ['health'] }),
+};
+
+/** All bundled agent shims keyed by agent name. */
+export const AGENT_SHIMS: Readonly<Record<AgentName, AgentShim>> = {
+    claude: claudeShim,
+    codex: codexShim,
+    gemini: geminiShim,
+    pi: piShim,
+    opencode: opencodeShim,
+    antigravity: antigravityShim,
+    openclaw: openclawShim,
+};
+
+/** Tier-1 auto-selection priority. */
+export const TIER1_PRIORITY: readonly AgentName[] = ['pi', 'codex', 'gemini', 'claude', 'opencode'];
+
+/** Display order for doctor and list commands. */
+export const DISPLAY_ORDER: readonly AgentName[] = [
+    'claude',
+    'codex',
+    'gemini',
+    'pi',
+    'opencode',
+    'antigravity',
+    'openclaw',
+];
+
+/** Set of gateway/TUI-constrained agents. */
+export const TIER2_AGENTS: ReadonlySet<AgentName> = new Set(['antigravity', 'openclaw']);
+
+/** Return true when a value is a supported agent identifier. */
+export function isAgentName(value: string): value is AgentName {
+    return Object.hasOwn(AGENT_SHIMS, value);
+}
+
+/** Look up a bundled agent shim. */
+export function getAgentShim(agent: AgentName): AgentShim {
+    return AGENT_SHIMS[agent];
+}

package/src/ai-runner.ts

@@ -0,0 +1,97 @@
+import { NodeProcessExecutor, type ProcessExecutor, type ProcessResult } from '@gobing-ai/ts-runtime';
+import { type AgentName, getAgentShim, type PromptOptions } from './agents/shims';
+
+/** Result returned by every AI runner dispatch method. */
+export interface AgentRunResult {
+    /** Process exit code; null indicates signal or timeout termination. */
+    exitCode: number | null;
+    /** Captured stdout. */
+    stdout: string;
+    /** Captured stderr. */
+    stderr: string;
+    /** Signal description when the process was terminated by signal. */
+    signal?: string;
+    /** Wall-clock duration in milliseconds. */
+    durationMs: number;
+}
+
+/** Per-invocation runtime options. */
+export interface AgentRunOptions {
+    /** Working directory for the invocation. */
+    cwd?: string;
+    /** Timeout in milliseconds. */
+    timeout?: number;
+}
+
+/** Constructor options for AiRunner. */
+export interface AiRunnerOptions {
+    /** Process executor used for all subprocess invocations. */
+    processExecutor?: ProcessExecutor;
+    /** Default working directory for invocations. */
+    defaultCwd?: string;
+    /** Default timeout in milliseconds. */
+    defaultTimeout?: number;
+}
+
+/** Dispatches coding-agent CLI commands through pure command shims. */
+export class AiRunner {
+    private readonly processExecutor: ProcessExecutor;
+    private readonly defaultCwd: string | undefined;
+    private readonly defaultTimeout: number | undefined;
+
+    constructor(options: AiRunnerOptions = {}) {
+        this.processExecutor = options.processExecutor ?? new NodeProcessExecutor();
+        this.defaultCwd = options.defaultCwd;
+        this.defaultTimeout = options.defaultTimeout;
+    }
+
+    /** Run an agent help command. */
+    runHelpCommand(agent: AgentName, options: AgentRunOptions = {}): Promise<AgentRunResult> {
+        return this.invoke(agent, 'help', getAgentShim(agent).getHelpCommand(), options, true);
+    }
+
+    /** Run an agent version command. */
+    runVersionCommand(agent: AgentName, options: AgentRunOptions = {}): Promise<AgentRunResult> {
+        return this.invoke(agent, 'version', getAgentShim(agent).getVersionCommand(), options, true);
+    }
+
+    /** Run an agent prompt command. */
+    runPromptCommand(
+        agent: AgentName,
+        promptOptions: PromptOptions,
+        options: AgentRunOptions = {},
+    ): Promise<AgentRunResult> {
+        return this.invoke(agent, 'prompt', getAgentShim(agent).getPromptCommand(promptOptions), options, false);
+    }
+
+    /** Run an agent authentication command, or return null when unsupported. */
+    runAuthCommand(agent: AgentName, options: AgentRunOptions = {}): Promise<AgentRunResult> | null {
+        const command = getAgentShim(agent).getAuthCommand();
+        return command === null ? null : this.invoke(agent, 'auth', command, options, true);
+    }
+
+    private async invoke(
+        agent: AgentName,
+        operation: string,
+        command: { command: string; args: string[] },
+        options: AgentRunOptions,
+        forceBuffered: boolean,
+    ): Promise<AgentRunResult> {
+        const result: ProcessResult = await this.processExecutor.run({
+            command: command.command,
+            args: command.args,
+            label: `ai-runner.${agent}.${operation}`,
+            rejectOnError: false,
+            forceBuffered,
+            cwd: options.cwd ?? this.defaultCwd,
+            timeout: options.timeout ?? this.defaultTimeout,
+        });
+        return {
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            ...(result.signal !== undefined ? { signal: result.signal } : {}),
+            durationMs: result.durationMs,
+        };
+    }
+}

package/src/doctor-runner.ts

@@ -0,0 +1,97 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getProcessEnv, NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { AgentDetector, type DetectedAgent } from './agent-detector';
+import { type AgentName, isAgentName, TIER2_AGENTS } from './agents/shims';
+import { AiRunner } from './ai-runner';
+
+/** Health-check result for one coding agent. */
+export interface DoctorResult {
+    /** Agent identifier. */
+    agent: string;
+    /** Whether the CLI is installed. */
+    installed: boolean;
+    /** Human-readable version when installed. */
+    version: string | null;
+    /** Whether the agent appears authenticated. */
+    authenticated: boolean;
+    /** Whether the agent is ready for direct use. */
+    usable: boolean;
+    /** Capability tier: 1 = direct CLI, 2 = gateway/TUI constrained. */
+    tier: 1 | 2;
+    /** Agent-specific channels or models when available. */
+    channels: string[];
+    /** Probe error when unavailable. */
+    error: string | null;
+}
+
+/** Constructor options for DoctorRunner. */
+export interface DoctorRunnerOptions {
+    /** Shared detector. */
+    agentDetector?: AgentDetector;
+    /** Shared runner. */
+    runner?: AiRunner;
+    /** Auth probe timeout in milliseconds. */
+    timeout?: number;
+    /** Environment map for file/env auth checks. */
+    env?: Record<string, string | undefined>;
+}
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+
+/** Runs installation and auth health checks for supported coding agents. */
+export class DoctorRunner {
+    private readonly detector: AgentDetector;
+    private readonly runner: AiRunner;
+    private readonly timeout: number;
+    private readonly env: Record<string, string | undefined>;
+    private readonly fs = new NodeFileSystem();
+
+    constructor(options: DoctorRunnerOptions = {}) {
+        this.runner = options.runner ?? new AiRunner();
+        this.detector = options.agentDetector ?? new AgentDetector({ runner: this.runner });
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.env = options.env ?? getProcessEnv();
+    }
+
+    /** Run a health check on all supported agents. */
+    async runAll(): Promise<DoctorResult[]> {
+        const detected = await this.detector.detectAll();
+        return await Promise.all(detected.map((agent) => this.buildResult(agent)));
+    }
+
+    /** Run a health check on one agent. */
+    async runOne(agent: string): Promise<DoctorResult> {
+        return this.buildResult(await this.detector.detectOne(agent));
+    }
+
+    private async buildResult(detected: DetectedAgent): Promise<DoctorResult> {
+        const tier = TIER2_AGENTS.has(detected.name as AgentName) ? 2 : 1;
+        const authenticated =
+            detected.installed && isAgentName(detected.name) ? await this.checkAuth(detected.name) : false;
+        return {
+            agent: detected.name,
+            installed: detected.installed,
+            version: detected.version,
+            authenticated,
+            usable: detected.installed && detected.version !== null && authenticated,
+            tier,
+            channels: detected.channels,
+            error: detected.error,
+        };
+    }
+
+    private async checkAuth(agent: AgentName): Promise<boolean> {
+        if (agent === 'gemini') return this.fs.exists(join(homedir(), '.gemini', 'settings.json'));
+        if (agent === 'codex' && (await this.fs.exists(join(homedir(), '.codex', 'auth.json')))) return true;
+        if (agent === 'pi' && (this.env.GOOGLE_API_KEY !== undefined || this.env.ANTHROPIC_API_KEY !== undefined))
+            return true;
+        const command = this.runner.runAuthCommand(agent, { timeout: this.timeout });
+        if (command === null) return false;
+        const result = await command;
+        return (
+            result.exitCode === 0 &&
+            !/not authenticated|not logged|unauthenticated/i.test(`${result.stdout}\n${result.stderr}`)
+        );
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './agent-detector';
+export * from './agents/shims';
+export * from './ai-runner';
+export * from './doctor-runner';