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

package/src/identity.ts

@@ -1,5 +1,6 @@
 import { BunSyncProcessExecutor, type SyncProcessExecutor } from '@gobing-ai/ts-runtime';
 
+/** Context used to construct the identity preamble injected into agent prompts. */
 export interface IdentityContext {
     agentId: string;
     agentType: string;
@@ -14,6 +15,7 @@ export interface IdentityContext {
     guardrails?: string[];
 }
 
+/** Build a human-readable identity preamble string that describes the agent, its task, peers, guardrails, and git context. */
 export function buildIdentityPreamble(ctx: IdentityContext): string {
     const sections: string[] = [
         `You are agent \`${ctx.agentId}\` (${ctx.agentType}) in workspace \`${ctx.workspace}\`.`,
@@ -62,6 +64,7 @@ export function buildIdentityPreamble(ctx: IdentityContext): string {
     return `${sections.join('\n\n')}\n`;
 }
 
+/** Query git for the current branch name and dirty file count in `workspacePath`. Returns a pre-formatted "Git context" block, or `null` if git is unavailable or the directory is not a repo. */
 export function getGitContext(
     workspacePath: string,
     executor: SyncProcessExecutor = new BunSyncProcessExecutor(),

package/src/index.ts

@@ -3,8 +3,9 @@ export * from './agent-spec';
 export * from './agents/shims';
 export * from './ai-runner';
 export * from './doctor-runner';
+export * from './events';
 export * from './identity';
-export * from './message-service';
+export * from './messages';
 export * from './slash-command';
 export * from './team-agent-process';
 export * from './team-orchestrator';

package/src/messages.ts

@@ -0,0 +1,6 @@
+import type { InboxMessage } from '@gobing-ai/ts-db/inbox';
+
+/** Renders an inbox message into the line injected into an agent's stdin. */
+export function formatMessage(msg: InboxMessage): string {
+    return `[task from=${msg.fromId ?? 'operator'} id=${msg.id}] ${msg.body}`;
+}

package/src/team-agent-process.ts

@@ -1,25 +1,31 @@
 import { Buffer } from 'node:buffer';
-import { BunPipeProcessSpawner, type PipeProcess, type PipeProcessSpawner } from '@gobing-ai/ts-runtime';
+import { getLogger, type Logger } from '@gobing-ai/ts-infra';
+import { type PipeProcess, ProcessExecutor } from '@gobing-ai/ts-runtime';
 import type { AgentSpec } from './agent-spec';
-import { buildIdentityPreamble } from './identity';
 
+/** Options for spawning a team agent subprocess. */
 export interface AgentProcessOptions {
     spec: AgentSpec;
     command: string[];
     env?: Record<string, string>;
     cwd?: string;
-    processSpawner?: PipeProcessSpawner;
+    processExecutor?: ProcessExecutor;
+    logger?: Logger;
 }
 
 type ProcessStatus = 'running' | 'stopped' | 'errored';
 
+/**
+ * Manages the lifecycle of a single agent subprocess — start, stop, message send, and stdout/stderr subscription.
+ * The identity preamble is built by `TeamOrchestrator` and baked into `command` before the process is constructed.
+ */
 export class TeamAgentProcess {
     readonly agentId: string;
-    readonly identityPreamble: string;
     private readonly command: string[];
     private readonly env: Record<string, string> | undefined;
     private readonly cwd: string | undefined;
-    private readonly processSpawner: PipeProcessSpawner;
+    private readonly processExecutor: ProcessExecutor;
+    private readonly logger: Logger;
     private subprocess: PipeProcess | null = null;
     private status: ProcessStatus = 'stopped';
     private exitCode: number | null = null;
@@ -27,27 +33,21 @@ export class TeamAgentProcess {
 
     constructor(options: AgentProcessOptions) {
         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();
+        this.processExecutor = options.processExecutor ?? new ProcessExecutor();
+        this.logger = options.logger ?? getLogger('team-agent');
     }
 
     async start(): Promise<void> {
         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({
+        this.subprocess = this.processExecutor.runStreaming({
             command,
             args,
+            label: `team-agent.${this.agentId}`,
             ...(this.cwd !== undefined ? { cwd: this.cwd } : {}),
             ...(this.env !== undefined ? { env: this.env } : {}),
         });
@@ -69,11 +69,13 @@ export class TeamAgentProcess {
         }
         try {
             process.endStdin();
-        } catch {
-            // Process may have already closed stdin.
+        } catch (error) {
+            this.warn('stdin close failed', 'stop.endStdin', error);
         }
         process.kill('SIGTERM');
-        const timeout = Bun.sleep(5000).then(() => 'timeout' as const);
+        const timeout = new Promise<'timeout'>((resolve) => {
+            setTimeout(() => resolve('timeout'), 5000);
+        });
         const result = await Promise.race([process.exited, timeout]);
         if (result === 'timeout') {
             process.kill('SIGKILL');
@@ -86,11 +88,15 @@ export class TeamAgentProcess {
     }
 
     async send(message: string): Promise<{ ok: boolean }> {
-        if (this.status !== 'running' || this.subprocess === null) return { ok: false };
+        if (this.status !== 'running' || this.subprocess === null) {
+            this.warn('send skipped because process is not running', 'send.notRunning');
+            return { ok: false };
+        }
         try {
             this.subprocess.writeStdin(`${message}\n`);
             return { ok: true };
-        } catch {
+        } catch (error) {
+            this.warn('stdin write failed', 'send.writeStdin', error);
             this.status = 'errored';
             return { ok: false };
         }
@@ -124,10 +130,19 @@ export class TeamAgentProcess {
                 const buffer = Buffer.from(chunk.value);
                 for (const subscriber of this.subscribers) subscriber(buffer);
             }
-        } catch {
+        } catch (error) {
+            this.warn('stream pipe failed', 'pipe', error);
             if (this.status === 'running') this.status = 'errored';
         } finally {
             reader.releaseLock();
         }
     }
+
+    private warn(message: string, op: string, error?: unknown): void {
+        this.logger.warn(message, {
+            agentId: this.agentId,
+            op,
+            ...(error !== undefined ? { error: error instanceof Error ? error.message : String(error) } : {}),
+        });
+    }
 }

package/src/team-orchestrator.ts

@@ -1,30 +1,38 @@
+import type { InboxMessageDao } from '@gobing-ai/ts-db/inbox';
+import { EventBus } from '@gobing-ai/ts-infra';
 import type { AgentSpec } from './agent-spec';
 import { loadAgentSpecs } from './agent-spec';
 import { type AgentName, getAgentShim, isAgentName } from './agents/shims';
+import type { AgentEvents } from './events';
 import { buildIdentityPreamble } from './identity';
-import { MessageService } from './message-service';
+import { formatMessage } from './messages';
 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 class TeamOrchestrator {
     private specs: AgentSpec[] = [];
     private readonly running = new Map<string, TeamAgentProcess>();
-    private readonly listeners = new Map<TeamEvent, Set<TeamListener>>();
     private readonly processFactory: AgentProcessFactory;
+    private readonly events: EventBus<AgentEvents>;
 
     constructor(
         private readonly configDir: string,
-        private readonly messageService: MessageService,
+        private readonly inbox: InboxMessageDao,
         options: TeamOrchestratorOptions = {},
     ) {
         this.processFactory = options.processFactory ?? ((processOptions) => new TeamAgentProcess(processOptions));
+        this.events = options.events ?? new EventBus<AgentEvents>();
     }
 
     loadSpecs(): AgentSpec[] {
@@ -67,7 +75,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;
     }
 
@@ -76,7 +88,7 @@ export class TeamOrchestrator {
         if (process === undefined) 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: string): Promise<TeamAgentProcess> {
@@ -85,10 +97,10 @@ export class TeamOrchestrator {
     }
 
     async sendMessage(fromId: string | null, toId: string, body: string, inReplyTo?: string): Promise<string> {
-        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;
     }
 
@@ -111,11 +123,9 @@ export class TeamOrchestrator {
         await Promise.all([...this.running.keys()].map((id) => this.stopAgent(id)));
     }
 
-    on(event: TeamEvent, listener: TeamListener): () => void {
-        const listeners = this.listeners.get(event) ?? new Set<TeamListener>();
-        listeners.add(listener);
-        this.listeners.set(event, listeners);
-        return () => listeners.delete(listener);
+    on<K extends keyof AgentEvents>(event: K, listener: AgentEvents[K]): () => void {
+        this.events.on(event, listener);
+        return () => this.events.off(event, listener);
     }
 
     private requireSpec(id: string): AgentSpec {
@@ -129,20 +139,21 @@ export class TeamOrchestrator {
         return type;
     }
 
-    private injectPendingMessages(process: TeamAgentProcess): Promise<void> {
+    private async injectPendingMessages(process: TeamAgentProcess): Promise<boolean> {
         return this.flushInbox(process, 'startup stdin injection failed');
     }
 
-    private async flushInbox(process: TeamAgentProcess, failLabel: string): Promise<void> {
-        const messages = await this.messageService.drain(process.agentId);
+    private async flushInbox(process: TeamAgentProcess, failLabel: string): Promise<boolean> {
+        const messages = await this.inbox.drainPending(process.agentId);
+        let ok = true;
         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);
+            const result = await process.send(formatMessage(message));
+            if (result.ok) await this.inbox.markDelivered(message.id);
+            else {
+                ok = false;
+                await this.inbox.markFailed(message.id, failLabel);
+            }
         }
-    }
-
-    private emit(event: TeamEvent, payload: unknown): void {
-        for (const listener of this.listeners.get(event) ?? []) listener(payload);
+        return ok;
     }
 }

package/dist/message-service.d.ts

@@ -1,13 +0,0 @@
-import type { InboxMessage, InboxMessageDao } from '@gobing-ai/ts-db/inbox';
-export declare class MessageService {
-    private readonly dao;
-    constructor(dao: InboxMessageDao);
-    enqueue(fromId: string | null, toId: string, body: string, inReplyTo?: string): Promise<string>;
-    drain(toId: string): Promise<InboxMessage[]>;
-    deliver(msgId: string): Promise<void>;
-    fail(msgId: string, error: string): Promise<void>;
-    inbox(toId: string, limit?: number, offset?: number): Promise<InboxMessage[]>;
-    countPending(toId: string): Promise<number>;
-    static formatMessage(msg: InboxMessage): string;
-}
-//# sourceMappingURL=message-service.d.ts.map

package/dist/message-service.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"message-service.d.ts","sourceRoot":"","sources":["../src/message-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE5E,qBAAa,cAAc;IACX,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,eAAe;IAEjD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/F,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAI5C,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAI7E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3C,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM;CAGlD"}

package/dist/message-service.js

@@ -1,27 +0,0 @@
-export class MessageService {
-    dao;
-    constructor(dao) {
-        this.dao = dao;
-    }
-    enqueue(fromId, toId, body, inReplyTo) {
-        return this.dao.enqueue(fromId, toId, body, inReplyTo);
-    }
-    drain(toId) {
-        return this.dao.drainPending(toId);
-    }
-    deliver(msgId) {
-        return this.dao.markDelivered(msgId);
-    }
-    fail(msgId, error) {
-        return this.dao.markFailed(msgId, error);
-    }
-    inbox(toId, limit, offset) {
-        return this.dao.inbox(toId, limit, offset);
-    }
-    countPending(toId) {
-        return this.dao.countPending(toId);
-    }
-    static formatMessage(msg) {
-        return `[task from=${msg.fromId ?? 'operator'} id=${msg.id}] ${msg.body}`;
-    }
-}

package/src/message-service.ts

@@ -1,33 +0,0 @@
-import type { InboxMessage, InboxMessageDao } from '@gobing-ai/ts-db/inbox';
-
-export class MessageService {
-    constructor(private readonly dao: InboxMessageDao) {}
-
-    enqueue(fromId: string | null, toId: string, body: string, inReplyTo?: string): Promise<string> {
-        return this.dao.enqueue(fromId, toId, body, inReplyTo);
-    }
-
-    drain(toId: string): Promise<InboxMessage[]> {
-        return this.dao.drainPending(toId);
-    }
-
-    deliver(msgId: string): Promise<void> {
-        return this.dao.markDelivered(msgId);
-    }
-
-    fail(msgId: string, error: string): Promise<void> {
-        return this.dao.markFailed(msgId, error);
-    }
-
-    inbox(toId: string, limit?: number, offset?: number): Promise<InboxMessage[]> {
-        return this.dao.inbox(toId, limit, offset);
-    }
-
-    countPending(toId: string): Promise<number> {
-        return this.dao.countPending(toId);
-    }
-
-    static formatMessage(msg: InboxMessage): string {
-        return `[task from=${msg.fromId ?? 'operator'} id=${msg.id}] ${msg.body}`;
-    }
-}