@gobing-ai/ts-ai-runner 0.2.7 → 0.2.9

package/README.md

@@ -1,3 +1,315 @@
 # @gobing-ai/ts-ai-runner
 
-Coding-agent command shims, detection, doctor checks, and prompt execution for Bun/Node CLIs.
+Coding-agent command shims, installation detection, doctor checks, slash-command translation, and prompt execution for downstream CLIs.
+
+## What It Provides
+
+`ts-ai-runner` normalizes the command-line surface of common coding agents so application code can work with stable TypeScript APIs instead of hard-coded executable arguments.
+
+| Export | Purpose |
+|--------|---------|
+| `AiRunner` | Runs help, version, auth, and prompt commands through a pluggable process executor |
+| `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 |
+| `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`.
+
+## Installation
+
+```bash
+bun add @gobing-ai/ts-ai-runner
+```
+
+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.
+
+## Detect Installed Agents
+
+```ts
+import { AgentDetector } from '@gobing-ai/ts-ai-runner';
+
+const detector = new AgentDetector({ timeout: 5_000 });
+const agents = await detector.detectAll();
+
+for (const agent of agents) {
+    console.log(agent.name, agent.installed, agent.version, agent.error);
+}
+```
+
+Probe a single agent when you already know the target:
+
+```ts
+const codex = await detector.detectOne('codex');
+if (!codex.installed) {
+    throw new Error(codex.error ?? 'codex is not installed');
+}
+```
+
+Unknown agent names are reported as unavailable rather than throwing.
+
+## Run Agent Commands
+
+```ts
+import { AiRunner } from '@gobing-ai/ts-ai-runner';
+
+const runner = new AiRunner({
+    defaultCwd: '/workspace/project',
+    defaultTimeout: 60_000,
+});
+
+const result = await runner.runPromptCommand('codex', {
+    input: 'Review packages/runtime/src/fs.ts',
+    model: 'gpt-5',
+    mode: 'text',
+});
+
+if (result.exitCode !== 0) {
+    throw new Error(result.stderr);
+}
+
+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.
+
+### 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.
+
+```ts
+await runner.runPromptCommand('codex', {
+    input: 'Implement the inbox DAO tests',
+    taskId: '0005',
+    purpose: 'Implement scoped code changes',
+    systemPrompt: 'Follow repository AGENTS.md rules.',
+    peers: [{ id: 'planner', type: 'claude', purpose: 'Plan implementation work' }],
+});
+```
+
+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';
+
+const preamble = buildIdentityPreamble({
+    agentId: 'coder',
+    agentType: 'codex',
+    workspace: '/workspace/spur',
+    taskId: '0005',
+    taskTitle: 'Implement team mode primitives',
+    purpose: 'Make focused code changes',
+    peers: [{ id: 'reviewer', type: 'claude', purpose: 'Review correctness and risk' }],
+    guardrails: ['Do not commit without operator approval.'],
+});
+```
+
+## Inject a Process Executor
+
+For tests, dry runs, or sandboxed launchers, inject a `ProcessExecutor` from `@gobing-ai/ts-runtime`:
+
+```ts
+import type { ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { AiRunner } from '@gobing-ai/ts-ai-runner';
+
+const processExecutor: ProcessExecutor = {
+    async run(options) {
+        return {
+            exitCode: 0,
+            stdout: `${options.command} ${options.args.join(' ')}`,
+            stderr: '',
+            durationMs: 1,
+        };
+    },
+};
+
+const runner = new AiRunner({ processExecutor });
+```
+
+## Doctor Checks
+
+`DoctorRunner` verifies both installation and authentication state. Auth checks use each agent's native command when available, and known credential files or environment variables when the CLI has no auth-status command.
+
+```ts
+import { DoctorRunner } from '@gobing-ai/ts-ai-runner';
+
+const doctor = new DoctorRunner();
+const report = await doctor.runAll();
+
+const usable = report.filter((agent) => agent.usable);
+```
+
+Each result includes:
+
+```ts
+interface DoctorResult {
+    agent: string;
+    installed: boolean;
+    version: string | null;
+    authenticated: boolean;
+    usable: boolean;
+    tier: 1 | 2;
+    channels: string[];
+    error: string | null;
+}
+```
+
+Tier `1` agents support direct prompt-style CLI execution. Tier `2` agents are gateway or TUI constrained and may require adapter logic in the downstream app.
+
+## Slash Command Translation
+
+Claude-style plugin commands use `/plugin:command args`. Other agents expose different command syntaxes. Use `translateSlashCommand()` before sending user-entered slash commands to a target agent:
+
+```ts
+import { translateSlashCommand } from '@gobing-ai/ts-ai-runner';
+
+translateSlashCommand('claude', '/rd3:dev-fixall bun run check');
+// /rd3:dev-fixall bun run check
+
+translateSlashCommand('codex', '/rd3:dev-fixall bun run check');
+// $rd3-dev-fixall bun run check
+
+translateSlashCommand('pi', '/rd3:dev-fixall bun run check');
+// /skill:rd3-dev-fixall bun run check
+```
+
+Non-slash input is returned unchanged.
+
+## Command Shims
+
+If you need to inspect command construction without launching a process, use the pure shim API:
+
+```ts
+import { getAgentShim } from '@gobing-ai/ts-ai-runner';
+
+const shim = getAgentShim('codex');
+const command = shim.getPromptCommand({ input: 'Summarize this repository' });
+
+console.log(command.command, command.args);
+```
+
+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.
+
+### 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.
+
+```ts
+import { loadAgentSpecs, saveAgentSpec } from '@gobing-ai/ts-ai-runner';
+
+await saveAgentSpec(
+    {
+        id: 'coder',
+        name: 'Coder',
+        type: 'codex',
+        workspace: '/workspace/spur',
+        purpose: 'Implement scoped code changes',
+        tags: ['code'],
+        config: { model: 'gpt-5', systemPrompt: 'Follow repository rules.' },
+        autoStart: true,
+    },
+    './agents',
+);
+
+const specs = loadAgentSpecs('./agents');
+```
+
+`validateAgentId()` enforces lowercase agent ids with alphanumeric, `_`, and `-` characters.
+
+### 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.
+
+```ts
+import { InboxMessageDao } from '@gobing-ai/ts-db/inbox';
+import { MessageService } from '@gobing-ai/ts-ai-runner';
+
+const messages = new MessageService(new InboxMessageDao(adapter));
+
+const id = await messages.enqueue(null, 'coder', 'Review the runtime process seam');
+const pending = await messages.drain('coder');
+
+for (const msg of pending) {
+    console.log(MessageService.formatMessage(msg));
+    await messages.deliver(msg.id);
+}
+```
+
+### 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.
+
+```ts
+import { TeamAgentProcess, type AgentSpec } from '@gobing-ai/ts-ai-runner';
+
+const spec: AgentSpec = {
+    id: 'coder',
+    name: 'Coder',
+    type: 'codex',
+    workspace: '/workspace/spur',
+    purpose: 'Implement scoped code changes',
+    tags: [],
+    config: {},
+};
+
+const process = new TeamAgentProcess({
+    spec,
+    command: ['codex', 'exec', 'You are coder. Wait for inbox messages.'],
+});
+
+const unsubscribe = process.subscribe((chunk) => {
+    console.log(chunk.toString());
+});
+
+await process.start();
+await process.send('[task from=operator id=msg-1] Inspect packages/db');
+await process.stop();
+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.
+
+```ts
+import { InboxMessageDao } from '@gobing-ai/ts-db/inbox';
+import { MessageService, TeamOrchestrator } from '@gobing-ai/ts-ai-runner';
+
+const messages = new MessageService(new InboxMessageDao(adapter));
+const team = new TeamOrchestrator('./agents', messages);
+
+await team.startAgent('coder');
+await team.sendMessage(null, 'coder', 'Please implement task 0005');
+
+console.log(team.getAgentStatus('coder')); // running
+
+await team.stopAll();
+```
+
+## 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.
+- Team-mode persistence is delegated to `@gobing-ai/ts-db/inbox`; host apps own migrations and adapter lifecycle.

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;IAiBtD,OAAO,CAAC,WAAW;CAiDtB"}
+{"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"}

package/dist/agent-detector.js

@@ -16,20 +16,13 @@ export class AgentDetector {
     }
     /** Probe one agent by name. */
     async detectOne(agent) {
-        if (!isAgentName(agent)) {
-            return { name: agent, installed: false, version: null, channels: [], error: `Unknown agent: ${agent}` };
-        }
+        if (!isAgentName(agent))
+            return unavailable(agent, `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),
-            };
+            return unavailable(agent, error instanceof Error ? error.message : String(error));
         }
     }
     parseResult(agent, result) {
@@ -37,41 +30,17 @@ export class AgentDetector {
         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`,
-            };
+            return unavailable(agent, `${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',
-            };
+            return unavailable(agent, 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)}`,
-            };
+            return unavailable(agent, `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 unavailable(agent, 'Could not parse version output');
         }
         return {
             name: agent,
@@ -82,3 +51,7 @@ export class AgentDetector {
         };
     }
 }
+/** Build an "unavailable" detection result for an agent with the given error. */
+function unavailable(name, error) {
+    return { name, installed: false, version: null, channels: [], error };
+}

package/dist/agent-spec.d.ts

@@ -0,0 +1,19 @@
+import { type SyncFileSystem } from '@gobing-ai/ts-runtime';
+export interface AgentSpec {
+    id: string;
+    name: string;
+    type: string;
+    workspace: string;
+    purpose: string;
+    tags: string[];
+    config: Record<string, unknown>;
+    autoStart?: boolean;
+}
+export declare class ValueError extends Error {
+    constructor(message: string);
+}
+export declare function validateAgentId(id: string): string;
+export declare function loadAgentSpecs(configDir: string, fs?: SyncFileSystem): AgentSpec[];
+export declare function saveAgentSpec(spec: AgentSpec, configDir: string, fs?: SyncFileSystem): Promise<void>;
+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

@@ -0,0 +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"}

package/dist/agent-spec.js

@@ -0,0 +1,96 @@
+import { basename, join } from 'node:path';
+import { NodeSyncFileSystem, parseYamlObject, stringifyYamlObject } from '@gobing-ai/ts-runtime';
+export class ValueError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValueError';
+    }
+}
+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;
+}
+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 seen = new Set();
+    for (const spec of specs) {
+        validateAgentId(spec.id);
+        if (seen.has(spec.id))
+            throw new ValueError(`Duplicate agent id "${spec.id}" in ${configDir}`);
+        seen.add(spec.id);
+    }
+    return specs;
+}
+export async function saveAgentSpec(spec, configDir, fs = new NodeSyncFileSystem()) {
+    validateAgentId(spec.id);
+    fs.mkdir(configDir);
+    fs.writeFile(join(configDir, `${spec.id}.yaml`), serializeAgentSpec(spec));
+}
+export async function deleteAgentSpec(id, configDir, fs = new NodeSyncFileSystem()) {
+    validateAgentId(id);
+    fs.unlink(join(configDir, `${id}.yaml`));
+}
+function safeReadDir(configDir, fs = new NodeSyncFileSystem()) {
+    try {
+        return fs.readDir(configDir);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+function parseAgentSpec(source, fileName) {
+    const parsed = parseYamlObject(source);
+    const spec = {
+        id: requireString(parsed, 'id', fileName),
+        name: requireString(parsed, 'name', fileName),
+        type: requireString(parsed, 'type', fileName),
+        workspace: requireString(parsed, 'workspace', fileName),
+        purpose: requireString(parsed, 'purpose', fileName),
+        tags: requireStringArray(parsed, 'tags', fileName),
+        config: requireRecord(parsed, 'config', fileName),
+        ...(typeof parsed.autoStart === 'boolean' ? { autoStart: parsed.autoStart } : {}),
+    };
+    return spec;
+}
+function serializeAgentSpec(spec) {
+    const record = {
+        id: spec.id,
+        name: spec.name,
+        type: spec.type,
+        workspace: spec.workspace,
+        purpose: spec.purpose,
+        tags: spec.tags,
+        ...(spec.autoStart !== undefined ? { autoStart: spec.autoStart } : {}),
+        config: spec.config,
+    };
+    return stringifyYamlObject(record);
+}
+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`);
+    }
+    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`);
+    }
+    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`);
+    }
+    return value;
+}

