@gobing-ai/ts-ai-runner 0.2.8 → 0.3.0

package/dist/team-agent-process.d.ts

@@ -0,0 +1,36 @@
+import { Buffer } from 'node:buffer';
+import { type PipeProcessSpawner } from '@gobing-ai/ts-runtime';
+import type { AgentSpec } from './agent-spec';
+export interface AgentProcessOptions {
+    spec: AgentSpec;
+    command: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    processSpawner?: PipeProcessSpawner;
+}
+type ProcessStatus = 'running' | 'stopped' | 'errored';
+export declare class TeamAgentProcess {
+    readonly agentId: string;
+    readonly identityPreamble: string;
+    private readonly command;
+    private readonly env;
+    private readonly cwd;
+    private readonly processSpawner;
+    private subprocess;
+    private status;
+    private exitCode;
+    private readonly subscribers;
+    constructor(options: AgentProcessOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(message: string): Promise<{
+        ok: boolean;
+    }>;
+    subscribe(callback: (data: Buffer) => void): () => void;
+    getStatus(): ProcessStatus;
+    getPid(): number | null;
+    getExitCode(): number | null;
+    private pipe;
+}
+export {};
+//# sourceMappingURL=team-agent-process.d.ts.map

package/dist/team-agent-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"team-agent-process.d.ts","sourceRoot":"","sources":["../src/team-agent-process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAA2C,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACzG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9C,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,kBAAkB,CAAC;CACvC;AAED,KAAK,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEvD,qBAAa,gBAAgB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqC;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;gBAErD,OAAO,EAAE,mBAAmB;IAgBlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBrB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAWrD,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAOvD,SAAS,IAAI,aAAa;IAI1B,MAAM,IAAI,MAAM,GAAG,IAAI;IAIvB,WAAW,IAAI,MAAM,GAAG,IAAI;YAId,IAAI;CAerB"}

package/dist/team-agent-process.js

@@ -0,0 +1,125 @@
+import { Buffer } from 'node:buffer';
+import { BunPipeProcessSpawner } from '@gobing-ai/ts-runtime';
+import { buildIdentityPreamble } from './identity.js';
+export class TeamAgentProcess {
+    agentId;
+    identityPreamble;
+    command;
+    env;
+    cwd;
+    processSpawner;
+    subprocess = null;
+    status = 'stopped';
+    exitCode = null;
+    subscribers = new Set();
+    constructor(options) {
+        this.agentId = options.spec.id;
+        this.identityPreamble = buildIdentityPreamble({
+            agentId: options.spec.id,
+            agentType: options.spec.type,
+            workspace: options.spec.workspace,
+            purpose: options.spec.purpose,
+            systemPrompt: typeof options.spec.config.systemPrompt === 'string' ? options.spec.config.systemPrompt : undefined,
+        });
+        this.command = options.command;
+        this.env = options.env;
+        this.cwd = options.cwd ?? options.spec.workspace;
+        this.processSpawner = options.processSpawner ?? new BunPipeProcessSpawner();
+    }
+    async start() {
+        if (this.status === 'running')
+            return;
+        const [command, ...args] = this.command;
+        if (command === undefined)
+            throw new Error(`${this.agentId}: command must not be empty`);
+        this.subprocess = this.processSpawner.spawn({
+            command,
+            args,
+            ...(this.cwd !== undefined ? { cwd: this.cwd } : {}),
+            ...(this.env !== undefined ? { env: this.env } : {}),
+        });
+        this.status = 'running';
+        this.exitCode = null;
+        if (this.subprocess.stdout !== null)
+            this.pipe(this.subprocess.stdout);
+        if (this.subprocess.stderr !== null)
+            this.pipe(this.subprocess.stderr);
+        void this.subprocess.exited.then((code) => {
+            this.exitCode = code;
+            if (this.status === 'running')
+                this.status = code === 0 ? 'stopped' : 'errored';
+        });
+    }
+    async stop() {
+        const process = this.subprocess;
+        if (process === null) {
+            this.status = 'stopped';
+            return;
+        }
+        try {
+            process.endStdin();
+        }
+        catch {
+            // Process may have already closed stdin.
+        }
+        process.kill('SIGTERM');
+        const timeout = Bun.sleep(5000).then(() => 'timeout');
+        const result = await Promise.race([process.exited, timeout]);
+        if (result === 'timeout') {
+            process.kill('SIGKILL');
+            this.exitCode = await process.exited;
+        }
+        else {
+            this.exitCode = result;
+        }
+        this.status = 'stopped';
+        this.subprocess = null;
+    }
+    async send(message) {
+        if (this.status !== 'running' || this.subprocess === null)
+            return { ok: false };
+        try {
+            this.subprocess.writeStdin(`${message}\n`);
+            return { ok: true };
+        }
+        catch {
+            this.status = 'errored';
+            return { ok: false };
+        }
+    }
+    subscribe(callback) {
+        this.subscribers.add(callback);
+        return () => {
+            this.subscribers.delete(callback);
+        };
+    }
+    getStatus() {
+        return this.status;
+    }
+    getPid() {
+        return this.subprocess?.pid ?? null;
+    }
+    getExitCode() {
+        return this.exitCode;
+    }
+    async pipe(stream) {
+        const reader = stream.getReader();
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                const buffer = Buffer.from(chunk.value);
+                for (const subscriber of this.subscribers)
+                    subscriber(buffer);
+            }
+        }
+        catch {
+            if (this.status === 'running')
+                this.status = 'errored';
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+}

package/dist/team-orchestrator.d.ts

@@ -0,0 +1,36 @@
+import type { AgentSpec } from './agent-spec';
+import { MessageService } from './message-service';
+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;
+export interface TeamOrchestratorOptions {
+    processFactory?: AgentProcessFactory;
+}
+export declare class TeamOrchestrator {
+    private readonly configDir;
+    private readonly messageService;
+    private specs;
+    private readonly running;
+    private readonly listeners;
+    private readonly processFactory;
+    constructor(configDir: string, messageService: MessageService, options?: TeamOrchestratorOptions);
+    loadSpecs(): AgentSpec[];
+    getSpec(id: string): AgentSpec | undefined;
+    startAgent(id: string): Promise<TeamAgentProcess>;
+    stopAgent(id: string): Promise<void>;
+    restartAgent(id: string): Promise<TeamAgentProcess>;
+    sendMessage(fromId: string | null, toId: string, body: string, inReplyTo?: string): Promise<string>;
+    getRunningAgents(): Map<string, TeamAgentProcess>;
+    getAgentStatus(id: string): 'running' | 'stopped' | 'errored' | 'unknown';
+    getPeerSpecs(workspace: string, excludeId?: string): AgentSpec[];
+    stopAll(): Promise<void>;
+    on(event: TeamEvent, listener: TeamListener): () => 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

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

package/dist/team-orchestrator.js

@@ -0,0 +1,131 @@
+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 { TeamAgentProcess } from './team-agent-process.js';
+export class TeamOrchestrator {
+    configDir;
+    messageService;
+    specs = [];
+    running = new Map();
+    listeners = new Map();
+    processFactory;
+    constructor(configDir, messageService, options = {}) {
+        this.configDir = configDir;
+        this.messageService = messageService;
+        this.processFactory = options.processFactory ?? ((processOptions) => new TeamAgentProcess(processOptions));
+    }
+    loadSpecs() {
+        this.specs = loadAgentSpecs(this.configDir);
+        return [...this.specs];
+    }
+    getSpec(id) {
+        if (this.specs.length === 0)
+            this.loadSpecs();
+        return this.specs.find((spec) => spec.id === id);
+    }
+    async startAgent(id) {
+        const spec = this.requireSpec(id);
+        const agentType = this.requireAgentName(spec.type);
+        const peers = this.getPeerSpecs(spec.workspace, spec.id).map((peer) => ({
+            id: peer.id,
+            type: peer.type,
+            purpose: peer.purpose,
+        }));
+        const identityPreamble = buildIdentityPreamble({
+            agentId: spec.id,
+            agentType: spec.type,
+            workspace: spec.workspace,
+            purpose: spec.purpose,
+            systemPrompt: typeof spec.config.systemPrompt === 'string' ? spec.config.systemPrompt : undefined,
+            peers,
+        });
+        const command = getAgentShim(agentType).getPromptCommand({
+            input: identityPreamble,
+            purpose: spec.purpose,
+            systemPrompt: typeof spec.config.systemPrompt === 'string' ? spec.config.systemPrompt : undefined,
+            peers,
+        });
+        const process = this.processFactory({
+            spec,
+            command: [command.command, ...command.args],
+            cwd: spec.workspace,
+        });
+        await process.start();
+        this.running.set(id, process);
+        await this.injectPendingMessages(process);
+        this.emit('agent.started', { id });
+        return process;
+    }
+    async stopAgent(id) {
+        const process = this.running.get(id);
+        if (process === undefined)
+            return;
+        await process.stop();
+        this.running.delete(id);
+        this.emit('agent.stopped', { id });
+    }
+    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 process = this.running.get(toId);
+        if (process !== undefined)
+            await this.flushInbox(process, 'live stdin injection failed');
+        this.emit('message.sent', { id: msgId, fromId, toId });
+        return msgId;
+    }
+    getRunningAgents() {
+        return new Map(this.running);
+    }
+    getAgentStatus(id) {
+        const process = this.running.get(id);
+        if (process === undefined)
+            return this.getSpec(id) === undefined ? 'unknown' : 'stopped';
+        return process.getStatus();
+    }
+    getPeerSpecs(workspace, excludeId) {
+        if (this.specs.length === 0)
+            this.loadSpecs();
+        return this.specs.filter((spec) => spec.workspace === workspace && spec.id !== excludeId);
+    }
+    async stopAll() {
+        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);
+    }
+    requireSpec(id) {
+        const spec = this.getSpec(id);
+        if (spec === undefined)
+            throw new Error(`Agent spec not found: ${id}`);
+        return spec;
+    }
+    requireAgentName(type) {
+        if (!isAgentName(type))
+            throw new Error(`Unsupported agent type: ${type}`);
+        return type;
+    }
+    injectPendingMessages(process) {
+        return this.flushInbox(process, 'startup stdin injection failed');
+    }
+    async flushInbox(process, failLabel) {
+        const messages = await this.messageService.drain(process.agentId);
+        for (const message of messages) {
+            const result = await process.send(MessageService.formatMessage(message));
+            if (result.ok)
+                await this.messageService.deliver(message.id);
+            else
+                await this.messageService.fail(message.id, failLabel);
+        }
+    }
+    emit(event, payload) {
+        for (const listener of this.listeners.get(event) ?? [])
+            listener(payload);
+    }
+}

