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

package/README.md

@@ -1,6 +1,12 @@
 # @gobing-ai/ts-ai-runner
 
-Coding-agent command shims, installation detection, doctor checks, slash-command translation, and prompt execution for downstream CLIs.
+Coding-agent command shims, installation detection, doctor checks, slash-command translation, identity preamble construction, and team-mode orchestration for downstream CLIs.
+
+## Installation
+
+```bash
+bun add @gobing-ai/ts-ai-runner
+```
 
 ## What It Provides
 
@@ -8,26 +14,175 @@ Coding-agent command shims, installation detection, doctor checks, slash-command
 
 | Export | Purpose |
 |--------|---------|
-| `AiRunner` | Runs help, version, auth, and prompt commands through a pluggable process executor |
+| `AiRunner` | Runs help, version, auth, prompt, and slash commands through a pluggable process executor; can also build a prompt command without executing it. Emits typed events via optional `EventBus<AgentEvents>`. |
 | `AgentDetector` | Probes supported agent CLIs and parses version output |
 | `DoctorRunner` | Combines installation and authentication checks into a usability report |
 | `getAgentShim()` | Returns the pure command builder for one supported agent |
 | `translateSlashCommand()` | Converts Claude-style `/plugin:command` inputs to each agent's dialect |
-| `buildIdentityPreamble()` | Builds team-mode identity and communication context for prompts |
-| `loadAgentSpecs()` / `saveAgentSpec()` | Persist agent definitions as YAML-compatible config |
+| `isClaudeStyleSlashCommand()` | Tests whether input matches the `/plugin:command` pattern |
+| `buildIdentityPreamble()` / `getGitContext()` | Builds team-mode identity, communication context, and git metadata for prompts |
+| `loadAgentSpecs()` / `saveAgentSpec()` / `deleteAgentSpec()` | Persist agent definitions as YAML-compatible config |
+| `validateAgentId()` | Enforces agent ID format rules |
 | `MessageService` | Thin service wrapper around `@gobing-ai/ts-db/inbox` |
 | `TeamAgentProcess` | Manages a long-running agent subprocess with pipe-mode stdin/stdout |
