@gobing-ai/ts-ai-runner 0.3.1 → 0.3.2

package/dist/team-orchestrator.d.ts

@@ -1,20 +1,26 @@
+import type { InboxMessageDao } from '@gobing-ai/ts-db/inbox';
+import { EventBus } from '@gobing-ai/ts-infra';
 import type { AgentSpec } from './agent-spec';
-import { MessageService } from './message-service';
+import type { AgentEvents } from './events';
 import { TeamAgentProcess } from './team-agent-process';
-type TeamEvent = 'agent.started' | 'agent.stopped' | 'message.sent';
-type TeamListener = (payload: unknown) => void;
 type AgentProcessFactory = (options: ConstructorParameters<typeof TeamAgentProcess>[0]) => TeamAgentProcess;
+/** Configuration options for `TeamOrchestrator`. */
 export interface TeamOrchestratorOptions {
     processFactory?: AgentProcessFactory;
+    events?: EventBus<AgentEvents>;
 }
+/**
+ * Orchestrates a team of AI agents — loads specs, starts/stops agent processes, routes messages between them,
+ * and emits lifecycle events. Agents in the same workspace see each other as peers.
+ */
 export declare class TeamOrchestrator {
     private readonly configDir;
-    private readonly messageService;
+    private readonly inbox;
     private specs;
     private readonly running;
-    private readonly listeners;
     private readonly processFactory;
-    constructor(configDir: string, messageService: MessageService, options?: TeamOrchestratorOptions);
+    private readonly events;
+    constructor(configDir: string, inbox: InboxMessageDao, options?: TeamOrchestratorOptions);
     loadSpecs(): AgentSpec[];
     getSpec(id: string): AgentSpec | undefined;
     startAgent(id: string): Promise<TeamAgentProcess>;
@@ -25,12 +31,11 @@ export declare class TeamOrchestrator {
     getAgentStatus(id: string): 'running' | 'stopped' | 'errored' | 'unknown';
     getPeerSpecs(workspace: string, excludeId?: string): AgentSpec[];
     stopAll(): Promise<void>;
-    on(event: TeamEvent, listener: TeamListener): () => void;
+    on<K extends keyof AgentEvents>(event: K, listener: AgentEvents[K]): () => void;
     private requireSpec;
     private requireAgentName;
     private injectPendingMessages;
     private flushInbox;
-    private emit;
 }
 export {};
 //# sourceMappingURL=team-orchestrator.d.ts.map

package/dist/team-orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"team-orchestrator.d.ts","sourceRoot":"","sources":["../src/team-orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,KAAK,SAAS,GAAG,eAAe,GAAG,eAAe,GAAG,cAAc,CAAC;AACpE,KAAK,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAC/C,KAAK,mBAAmB,GAAG,CAAC,OAAO,EAAE,qBAAqB,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,KAAK,gBAAgB,CAAC;AAE5G,MAAM,WAAW,uBAAuB;IACpC,cAAc,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED,qBAAa,gBAAgB;IAOrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAPnC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2C;IACrE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAsB;gBAGhC,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,cAAc,EAC/C,OAAO,GAAE,uBAA4B;IAKzC,SAAS,IAAI,SAAS,EAAE;IAKxB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAKpC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAkCjD,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAKnD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQzG,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAIjD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS;IAMzE,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE;IAK1D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,MAAM,IAAI;IAOxD,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,qBAAqB;YAIf,UAAU;IASxB,OAAO,CAAC,IAAI;CAGf"}
+{"version":3,"file":"team-orchestrator.d.ts","sourceRoot":"","sources":["../src/team-orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,KAAK,mBAAmB,GAAG,CAAC,OAAO,EAAE,qBAAqB,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,KAAK,gBAAgB,CAAC;AAE5G,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACpC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,MAAM,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAOrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAP1B,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAsB;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;gBAG1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,EACvC,OAAO,GAAE,uBAA4B;IAMzC,SAAS,IAAI,SAAS,EAAE;IAKxB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAKpC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsCjD,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAKnD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQzG,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAIjD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS;IAMzE,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE;IAK1D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,EAAE,CAAC,CAAC,SAAS,MAAM,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAK/E,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,gBAAgB;YAKV,qBAAqB;YAIrB,UAAU;CAa3B"}

package/dist/team-orchestrator.js

@@ -1,19 +1,25 @@
+import { EventBus } from '@gobing-ai/ts-infra';
 import { loadAgentSpecs } from './agent-spec.js';
 import { getAgentShim, isAgentName } from './agents/shims.js';
 import { buildIdentityPreamble } from './identity.js';
-import { MessageService } from './message-service.js';
+import { formatMessage } from './messages.js';
 import { TeamAgentProcess } from './team-agent-process.js';
+/**
+ * Orchestrates a team of AI agents — loads specs, starts/stops agent processes, routes messages between them,
+ * and emits lifecycle events. Agents in the same workspace see each other as peers.
+ */
 export class TeamOrchestrator {
     configDir;
-    messageService;
+    inbox;
     specs = [];
     running = new Map();
-    listeners = new Map();
     processFactory;
-    constructor(configDir, messageService, options = {}) {
+    events;
+    constructor(configDir, inbox, options = {}) {
         this.configDir = configDir;
-        this.messageService = messageService;
+        this.inbox = inbox;
         this.processFactory = options.processFactory ?? ((processOptions) => new TeamAgentProcess(processOptions));
+        this.events = options.events ?? new EventBus();
     }
     loadSpecs() {
         this.specs = loadAgentSpecs(this.configDir);
@@ -54,7 +60,11 @@ export class TeamOrchestrator {
         await process.start();
         this.running.set(id, process);
         await this.injectPendingMessages(process);
-        this.emit('agent.started', { id });
+        void this.events.emit('agent.started', {
+            agentId: spec.id,
+            agentType: spec.type,
+            pid: process.getPid(),
+        });
         return process;
     }
     async stopAgent(id) {
@@ -63,18 +73,17 @@ export class TeamOrchestrator {
             return;
         await process.stop();
         this.running.delete(id);
-        this.emit('agent.stopped', { id });
+        void this.events.emit('agent.stopped', { agentId: id, exitCode: process.getExitCode() });
     }
     async restartAgent(id) {
         await this.stopAgent(id);
         return this.startAgent(id);
     }
     async sendMessage(fromId, toId, body, inReplyTo) {
-        const msgId = await this.messageService.enqueue(fromId, toId, body, inReplyTo);
+        const msgId = await this.inbox.enqueue(fromId, toId, body, inReplyTo);
         const process = this.running.get(toId);
-        if (process !== undefined)
-            await this.flushInbox(process, 'live stdin injection failed');
-        this.emit('message.sent', { id: msgId, fromId, toId });
+        const ok = process !== undefined ? await this.flushInbox(process, 'live stdin injection failed') : false;
+        void this.events.emit('agent.message.sent', { agentId: toId, ok });
         return msgId;
     }
     getRunningAgents() {
@@ -95,10 +104,8 @@ export class TeamOrchestrator {
         await Promise.all([...this.running.keys()].map((id) => this.stopAgent(id)));
     }
     on(event, listener) {
-        const listeners = this.listeners.get(event) ?? new Set();
-        listeners.add(listener);
-        this.listeners.set(event, listeners);
-        return () => listeners.delete(listener);
+        this.events.on(event, listener);
+        return () => this.events.off(event, listener);
     }
     requireSpec(id) {
         const spec = this.getSpec(id);
@@ -111,21 +118,21 @@ export class TeamOrchestrator {
             throw new Error(`Unsupported agent type: ${type}`);
         return type;
     }
-    injectPendingMessages(process) {
+    async injectPendingMessages(process) {
         return this.flushInbox(process, 'startup stdin injection failed');
     }
     async flushInbox(process, failLabel) {
-        const messages = await this.messageService.drain(process.agentId);
+        const messages = await this.inbox.drainPending(process.agentId);
+        let ok = true;
         for (const message of messages) {
-            const result = await process.send(MessageService.formatMessage(message));
+            const result = await process.send(formatMessage(message));
             if (result.ok)
-                await this.messageService.deliver(message.id);
-            else
-                await this.messageService.fail(message.id, failLabel);
+                await this.inbox.markDelivered(message.id);
+            else {
+                ok = false;
+                await this.inbox.markFailed(message.id, failLabel);
+            }
         }
-    }
-    emit(event, payload) {
-        for (const listener of this.listeners.get(event) ?? [])
-            listener(payload);
+        return ok;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-ai-runner",
-    "version": "0.3.1",
+    "version": "0.3.2",
     "description": "@gobing-ai/ts-ai-runner — Coding-agent shims, detection, doctor checks, and prompt execution.",
     "keywords": [
         "typescript",
@@ -47,9 +47,9 @@
         "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-db": "^0.3.1",
-        "@gobing-ai/ts-runtime": "^0.3.1",
-        "@gobing-ai/ts-utils": "^0.3.1"
+        "@gobing-ai/ts-db": "^0.3.2",
+        "@gobing-ai/ts-infra": "^0.3.2",
+        "@gobing-ai/ts-runtime": "^0.3.2"
     },
     "devDependencies": {
         "@types/bun": "1.3.14"

package/src/agent-detector.ts

@@ -58,24 +58,33 @@ export class AgentDetector {
         if (lower.includes('command not found') || lower.includes('enoent') || lower.includes('not recognized')) {
             return unavailable(agent, `${command}: command not found`);
         }
-        if (result.signal !== undefined || result.exitCode === null) {
-            return unavailable(agent, result.signal ?? 'Process timed out');
+        if (result.signal !== undefined) {
+            return unavailable(agent, `Terminated by signal: ${result.signal}`);
+        }
+        if (result.exitCode === null) {
+            return unavailable(agent, 'Process did not produce an exit code');
         }
         if (result.exitCode !== 0) {
-            return unavailable(agent, `Non-zero exit code ${result.exitCode}: ${result.stderr.slice(0, 200)}`);
+            return unavailable(agent, `Non-zero exit code: ${result.exitCode}. stderr: ${result.stderr.slice(0, 200)}`);
         }
         const match = VERSION_PATTERN.exec(output);
         if (match?.groups?.version === undefined) {
             return unavailable(agent, 'Could not parse version output');
         }
+        const version = output.split('\n')[0]?.trim() || match.groups.version;
         return {
             name: agent,
             installed: true,
-            version: match.groups.version,
-            channels: [],
+            version,
+            channels: this.detectChannels(agent, output),
             error: null,
         };
     }
+
+    private detectChannels(_agent: AgentName, _output: string): string[] {
+        // Phase 2 hook: parse per-agent channel/model output here when shims expose it.
+        return [];
+    }
 }
 
 /** Build an "unavailable" detection result for an agent with the given error. */

package/src/agent-spec.ts

@@ -1,6 +1,13 @@
-import { basename, join } from 'node:path';
-import { NodeSyncFileSystem, parseYamlObject, type SyncFileSystem, stringifyYamlObject } from '@gobing-ai/ts-runtime';
+import {
+    basenamePath,
+    joinPath,
+    NodeSyncFileSystem,
+    parseYamlObject,
+    type SyncFileSystem,
+    stringifyYamlObject,
+} from '@gobing-ai/ts-runtime';
 
+/** Specification for an AI agent defined in the configuration directory. */
 export interface AgentSpec {
     id: string;
     name: string;
@@ -12,6 +19,7 @@ export interface AgentSpec {
     autoStart?: boolean;
 }
 
+/** Validation error thrown when agent spec data is malformed or invalid. */
 export class ValueError extends Error {
     constructor(message: string) {
         super(message);
@@ -19,6 +27,7 @@ export class ValueError extends Error {
     }
 }
 
+/** Validate that `id` matches the agent ID format: 2-64 chars, lowercase alphanumeric with `_` or `-`. Returns the id on success, throws `ValueError` otherwise. */
 export function validateAgentId(id: string): string {
     if (!/^[a-z][a-z0-9_-]{1,63}$/.test(id)) {
         throw new ValueError(`Invalid agent id "${id}": expected 2-64 chars, lowercase alphanumeric, "_" or "-"`);
@@ -26,11 +35,12 @@ export function validateAgentId(id: string): string {
     return id;
 }
 
+/** Load and validate all YAML agent spec files from `configDir`. Throws `ValueError` on parse failures or duplicate IDs. */
 export function loadAgentSpecs(configDir: string, fs: SyncFileSystem = new NodeSyncFileSystem()): AgentSpec[] {
     const entries = safeReadDir(configDir, fs)
         .filter((entry) => entry.endsWith('.yaml') || entry.endsWith('.yml'))
         .sort();
-    const specs = entries.map((entry) => parseAgentSpec(fs.readFile(join(configDir, entry)), entry));
+    const specs = entries.map((entry) => parseAgentSpec(fs.readFile(joinPath(configDir, entry)), entry));
     const seen = new Set<string>();
     for (const spec of specs) {
         validateAgentId(spec.id);
@@ -40,6 +50,7 @@ export function loadAgentSpecs(configDir: string, fs: SyncFileSystem = new NodeS
     return specs;
 }
 
+/** Serialize `spec` to YAML and write it to `configDir/<id>.yaml`. Creates the directory if missing. */
 export async function saveAgentSpec(
     spec: AgentSpec,
     configDir: string,
@@ -47,16 +58,17 @@ export async function saveAgentSpec(
 ): Promise<void> {
     validateAgentId(spec.id);
     fs.mkdir(configDir);
-    fs.writeFile(join(configDir, `${spec.id}.yaml`), serializeAgentSpec(spec));
+    fs.writeFile(joinPath(configDir, `${spec.id}.yaml`), serializeAgentSpec(spec));
 }
 
+/** Remove the YAML file for agent `id` from `configDir`. Does nothing if the file doesn't exist. */
 export async function deleteAgentSpec(
     id: string,
     configDir: string,
     fs: SyncFileSystem = new NodeSyncFileSystem(),
 ): Promise<void> {
     validateAgentId(id);
-    fs.unlink(join(configDir, `${id}.yaml`));
+    fs.unlink(joinPath(configDir, `${id}.yaml`));
 }
 
 function safeReadDir(configDir: string, fs: SyncFileSystem = new NodeSyncFileSystem()): string[] {
@@ -102,7 +114,7 @@ function serializeAgentSpec(spec: AgentSpec): string {
 function requireString(source: Record<string, unknown>, key: keyof AgentSpec, fileName: string): string {
     const value = source[key];
     if (typeof value !== 'string' || value.trim() === '') {
-        throw new ValueError(`${basename(fileName)}: "${key}" must be a non-empty string`);
+        throw new ValueError(`${basenamePath(fileName)}: "${key}" must be a non-empty string`);
     }
     return value;
 }
@@ -110,7 +122,7 @@ function requireString(source: Record<string, unknown>, key: keyof AgentSpec, fi
 function requireStringArray(source: Record<string, unknown>, key: keyof AgentSpec, fileName: string): string[] {
     const value = source[key];
     if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
-        throw new ValueError(`${basename(fileName)}: "${key}" must be a string array`);
+        throw new ValueError(`${basenamePath(fileName)}: "${key}" must be a string array`);
     }
     return value;
 }
@@ -122,7 +134,7 @@ function requireRecord(
 ): Record<string, unknown> {
     const value = source[key];
     if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        throw new ValueError(`${basename(fileName)}: "${key}" must be an object`);
+        throw new ValueError(`${basenamePath(fileName)}: "${key}" must be an object`);
     }
     return value as Record<string, unknown>;
 }

package/src/ai-runner.ts

@@ -1,6 +1,15 @@
-import { NodeProcessExecutor, type ProcessExecutor, type ProcessResult } from '@gobing-ai/ts-runtime';
-import { type AgentName, getAgentShim, type PromptOptions } from './agents/shims';
+import { type EventBus, getLogger, type Logger, traceAsync } from '@gobing-ai/ts-infra';
+import {
+    getProcessCwd,
+    NodeProcessExecutor,
+    type ProcessExecutor,
+    type ProcessResult,
+    type TracerPort,
+} from '@gobing-ai/ts-runtime';
+import { type AgentName, getAgentShim, type PromptOptions, type ShimCommand } from './agents/shims';
+import type { AgentEvents, AiRunnerProcessEvents } from './events';
 import { buildIdentityPreamble } from './identity';
+import { translateSlashCommand } from './slash-command';
 
 /** Result returned by every AI runner dispatch method. */
 export interface AgentRunResult {
@@ -32,6 +41,14 @@ export interface AiRunnerOptions {
     defaultCwd?: string;
     /** Default timeout in milliseconds. */
     defaultTimeout?: number;
+    /** Logger for invocation diagnostics. Defaults to `getLogger('ai-runner')`. */
+    logger?: Logger;
+    /** Event bus receiving process-level observability from the default executor. */
+    processEvents?: EventBus<AiRunnerProcessEvents>;
+    /** Event bus receiving agent-level invocation observability. */
+    events?: EventBus<AgentEvents>;
+    /** Tracer adapter for the default executor. Defaults to `ts-infra` traceAsync. */
+    tracer?: TracerPort;
 }
 
 /** Dispatches coding-agent CLI commands through pure command shims. */
@@ -39,11 +56,30 @@ export class AiRunner {
     private readonly processExecutor: ProcessExecutor;
     private readonly defaultCwd: string | undefined;
     private readonly defaultTimeout: number | undefined;
+    private readonly logger: Logger;
+    private readonly events: EventBus<AgentEvents> | undefined;
 
     constructor(options: AiRunnerOptions = {}) {
-        this.processExecutor = options.processExecutor ?? new NodeProcessExecutor();
+        this.processExecutor =
+            options.processExecutor ??
+            new NodeProcessExecutor({
+                ...(options.processEvents !== undefined
+                    ? {
+                          events: {
+                              emit: (event, detail) => {
+                                  void options.processEvents?.emit(event, detail);
+                              },
+                          },
+                      }
+                    : {}),
+                tracer: options.tracer ?? {
+                    traceAsync: async (name, fn) => await traceAsync(name, (span) => fn(span)),
+                },
+            });
         this.defaultCwd = options.defaultCwd;
         this.defaultTimeout = options.defaultTimeout;
+        this.logger = options.logger ?? getLogger('ai-runner');
+        this.events = options.events;
     }
 
     /** Run an agent help command. */
@@ -62,14 +98,22 @@ export class AiRunner {
         promptOptions: PromptOptions,
         options: AgentRunOptions = {},
     ): Promise<AgentRunResult> {
-        const enrichedPromptOptions = this.withIdentityPreamble(agent, promptOptions, options);
-        return this.invoke(
-            agent,
-            'prompt',
-            getAgentShim(agent).getPromptCommand(enrichedPromptOptions),
-            options,
-            false,
-        );
+        return this.invoke(agent, 'prompt', this.buildPromptCommand(agent, promptOptions, options), options, false);
+    }
+
+    /** Translate a Claude-style slash command and run it as a prompt command. */
+    runSlashCommand(
+        agent: AgentName,
+        input: string,
+        promptOptions: PromptOptions,
+        options: AgentRunOptions = {},
+    ): Promise<AgentRunResult> {
+        return this.runPromptCommand(agent, { ...promptOptions, input: translateSlashCommand(agent, input) }, options);
+    }
+
+    /** Build an agent prompt command without executing it. */
+    buildPromptCommand(agent: AgentName, promptOptions: PromptOptions, options: AgentRunOptions = {}): ShimCommand {
+        return getAgentShim(agent).getPromptCommand(this.withIdentityPreamble(agent, promptOptions, options));
     }
 
     /** Run an agent authentication command, or return null when unsupported. */
@@ -85,15 +129,33 @@ export class AiRunner {
         options: AgentRunOptions,
         forceBuffered: boolean,
     ): Promise<AgentRunResult> {
+        const label = `ai-runner.${agent}.${operation}`;
+        this.logger.debug('invoke', { label, command: command.command, args: command.args.join(' ') });
+        void this.events?.emit('agent.invoke.start', { agent, operation, label });
         const result: ProcessResult = await this.processExecutor.run({
             command: command.command,
             args: command.args,
-            label: `ai-runner.${agent}.${operation}`,
+            label,
             rejectOnError: false,
             forceBuffered,
             cwd: options.cwd ?? this.defaultCwd,
             timeout: options.timeout ?? this.defaultTimeout,
         });
+        if (result.exitCode !== 0) {
+            this.logger.error('invoke exited non-zero', {
+                label,
+                exitCode: result.exitCode,
+                signal: result.signal,
+            });
+        }
+        void this.events?.emit('agent.invoke.exit', {
+            agent,
+            operation,
+            label,
+            exitCode: result.exitCode,
+            ...(result.signal !== undefined ? { signal: result.signal } : {}),
+            durationMs: result.durationMs,
+        });
         return {
             exitCode: result.exitCode,
             stdout: result.stdout,
@@ -109,7 +171,7 @@ export class AiRunner {
         options: AgentRunOptions,
     ): PromptOptions {
         if (!hasIdentityOptions(promptOptions)) return promptOptions;
-        const workspace = options.cwd ?? this.defaultCwd ?? process.cwd();
+        const workspace = options.cwd ?? this.defaultCwd ?? getProcessCwd();
         const preamble = buildIdentityPreamble({
             agentId: agent,
             agentType: agent,

package/src/doctor-runner.ts

@@ -1,9 +1,8 @@
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { getProcessEnv, NodeFileSystem } from '@gobing-ai/ts-runtime';
+import { getLogger, type Logger } from '@gobing-ai/ts-infra';
+import { getProcessEnv, joinPath, 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';
+import { type AgentName, DISPLAY_ORDER, isAgentName, TIER2_AGENTS } from './agents/shims';
+import { type AgentRunResult, AiRunner } from './ai-runner';
 
 /** Health-check result for one coding agent. */
 export interface DoctorResult {
@@ -35,9 +34,34 @@ export interface DoctorRunnerOptions {
     timeout?: number;
     /** Environment map for file/env auth checks. */
     env?: Record<string, string | undefined>;
+    /** Logger for health-check diagnostics. Defaults to `getLogger('doctor')`. */
+    logger?: Logger;
 }
 
 const DEFAULT_TIMEOUT_MS = 5_000;
+const AUTH_PATTERNS: Partial<Record<AgentName, { positive: RegExp; negative: RegExp }>> = {
+    claude: {
+        positive: /authenticated|logged[\s_-]*in|"loggedIn"\s*:\s*true/i,
+        negative:
+            /not[\s_-]*authenticated|not[\s_-]*logged[\s_-]*in|logged[\s_-]*out|unauthenticated|"loggedIn"\s*:\s*false/i,
+    },
+    codex: {
+        positive: /logged[\s_-]*in|authenticated/i,
+        negative: /not[\s_-]*authenticated|not[\s_-]*logged[\s_-]*in|logged[\s_-]*out|unauthenticated/i,
+    },
+    opencode: {
+        positive: /configured|available/i,
+        negative: /not[\s_-]*configured|no[\s_-]+providers?[\s_-]+available|unavailable/i,
+    },
+    openclaw: {
+        positive: /(^|[^a-z])ok([^a-z]|$)|healthy/i,
+        negative: /not[\s_-]*healthy|unhealthy|not[\s_-]*ok/i,
+    },
+    pi: {
+        positive: /\S/,
+        negative: /not[\s_-]*authenticated|not[\s_-]*logged[\s_-]*in|unauthenticated|no[\s_-]+providers?/i,
+    },
+};
 
 /** True when a value is a defined, non-blank string. */
 function isNonEmpty(value: string | undefined): boolean {
@@ -51,18 +75,33 @@ export class DoctorRunner {
     private readonly timeout: number;
     private readonly env: Record<string, string | undefined>;
     private readonly fs = new NodeFileSystem();
+    private readonly logger: Logger;
 
     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();
+        this.logger = options.logger ?? getLogger('doctor');
     }
 
     /** 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)));
+        const byName = new Map(detected.map((agent) => [agent.name, agent]));
+        return await Promise.all(
+            DISPLAY_ORDER.map((agent) =>
+                this.buildResult(
+                    byName.get(agent) ?? {
+                        name: agent,
+                        installed: false,
+                        version: null,
+                        channels: [],
+                        error: `Unknown agent: ${agent}`,
+                    },
+                ),
+            ),
+        );
     }
 
     /** Run a health check on one agent. */
@@ -72,6 +111,7 @@ export class DoctorRunner {
 
     private async buildResult(detected: DetectedAgent): Promise<DoctorResult> {
         const tier = TIER2_AGENTS.has(detected.name as AgentName) ? 2 : 1;
+        this.logger.debug('checking agent', { agent: detected.name, installed: detected.installed, tier });
         const authenticated =
             detected.installed && isAgentName(detected.name) ? await this.checkAuth(detected.name) : false;
         return {
@@ -87,24 +127,45 @@ export class DoctorRunner {
     }
 
     private async checkAuth(agent: AgentName): Promise<boolean> {
-        // gemini/codex expose no auth-status command; treat a non-empty credential
-        // file as authenticated. An empty/zero-byte file is a stale-credential
-        // false positive, so existence alone is insufficient.
-        if (agent === 'gemini') return this.hasNonEmptyFile(join(homedir(), '.gemini', 'settings.json'));
-        if (agent === 'codex' && (await this.hasNonEmptyFile(join(homedir(), '.codex', 'auth.json')))) return true;
+        const home = this.env.HOME || this.env.USERPROFILE || '';
+        if (agent === 'gemini') return this.geminiSettingsContainCredentials(home);
+        if (agent === 'codex') return this.checkCodexAuth(home);
         // pi reads provider keys from the environment; require a non-empty value
         // rather than mere presence (an empty export is not a usable credential).
         if (agent === 'pi' && (isNonEmpty(this.env.GOOGLE_API_KEY) || isNonEmpty(this.env.ANTHROPIC_API_KEY)))
             return true;
-        const command = this.runner.runAuthCommand(agent, { timeout: this.timeout });
-        if (command === null) return false;
-        const result = await command;
+        return (await this.probeAuthOutput(agent)) === true;
+    }
+
+    private async checkCodexAuth(home: string): Promise<boolean> {
+        const probeStatus = await this.probeAuthOutput('codex');
+        if (probeStatus !== null) return probeStatus;
         return (
-            result.exitCode === 0 &&
-            !/not authenticated|not logged|unauthenticated/i.test(`${result.stdout}\n${result.stderr}`)
+            (await this.hasNonEmptyFile(joinPath(home, '.codex', 'auth.json'))) ||
+            (await this.hasNonEmptyFile(joinPath(home, '.codex', 'auth')))
         );
     }
 
+    private async geminiSettingsContainCredentials(home: string): Promise<boolean> {
+        try {
+            return /auth|token|key/i.test(await this.fs.readFile(joinPath(home, '.gemini', 'settings.json')));
+        } catch {
+            return false;
+        }
+    }
+
+    private async probeAuthOutput(agent: AgentName): Promise<boolean | null> {
+        const command = this.runner.runAuthCommand(agent, { timeout: this.timeout });
+        const patterns = AUTH_PATTERNS[agent];
+        if (command === null || patterns === undefined) return null;
+        const result: AgentRunResult = await command;
+        if (result.exitCode !== 0) return false;
+        const output = `${result.stdout}\n${result.stderr}`;
+        if (patterns.negative.test(output)) return false;
+        if (patterns.positive.test(output)) return true;
+        return null;
+    }
+
     /** True when the path exists and has a non-zero size. */
     private async hasNonEmptyFile(path: string): Promise<boolean> {
         const stat = await this.fs.stat(path);

package/src/events.ts

@@ -0,0 +1,25 @@
+import type { ProcessEvents } from '@gobing-ai/ts-runtime';
+
+/** Typed event map for agent-runner observability. All events prefixed `agent.`. */
+export type AgentEvents = {
+    /** Emitted immediately before an agent CLI invocation starts. */
+    'agent.invoke.start': (data: { agent: string; operation: string; label: string }) => void;
+    /** Emitted after an agent CLI invocation exits. */
+    'agent.invoke.exit': (data: {
+        agent: string;
+        operation: string;
+        label: string;
+        exitCode: number | null;
+        signal?: string;
+        durationMs: number;
+    }) => void;
+    /** Emitted when a long-running team agent process starts. */
+    'agent.started': (data: { agentId: string; agentType: string; pid: number | null }) => void;
+    /** Emitted when a long-running team agent process stops. */
+    'agent.stopped': (data: { agentId: string; exitCode: number | null }) => void;
+    /** Emitted when a message is sent to a team agent process. */
+    'agent.message.sent': (data: { agentId: string; ok: boolean }) => void;
+};
+
+/** Event map for process-level observability emitted by AiRunner-owned executors. */
+export type AiRunnerProcessEvents = ProcessEvents;