package/dist/agents/shims.d.ts

@@ -19,6 +19,20 @@ export interface PromptOptions {
     model?: string;
     /** Output mode passed through to the agent CLI. */
     mode?: OutputMode;
+    /** Team-mode purpose included in the identity preamble. */
+    purpose?: string;
+    /** Caller-defined prompt tags. */
+    tags?: string[];
+    /** Additional system prompt rendered in the identity preamble. */
+    systemPrompt?: string;
+    /** Current task identifier included in the identity preamble. */
+    taskId?: string;
+    /** Peer agents included in the identity preamble. */
+    peers?: Array<{
+        id: string;
+        type: string;
+        purpose?: string;
+    }>;
 }
 /** Pure command builder for one coding-agent CLI. */
 export interface AgentShim {

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

@@ -1 +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"}
+{"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;IAClB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;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/ai-runner.d.ts

@@ -44,5 +44,6 @@ export declare class AiRunner {
     /** Run an agent authentication command, or return null when unsupported. */
     runAuthCommand(agent: AgentName, options?: AgentRunOptions): Promise<AgentRunResult> | null;
     private invoke;
+    private withIdentityPreamble;
 }
 //# sourceMappingURL=ai-runner.d.ts.map

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

@@ -1 +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"}
+{"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;AAGlF,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;IAW1B,4EAA4E;IAC5E,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;YAKjF,MAAM;IAyBpB,OAAO,CAAC,oBAAoB;CAmB/B"}

package/dist/ai-runner.js

@@ -1,5 +1,6 @@
 import { NodeProcessExecutor } from '@gobing-ai/ts-runtime';
 import { getAgentShim } from './agents/shims.js';
+import { buildIdentityPreamble } from './identity.js';
 /** Dispatches coding-agent CLI commands through pure command shims. */
 export class AiRunner {
     processExecutor;
@@ -20,7 +21,8 @@ export class AiRunner {
     }
     /** Run an agent prompt command. */
     runPromptCommand(agent, promptOptions, options = {}) {
-        return this.invoke(agent, 'prompt', getAgentShim(agent).getPromptCommand(promptOptions), options, false);
+        const enrichedPromptOptions = this.withIdentityPreamble(agent, promptOptions, options);
+        return this.invoke(agent, 'prompt', getAgentShim(agent).getPromptCommand(enrichedPromptOptions), options, false);
     }
     /** Run an agent authentication command, or return null when unsupported. */
     runAuthCommand(agent, options = {}) {
@@ -45,4 +47,26 @@ export class AiRunner {
             durationMs: result.durationMs,
         };
     }
+    withIdentityPreamble(agent, promptOptions, options) {
+        if (!hasIdentityOptions(promptOptions))
+            return promptOptions;
+        const workspace = options.cwd ?? this.defaultCwd ?? process.cwd();
+        const preamble = buildIdentityPreamble({
+            agentId: agent,
+            agentType: agent,
+            workspace,
+            purpose: promptOptions.purpose,
+            systemPrompt: promptOptions.systemPrompt,
+            taskId: promptOptions.taskId,
+            peers: promptOptions.peers,
+        });
+        const input = promptOptions.input === undefined ? preamble : `${preamble}\n${promptOptions.input}`;
+        return { ...promptOptions, input };
+    }
+}
+function hasIdentityOptions(options) {
+    return (options.purpose !== undefined ||
+        options.systemPrompt !== undefined ||
+        options.taskId !== undefined ||
+        (options.peers !== undefined && options.peers.length > 0));
 }

package/dist/identity.d.ts

@@ -0,0 +1,21 @@
+import { type SyncProcessExecutor } from '@gobing-ai/ts-runtime';
+export interface IdentityContext {
+    agentId: string;
+    agentType: string;
+    workspace: string;
+    purpose?: string;
+    taskId?: string;
+    taskTitle?: string;
+    systemPrompt?: string;
+    peers?: Array<{
+        id: string;
+        type: string;
+        purpose?: string;
+    }>;
+    gitBranch?: string;
+    gitDirty?: boolean;
+    guardrails?: string[];
+}
+export declare function buildIdentityPreamble(ctx: IdentityContext): string;
+export declare function getGitContext(workspacePath: string, executor?: SyncProcessExecutor): string | null;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEzF,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CA8ClE;AAED,wBAAgB,aAAa,CACzB,aAAa,EAAE,MAAM,EACrB,QAAQ,GAAE,mBAAkD,GAC7D,MAAM,GAAG,IAAI,CAYf"}