-| `TeamOrchestrator` | Loads specs, starts/stops agents, and routes durable/live messages |
-
-Supported agent identifiers are `claude`, `codex`, `gemini`, `pi`, `opencode`, `antigravity`, and `openclaw`.
+| `TeamOrchestrator` | Loads specs, starts/stops agents, routes durable/live messages, and emits lifecycle events |
+| `AgentEvents` / `AiRunnerProcessEvents` | Typed event maps for agent and process-level observability |
+| `AGENT_SHIMS` / `TIER1_PRIORITY` / `TIER2_AGENTS` / `DISPLAY_ORDER` | Agent registry constants |
+| `isAgentName()` | Type guard for supported agent identifiers |
+
+Supported agent identifiers: `claude`, `codex`, `gemini`, `pi`, `opencode` (tier 1), `antigravity`, `openclaw` (tier 2).
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph Shared ["Shared components"]
+        AgentShim["AgentShim<br/>(pure command builder per agent)"]
+        Identity["buildIdentityPreamble()<br/>(team-mode identity context)"]
+        EventBus["EventBus&lt;AgentEvents&gt;<br/>(opt-in observability)"]
+        ProcessExecutor["ProcessExecutor<br/>(injectable, ts-runtime)"]
+    end
+
+    subgraph OneShot ["One-shot mode"]
+        AiRunner["AiRunner<br/>runPromptCommand / runSlashCommand<br/>buildPromptCommand / runHelpCommand<br/>runVersionCommand / runAuthCommand"]
+        AgentDetector["AgentDetector<br/>(probes CLIs via AiRunner)"]
+        DoctorRunner["DoctorRunner<br/>(install + auth health checks)"]
+
+        AiRunner -->|"resolves command via"| AgentShim
+        AiRunner -->|"delegates execution to"| ProcessExecutor
+        AgentDetector -->|"probes versions via"| AiRunner
+        DoctorRunner -->|"probes install + auth via"| AiRunner
+        AiRunner -.->|"emits events"| EventBus
+        AiRunner -.->|"enriches prompt"| Identity
+    end
+
+    subgraph TeamMode ["Team mode (building blocks)"]
+        TeamOrchestrator["TeamOrchestrator<br/>loadSpecs / startAgent / stopAgent<br/>sendMessage / getAgentStatus / stopAll"]
+        AgentSpec["AgentSpec<br/>(YAML config)<br/>load / save / delete"]
+        TeamAgentProcess["TeamAgentProcess<br/>(pipe-mode subprocess)<br/>start / stop / send / subscribe"]
+        MessageService["MessageService<br/>(InboxMessageDao wrapper)<br/>enqueue / drain / deliver / fail"]
+
+        TeamOrchestrator -->|"loads"| AgentSpec
+        TeamOrchestrator -->|"creates + manages"| TeamAgentProcess
+        TeamOrchestrator -->|"routes through"| MessageService
+        TeamOrchestrator -->|"resolves command via"| AgentShim
+        TeamOrchestrator -.->|"emits events"| EventBus
+        TeamOrchestrator -.->|"builds preamble"| Identity
+        TeamAgentProcess -->|"spawns via"| ProcessExecutor
+    end
+```
 
-## Installation
+### One-shot prompt flow
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant AiRunner
+    participant AgentShim
+    participant Identity as buildIdentityPreamble
+    participant Slash as translateSlashCommand
+    participant Executor as ProcessExecutor
+    participant Agent as Coding Agent (CLI)
+    participant EventBus
+
+    Caller->>AiRunner: runPromptCommand("codex", options)
+    AiRunner->>AiRunner: hasIdentityOptions(options)?
+    alt has team-mode fields
+        AiRunner->>Identity: buildIdentityPreamble({agentId, peers, ...})
+        Identity-->>AiRunner: preamble text
+        AiRunner->>AiRunner: prepend preamble to input
+    end
+    AiRunner->>AgentShim: getPromptCommand(enrichedOptions)
+    AgentShim-->>AiRunner: { command, args }
+    AiRunner->>EventBus: emit("agent.invoke.start")
+    AiRunner->>Executor: run({ command, args, cwd, timeout })
+    Executor->>Agent: spawn CLI subprocess
+    Agent-->>Executor: stdout / stderr / exit
+    Executor-->>AiRunner: ProcessResult { exitCode, stdout, stderr, durationMs }
+    AiRunner->>EventBus: emit("agent.invoke.exit")
+    AiRunner-->>Caller: AgentRunResult
+```
 