package/package.json

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

package/src/agent-detector.ts

@@ -43,19 +43,11 @@ export class AgentDetector {
 
     /** Probe one agent by name. */
     async detectOne(agent: string): Promise<DetectedAgent> {
-        if (!isAgentName(agent)) {
-            return { name: agent, installed: false, version: null, channels: [], error: `Unknown agent: ${agent}` };
-        }
+        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));
         }
     }
 
@@ -64,41 +56,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,
@@ -109,3 +77,8 @@ export class AgentDetector {
         };
     }
 }
+
+/** Build an "unavailable" detection result for an agent with the given error. */
+function unavailable(name: AgentName | string, error: string): DetectedAgent {
+    return { name, installed: false, version: null, channels: [], error };
+}

package/src/agent-spec.ts

@@ -0,0 +1,128 @@
+import { basename, join } from 'node:path';
+import { NodeSyncFileSystem, parseYamlObject, type SyncFileSystem, stringifyYamlObject } 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 class ValueError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'ValueError';
+    }
+}
+
+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 "-"`);
+    }
+    return id;
+}
+
+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 seen = new Set<string>();
+    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: AgentSpec,
+    configDir: string,
+    fs: SyncFileSystem = new NodeSyncFileSystem(),
+): Promise<void> {
+    validateAgentId(spec.id);
+    fs.mkdir(configDir);
+    fs.writeFile(join(configDir, `${spec.id}.yaml`), serializeAgentSpec(spec));
+}
+
+export async function deleteAgentSpec(
+    id: string,
+    configDir: string,
+    fs: SyncFileSystem = new NodeSyncFileSystem(),
+): Promise<void> {
+    validateAgentId(id);
+    fs.unlink(join(configDir, `${id}.yaml`));
+}
+
+function safeReadDir(configDir: string, fs: SyncFileSystem = new NodeSyncFileSystem()): string[] {
+    try {
+        return fs.readDir(configDir);
+    } catch (error) {
+        if (error instanceof Error && 'code' in error && (error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+
+function parseAgentSpec(source: string, fileName: string): AgentSpec {
+    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: AgentSpec): string {
+    const record: Record<string, unknown> = {
+        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: 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`);
+    }
+    return value;
+}
+
+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`);
+    }
+    return value;
+}
+
+function requireRecord(
+    source: Record<string, unknown>,
+    key: keyof AgentSpec,
+    fileName: string,
+): 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`);
+    }
+    return value as Record<string, unknown>;
+}

package/src/agents/shims.ts

@@ -22,6 +22,16 @@ 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. */

package/src/ai-runner.ts

@@ -1,5 +1,6 @@
 import { NodeProcessExecutor, type ProcessExecutor, type ProcessResult } from '@gobing-ai/ts-runtime';
 import { type AgentName, getAgentShim, type PromptOptions } from './agents/shims';
+import { buildIdentityPreamble } from './identity';
 
 /** Result returned by every AI runner dispatch method. */
 export interface AgentRunResult {
@@ -61,7 +62,14 @@ export class AiRunner {
         promptOptions: PromptOptions,
         options: AgentRunOptions = {},
     ): Promise<AgentRunResult> {
-        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. */
@@ -94,4 +102,33 @@ export class AiRunner {
             durationMs: result.durationMs,
         };
     }
+
+    private withIdentityPreamble(
+        agent: AgentName,
+        promptOptions: PromptOptions,
+        options: AgentRunOptions,
+    ): PromptOptions {
+        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: PromptOptions): boolean {
+    return (
+        options.purpose !== undefined ||
+        options.systemPrompt !== undefined ||
+        options.taskId !== undefined ||
+        (options.peers !== undefined && options.peers.length > 0)
+    );
 }