-```bash
-bun add @gobing-ai/ts-ai-runner
+`runSlashCommand()` follows the same path with an extra step: it calls `translateSlashCommand()` to convert the slash input to the target agent's dialect before delegating to `runPromptCommand()`.
+
+### Team mode lifecycle
+
+```mermaid
+sequenceDiagram
+    participant Host as Host App
+    participant Orch as TeamOrchestrator
+    participant Spec as AgentSpec (filesystem)
+    participant Shim as AgentShim
+    participant Identity as buildIdentityPreamble
+    participant Proc as TeamAgentProcess
+    participant Msg as MessageService
+    participant DB as InboxMessageDao
+    participant Agent as Coding Agent (CLI)
+    participant EventBus
+
+    Note over Host,EventBus: Starting an agent
+    Host->>Orch: startAgent("coder")
+    Orch->>Spec: loadAgentSpecs(configDir)
+    Spec-->>Orch: AgentSpec[]
+    Orch->>Orch: requireSpec("coder") → spec
+    Orch->>Orch: getPeerSpecs(workspace, "coder") → peers
+    Orch->>Identity: buildIdentityPreamble({agentId, peers, ...})
+    Identity-->>Orch: preamble
+    Orch->>Shim: getPromptCommand({input: preamble, ...})
+    Shim-->>Orch: { command, args }
+    Orch->>Proc: new TeamAgentProcess({spec, command})
+    Orch->>Proc: start()
+    Proc->>Agent: spawn pipe-mode subprocess
+    Agent-->>Proc: stdout/stderr streams
+    Orch->>Msg: drain("coder")
+    Msg->>DB: drain(toId)
+    DB-->>Msg: pending messages
+    Msg-->>Orch: messages[]
+    alt pending messages exist
+        loop for each message
+            Orch->>Proc: send(formattedMessage)
+            Proc->>Agent: write to stdin
+            Orch->>Msg: deliver(msg.id)
+        end
+    end
+    Orch->>EventBus: emit("agent.started")
+    Orch-->>Host: TeamAgentProcess
+
+    Note over Host,EventBus: Sending a message (durable + live)
+    Host->>Orch: sendMessage(null, "coder", "Implement task 0005")
+    Orch->>Msg: enqueue(null, "coder", body)
+    Msg->>DB: enqueue(from, to, body)
+    DB-->>Msg: messageId
+    Msg-->>Orch: messageId
+    alt agent is running
+        Orch->>Msg: drain("coder")
+        Msg->>DB: drain(toId)
+        DB-->>Msg: pending messages
+        loop for each message
+            Orch->>Proc: send(formattedMessage)
+            Proc->>Agent: write to stdin
+            Orch->>Msg: deliver(msg.id)
+        end
+    end
+    Orch->>EventBus: emit("agent.message.sent")
+    Orch-->>Host: messageId
+
+    Note over Host,EventBus: Stopping an agent
+    Host->>Orch: stopAgent("coder")
+    Orch->>Proc: stop()
+    Proc->>Agent: SIGTERM / kill
+    Orch->>Orch: running.delete("coder")
+    Orch->>EventBus: emit("agent.stopped")
+    Orch-->>Host: void
 ```
 
-The package depends on `@gobing-ai/ts-runtime` for process execution and `@gobing-ai/ts-db` for team-mode inbox types. The target agent CLIs are not bundled; install them separately in the host environment.
+Key design decisions:
+
+- **Shims are pure**: `AgentShim` produces `{ command, args }` without touching the filesystem or launching processes. All side effects live in `AiRunner` and `TeamAgentProcess`.
+- **ProcessExecutor is injectable**: tests inject a stub executor; production uses `NodeProcessExecutor` (or the Bun pipe-process seam for team mode).
+- **Events are opt-in**: `AiRunnerOptions.events` and `TeamOrchestratorOptions.events` accept an `EventBus<AgentEvents>` for structured observability. Without it, the runner is silent.
+- **Team mode is composable**: `AgentSpec`, `TeamAgentProcess`, `MessageService`, and `TeamOrchestrator` are small building blocks. Downstream apps compose them into their own orchestration layer.
+
+The package depends on `@gobing-ai/ts-runtime` for process execution, `@gobing-ai/ts-db` for team-mode inbox types, and `@gobing-ai/ts-infra` for structured logging and EventBus. The target agent CLIs are not bundled; install them separately in the host environment.
 
 ## Detect Installed Agents
 
@@ -78,12 +233,27 @@ console.log(result.stdout);
 
 `AiRunner` captures `stdout`, `stderr`, `exitCode`, optional termination `signal`, and `durationMs`. It does not throw on non-zero agent exits; callers decide how to handle failures.
 
+Every invocation is logged through an injectable logger (`getLogger('ai-runner')` by default): one `debug` line per dispatch and an `error` line on any non-zero exit. Pass a custom `logger` to the constructor to route diagnostics elsewhere or silence them in tests.
+
+### Slash commands and command preview
+
+`runSlashCommand()` translates a Claude-style `/plugin:command args` input into the target agent's dialect (via `translateSlashCommand()`) and dispatches it as a prompt. Non-slash input passes through unchanged.
+
+```ts
+// For codex, "/review:pr 123" becomes "$review-pr 123" before dispatch.
+await runner.runSlashCommand('codex', '/review:pr 123', { model: 'gpt-5' });
+```
+
+`buildPromptCommand()` returns the resolved `{ command, args }` **without** executing it — useful for previewing, logging, or dry-running the exact argv a prompt would dispatch. It applies the same identity-preamble enrichment as `runPromptCommand()`.
+
+```ts
+const { command, args } = runner.buildPromptCommand('pi', { input: 'ship it', mode: 'json' });
+// command === 'pi', args === ['--no-session', '-p', 'ship it', '--mode', 'json']
+```
+
 ### Team identity preambles
 
-`PromptOptions` accepts optional team-mode fields. When any of `purpose`, `systemPrompt`, `taskId`,
-or non-empty `peers` is supplied, `AiRunner` prepends an identity preamble before dispatching the
-prompt through the selected agent shim. Existing callers that only pass `input`, `continue`, `model`,
-or `mode` are unchanged.
+`PromptOptions` accepts optional team-mode fields. When any of `purpose`, `systemPrompt`, `taskId`, or non-empty `peers` is supplied, `AiRunner` prepends an identity preamble before dispatching the prompt through the selected agent shim.
 
 ```ts
 await runner.runPromptCommand('codex', {
@@ -95,8 +265,7 @@ await runner.runPromptCommand('codex', {
 });
 ```
 
-Use `buildIdentityPreamble()` directly when a host app needs to preview or inject the same context
-outside `AiRunner`:
+Use `buildIdentityPreamble()` directly when a host app needs to preview or inject the same context outside `AiRunner`:
 
 ```ts
 import { buildIdentityPreamble } from '@gobing-ai/ts-ai-runner';
@@ -113,6 +282,43 @@ const preamble = buildIdentityPreamble({
 });
 ```
 
+Use `getGitContext()` to auto-detect the current branch and dirty state:
+
+```ts
+import { getGitContext } from '@gobing-ai/ts-ai-runner';
+
+const gitBlock = getGitContext('/workspace/spur');
+// "Git context:\nbranch: feat/team-mode\ndirty: 3 files"
+```
+
+## Observability
+
+`AiRunner` and `TeamOrchestrator` emit typed events when an `EventBus<AgentEvents>` is provided:
+
+```ts
+import { AiRunner } from '@gobing-ai/ts-ai-runner';
+import { EventBus } from '@gobing-ai/ts-infra';
+import type { AgentEvents } from '@gobing-ai/ts-ai-runner';
+
+const bus = new EventBus<AgentEvents>();
+bus.on('agent.invoke.start', (data) => console.log('starting', data.label));
+bus.on('agent.invoke.exit', (data) => console.log('done', data.label, data.exitCode, data.durationMs));
+
+const runner = new AiRunner({ events: bus });
+```
+
+Available events:
+
+| Event | When |
+|-------|------|
+| `agent.invoke.start` | Immediately before an agent CLI invocation starts |
+| `agent.invoke.exit` | After an agent CLI invocation exits |
+| `agent.started` | When a long-running team agent process starts |
+| `agent.stopped` | When a long-running team agent process stops |
+| `agent.message.sent` | When a message is sent to a team agent process |
+
+`AiRunnerOptions.processEvents` accepts a separate `EventBus<AiRunnerProcessEvents>` for process-level events from the underlying executor.
+
 ## Inject a Process Executor
 
 For tests, dry runs, or sandboxed launchers, inject a `ProcessExecutor` from `@gobing-ai/ts-runtime`:
@@ -182,7 +388,7 @@ translateSlashCommand('pi', '/rd3:dev-fixall bun run check');
 // /skill:rd3-dev-fixall bun run check
 ```
 
-Non-slash input is returned unchanged.
+Non-slash input is returned unchanged. Use `isClaudeStyleSlashCommand()` to test input before translation.
 
 ## Command Shims
 
@@ -197,17 +403,41 @@ const command = shim.getPromptCommand({ input: 'Summarize this repository' });
 console.log(command.command, command.args);
 ```
 
+Each shim implements the `AgentShim` interface:
+
+```ts
+interface AgentShim {
+    readonly name: AgentName;
+    readonly command: string;
+    readonly tier: 1 | 2;
+    getHelpCommand(): ShimCommand;
+    getVersionCommand(): ShimCommand;
+    getPromptCommand(options: PromptOptions): ShimCommand;
+    getAuthCommand(): ShimCommand | null;
+}
+```
+
+Agent-specific behavior:
+
+| Agent | CLI | Tier | Auth check | Prompt flags |
+|-------|-----|------|------------|--------------|
+| `claude` | `claude` | 1 | `claude auth status` | `-p`, `--continue`, `--model`, `--output-format` |
+| `codex` | `codex` | 1 | `codex login status` | `exec <prompt>`, `exec resume --last`, `-m`, `--json` |
+| `gemini` | `gemini` | 1 | env-only | `-p`, `-r latest` (resume), `-m`, `-o` |
+| `pi` | `pi` | 1 | `pi --list-models` | `--no-session`, `-p`, `-c` (resume), `--model`, `--mode` |
+| `opencode` | `opencode` | 1 | `opencode providers` | `run`, `-c`, `-m`, `--format json` |
+| `antigravity` | `agy` | 2 | env-only | `chat` |
+| `openclaw` | `openclaw` | 2 | `openclaw health` | `agent --local -m` |
+
 This is the right layer for UI previews, audit logging, and custom launchers.
 
 ## Team Mode Primitives
 
-The team-mode APIs are intentionally small building blocks. They do not implement an HTTP API,
-dashboard, or product workflow; downstream apps compose them into their own orchestration layer.
+The team-mode APIs are intentionally small building blocks. They do not implement an HTTP API, dashboard, or product workflow; downstream apps compose them into their own orchestration layer.
 
 ### Agent specs
 
-Agent specs define agents as config. The built-in parser supports the repository's constrained YAML
-subset: scalars, arrays, nested objects, and no anchors/tags/multiline scalars.
+Agent specs define agents as config. The built-in parser supports the repository's constrained YAML subset: scalars, arrays, nested objects, and no anchors/tags/multiline scalars.
 
 ```ts
 import { loadAgentSpecs, saveAgentSpec } from '@gobing-ai/ts-ai-runner';
@@ -229,12 +459,11 @@ await saveAgentSpec(
 const specs = loadAgentSpecs('./agents');
 ```
 
-`validateAgentId()` enforces lowercase agent ids with alphanumeric, `_`, and `-` characters.
+`validateAgentId()` enforces lowercase agent ids with alphanumeric, `_`, and `-` characters (2–64 chars). `deleteAgentSpec()` removes a spec file by id.
 
 ### Durable messages
 
-`MessageService` wraps `InboxMessageDao` from `@gobing-ai/ts-db/inbox`. It owns no subprocess
-behavior; it only persists, drains, marks delivery/failure, and formats messages.
+`MessageService` wraps `InboxMessageDao` from `@gobing-ai/ts-db/inbox`. It owns no subprocess behavior; it only persists, drains, marks delivery/failure, and formats messages.
 
 ```ts
 import { InboxMessageDao } from '@gobing-ai/ts-db/inbox';
@@ -251,10 +480,11 @@ for (const msg of pending) {
 }
 ```
 
+`MessageService` also exposes `fail(msgId, error)`, `inbox(toId, limit?, offset?)`, and `countPending(toId)`.
+
 ### Persistent agent processes
 
-`TeamAgentProcess` wraps a long-running agent subprocess using the runtime pipe-process seam. It
-supports start/stop, stdin sends, stdout/stderr subscriptions, status, pid, and exit-code queries.
+`TeamAgentProcess` wraps a long-running agent subprocess using the runtime pipe-process seam. It supports start/stop, stdin sends, stdout/stderr subscriptions, status, pid, and exit-code queries.
 
 ```ts
 import { TeamAgentProcess, type AgentSpec } from '@gobing-ai/ts-ai-runner';
@@ -286,10 +516,7 @@ unsubscribe();
 
 ### Team orchestrator
 
-`TeamOrchestrator` connects specs, shims, processes, and messages. On start it loads an agent spec,
-builds the agent command through the matching shim, starts the process, drains pending inbox messages,
-and injects them live. `sendMessage()` always persists first, then injects immediately when the target
-agent is running.
+`TeamOrchestrator` connects specs, shims, processes, and messages. On start it loads an agent spec, builds the agent command through the matching shim, starts the process, drains pending inbox messages, and injects them live. `sendMessage()` always persists first, then injects immediately when the target agent is running.
 
 ```ts
 import { InboxMessageDao } from '@gobing-ai/ts-db/inbox';
@@ -306,10 +533,87 @@ console.log(team.getAgentStatus('coder')); // running
 await team.stopAll();
 ```
 
+The orchestrator also provides `restartAgent(id)`, `getRunningAgents()`, `getPeerSpecs(workspace, excludeId?)`, and `on(event, listener)` for event subscription.
+
+## Adding a New Coding Agent
+
+To add support for a new coding agent (e.g. `amp`), follow these steps:
+
+### 1. Add the shim
+
+Edit `src/agents/shims.ts`. Add a new constant implementing the `AgentShim` interface:
+
+```ts
+const ampShim: AgentShim = {
+    name: 'amp',
+    command: 'amp',
+    tier: 1,  // or 2 if gateway/TUI-constrained
+    getHelpCommand: () => ({ command: 'amp', args: ['--help'] }),
+    getVersionCommand: () => ({ command: 'amp', args: ['--version'] }),
+    getPromptCommand: (options) => {
+        const args = ['run', options.input ?? ''];
+        if (options.continue === true) args.push('--resume');
+        if (options.model !== undefined) args.push('--model', options.model);
+        if ((options.mode ?? 'text') === 'json') args.push('--json');
+        return { command: 'amp', args };
+    },
+    getAuthCommand: () => ({ command: 'amp', args: ['auth', 'status'] }),
+};
+```
+
+### 2. Register the shim
+
+In the same file, add the new agent to these three places:
+
+```ts
+// 1. The AgentName union type
+export type AgentName = 'claude' | 'codex' | 'gemini' | 'pi' | 'opencode' | 'antigravity' | 'openclaw' | 'amp';
+
+// 2. The AGENT_SHIMS registry
+export const AGENT_SHIMS: Readonly<Record<AgentName, AgentShim>> = {
+    // ...existing entries...
+    amp: ampShim,
+};
+
+// 3. DISPLAY_ORDER (determines doctor/detector output order)
+export const DISPLAY_ORDER: readonly AgentName[] = [
+    'claude', 'codex', 'gemini', 'pi', 'opencode', 'antigravity', 'openclaw', 'amp',
+];
+```
+
+If the agent is tier 1, add it to `TIER1_PRIORITY`. If tier 2 (gateway/TUI-constrained), add it to `TIER2_AGENTS`.
+
+### 3. Add slash-command dialect (if needed)
+
+If the agent uses a different slash-command syntax than the default `/{plugin}-{command} args` mapping, add a case to `translateSlashCommand()` in `src/slash-command.ts`.
+
+### 4. Add auth detection (if applicable)
+
+If the agent supports an auth-status command, `getAuthCommand()` already returns it and `DoctorRunner` will probe it automatically. For env-only or file-based auth, add a pattern to `AUTH_PATTERNS` in `src/doctor-runner.ts`.
+
+### 5. Add tests
+
+- **Shim tests**: add cases to `tests/agents/` verifying command construction for help, version, prompt (with and without options), and auth.
+- **Detector tests**: verify `detectOne('amp')` handles version output and error cases.
+- **Doctor tests**: verify auth probe for the new agent.
+
+### Summary checklist
+
+| Step | File | What to change |
+|------|------|----------------|
+| Shim | `src/agents/shims.ts` | Add `AgentShim` impl, update `AgentName`, `AGENT_SHIMS`, `DISPLAY_ORDER` |
+| Tier | `src/agents/shims.ts` | Add to `TIER1_PRIORITY` or `TIER2_AGENTS` |
+| Slash | `src/slash-command.ts` | Add case if dialect differs from default |
+| Auth | `src/doctor-runner.ts` | Add `AUTH_PATTERNS` entry if file/env-based |
+| Tests | `tests/` | Shim, detector, and doctor coverage |
+
+After these changes, the new agent is automatically available to `AiRunner`, `AgentDetector`, `DoctorRunner`, `TeamOrchestrator`, and all downstream consumers — no further registration needed.
+
 ## Boundary Notes
 
 - This package is a command adapter, not an agent orchestration framework.
 - It does not install agent CLIs or manage credentials.
 - It does not parse agent responses beyond process result capture.
-- It keeps subprocess launching behind `ProcessExecutor` / `PipeProcessSpawner`, so tests can stay deterministic.
+- It keeps subprocess launching behind `ProcessExecutor` / `PipeProcess`, so tests can stay deterministic.
 - Team-mode persistence is delegated to `@gobing-ai/ts-db/inbox`; host apps own migrations and adapter lifecycle.
+- Platform APIs (`node:fs`, `node:path`, `Bun.spawn`, etc.) are confined to `@gobing-ai/ts-runtime` per ADR-011. This package accesses them through the runtime's `FileSystem`, `ProcessExecutor`, and path utilities.

package/dist/agent-detector.d.ts

@@ -30,5 +30,6 @@ export declare class AgentDetector {
     /** Probe one agent by name. */
     detectOne(agent: string): Promise<DetectedAgent>;
     private parseResult;
+    private detectChannels;
 }
 //# sourceMappingURL=agent-detector.d.ts.map

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

@@ -1 +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;IAStD,OAAO,CAAC,WAAW;CAyBtB"}
+{"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;IAStD,OAAO,CAAC,WAAW;IA8BnB,OAAO,CAAC,cAAc;CAIzB"}

package/dist/agent-detector.js

@@ -32,24 +32,32 @@ 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,
         };
     }
+    detectChannels(_agent, _output) {
+        // 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. */
 function unavailable(name, error) {

package/dist/agent-spec.d.ts

@@ -1,4 +1,5 @@
 import { type SyncFileSystem } from '@gobing-ai/ts-runtime';
+/** Specification for an AI agent defined in the configuration directory. */
 export interface AgentSpec {
     id: string;
     name: string;
@@ -9,11 +10,16 @@ export interface AgentSpec {
     config: Record<string, unknown>;
     autoStart?: boolean;
 }
+/** Validation error thrown when agent spec data is malformed or invalid. */
 export declare class ValueError extends Error {
     constructor(message: string);
 }
+/** Validate that `id` matches the agent ID format: 2-64 chars, lowercase alphanumeric with `_` or `-`. Returns the id on success, throws `ValueError` otherwise. */
 export declare function validateAgentId(id: string): string;
+/** Load and validate all YAML agent spec files from `configDir`. Throws `ValueError` on parse failures or duplicate IDs. */
 export declare function loadAgentSpecs(configDir: string, fs?: SyncFileSystem): AgentSpec[];
+/** Serialize `spec` to YAML and write it to `configDir/<id>.yaml`. Creates the directory if missing. */
 export declare function saveAgentSpec(spec: AgentSpec, configDir: string, fs?: SyncFileSystem): Promise<void>;
+/** Remove the YAML file for agent `id` from `configDir`. Does nothing if the file doesn't exist. */
 export declare function deleteAgentSpec(id: string, configDir: string, fs?: SyncFileSystem): Promise<void>;
 //# sourceMappingURL=agent-spec.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"agent-spec.d.ts","sourceRoot":"","sources":["../src/agent-spec.ts"],"names":[],"mappings":"AACA,OAAO,EAAuC,KAAK,cAAc,EAAuB,MAAM,uBAAuB,CAAC;AAEtH,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,qBAAa,UAAW,SAAQ,KAAK;gBACrB,OAAO,EAAE,MAAM;CAI9B;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,GAAE,cAAyC,GAAG,SAAS,EAAE,CAY5G;AAED,wBAAsB,aAAa,CAC/B,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,MAAM,EACjB,EAAE,GAAE,cAAyC,GAC9C,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAsB,eAAe,CACjC,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,EAAE,GAAE,cAAyC,GAC9C,OAAO,CAAC,IAAI,CAAC,CAGf"}
+{"version":3,"file":"agent-spec.d.ts","sourceRoot":"","sources":["../src/agent-spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAKH,KAAK,cAAc,EAEtB,MAAM,uBAAuB,CAAC;AAE/B,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,4EAA4E;AAC5E,qBAAa,UAAW,SAAQ,KAAK;gBACrB,OAAO,EAAE,MAAM;CAI9B;AAED,oKAAoK;AACpK,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,4HAA4H;AAC5H,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,GAAE,cAAyC,GAAG,SAAS,EAAE,CAY5G;AAED,wGAAwG;AACxG,wBAAsB,aAAa,CAC/B,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,MAAM,EACjB,EAAE,GAAE,cAAyC,GAC9C,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,oGAAoG;AACpG,wBAAsB,eAAe,CACjC,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,EAAE,GAAE,cAAyC,GAC9C,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/agent-spec.js

@@ -1,22 +1,24 @@
-import { basename, join } from 'node:path';
-import { NodeSyncFileSystem, parseYamlObject, stringifyYamlObject } from '@gobing-ai/ts-runtime';
+import { basenamePath, joinPath, NodeSyncFileSystem, parseYamlObject, stringifyYamlObject, } from '@gobing-ai/ts-runtime';
+/** Validation error thrown when agent spec data is malformed or invalid. */
 export class ValueError extends Error {
     constructor(message) {
         super(message);
         this.name = 'ValueError';
     }
 }
+/** 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) {
     if (!/^[a-z][a-z0-9_-]{1,63}$/.test(id)) {
         throw new ValueError(`Invalid agent id "${id}": expected 2-64 chars, lowercase alphanumeric, "_" or "-"`);
     }
     return id;
 }
+/** Load and validate all YAML agent spec files from `configDir`. Throws `ValueError` on parse failures or duplicate IDs. */
 export function loadAgentSpecs(configDir, fs = new NodeSyncFileSystem()) {
     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();
     for (const spec of specs) {
         validateAgentId(spec.id);
@@ -26,14 +28,16 @@ export function loadAgentSpecs(configDir, fs = new NodeSyncFileSystem()) {
     }
     return specs;
 }
+/** Serialize `spec` to YAML and write it to `configDir/<id>.yaml`. Creates the directory if missing. */
 export async function saveAgentSpec(spec, configDir, fs = new NodeSyncFileSystem()) {
     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, configDir, fs = new NodeSyncFileSystem()) {
     validateAgentId(id);
-    fs.unlink(join(configDir, `${id}.yaml`));
+    fs.unlink(joinPath(configDir, `${id}.yaml`));
 }
 function safeReadDir(configDir, fs = new NodeSyncFileSystem()) {
     try {
@@ -76,21 +80,21 @@ function serializeAgentSpec(spec) {
 function requireString(source, key, fileName) {
     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;
 }
 function requireStringArray(source, key, fileName) {
     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;
 }
 function requireRecord(source, key, fileName) {
     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;
 }