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

package/src/identity.ts

@@ -0,0 +1,86 @@
+import { BunSyncProcessExecutor, 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 function buildIdentityPreamble(ctx: IdentityContext): string {
+    const sections: string[] = [
+        `You are agent \`${ctx.agentId}\` (${ctx.agentType}) in workspace \`${ctx.workspace}\`.`,
+    ];
+
+    if (ctx.taskId !== undefined) {
+        const title = ctx.taskTitle === undefined ? '' : ` — ${ctx.taskTitle}`;
+        sections.push(`Your current task: #${ctx.taskId}${title}.`);
+    }
+
+    if (ctx.purpose !== undefined && ctx.purpose.trim() !== '') sections.push(`Your purpose: ${ctx.purpose}.`);
+    if (ctx.systemPrompt !== undefined && ctx.systemPrompt.trim() !== '') sections.push(ctx.systemPrompt);
+
+    if ((ctx.peers?.length ?? 0) > 0) {
+        sections.push(
+            [
+                'Peer agents in this workspace:',
+                ...(ctx.peers ?? []).map(
+                    (peer) => `- \`${peer.id}\` (${peer.type}) — ${peer.purpose ?? '(no purpose set)'}`,
+                ),
+            ].join('\n'),
+        );
+    }
+
+    sections.push(
+        [
+            'Communication:',
+            '- Send a message with: spur message send --to <agent-id> "<message>"',
+            '- Reply to a message with: spur message reply <msg-id> "<response>"',
+            '- Read pending messages with: spur message inbox',
+        ].join('\n'),
+    );
+
+    if (ctx.gitBranch !== undefined) {
+        sections.push(
+            ['Git context:', `branch: ${ctx.gitBranch}`, `dirty: ${ctx.gitDirty === true ? 'true' : 'false'}`].join(
+                '\n',
+            ),
+        );
+    }
+
+    if ((ctx.guardrails?.length ?? 0) > 0) {
+        sections.push(['Guardrails:', ...(ctx.guardrails ?? []).map((guardrail) => `- ${guardrail}`)].join('\n'));
+    }
+
+    return `${sections.join('\n\n')}\n`;
+}
+
+export function getGitContext(
+    workspacePath: string,
+    executor: SyncProcessExecutor = new BunSyncProcessExecutor(),
+): string | null {
+    const git = Bun.which('git');
+    if (git === null) return null;
+
+    const branch = runGit(executor, git, ['-C', workspacePath, 'branch', '--show-current']);
+    if (branch === null || branch === '') return null;
+
+    const status = runGit(executor, git, ['-C', workspacePath, 'status', '--porcelain']);
+    const dirtyCount = status === null || status === '' ? 0 : status.split('\n').filter(Boolean).length;
+    return ['Git context:', `branch: ${branch}`, `dirty: ${dirtyCount === 0 ? 'false' : `${dirtyCount} files`}`].join(
+        '\n',
+    );
+}
+
+function runGit(executor: SyncProcessExecutor, command: string, args: string[]): string | null {
+    const result = executor.runSync({ command, args, rejectOnError: false, forceBuffered: true });
+    if (result.exitCode !== 0) return null;
+    return result.stdout.trim();
+}

package/src/index.ts

@@ -1,5 +1,10 @@
 export * from './agent-detector';
+export * from './agent-spec';
 export * from './agents/shims';
 export * from './ai-runner';
 export * from './doctor-runner';
+export * from './identity';
+export * from './message-service';
 export * from './slash-command';
+export * from './team-agent-process';
+export * from './team-orchestrator';

package/src/message-service.ts

@@ -0,0 +1,33 @@
+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}`;
+    }
+}

package/src/team-agent-process.ts

@@ -0,0 +1,133 @@
+import { Buffer } from 'node:buffer';
+import { BunPipeProcessSpawner, type PipeProcess, type PipeProcessSpawner } from '@gobing-ai/ts-runtime';
+import type { AgentSpec } from './agent-spec';
+import { buildIdentityPreamble } from './identity';
+
+export interface AgentProcessOptions {
+    spec: AgentSpec;
+    command: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    processSpawner?: PipeProcessSpawner;
+}
+
+type ProcessStatus = 'running' | 'stopped' | 'errored';
+
+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 subprocess: PipeProcess | null = null;
+    private status: ProcessStatus = 'stopped';
+    private exitCode: number | null = null;
+    private readonly subscribers = new Set<(data: Buffer) => void>();
+
+    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();
+    }
+
+    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({
+            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(): Promise<void> {
+        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' as const);
+        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: string): Promise<{ ok: boolean }> {
+        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: (data: Buffer) => void): () => void {
+        this.subscribers.add(callback);
+        return () => {
+            this.subscribers.delete(callback);
+        };
+    }
+
+    getStatus(): ProcessStatus {
+        return this.status;
+    }
+
+    getPid(): number | null {
+        return this.subprocess?.pid ?? null;
+    }
+
+    getExitCode(): number | null {
+        return this.exitCode;
+    }
+
+    private async pipe(stream: ReadableStream<Uint8Array>): Promise<void> {
+        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/src/team-orchestrator.ts

@@ -0,0 +1,148 @@
+import type { AgentSpec } from './agent-spec';
+import { loadAgentSpecs } from './agent-spec';
+import { type AgentName, getAgentShim, isAgentName } from './agents/shims';
+import { buildIdentityPreamble } from './identity';
+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 class TeamOrchestrator {
+    private specs: AgentSpec[] = [];
+    private readonly running = new Map<string, TeamAgentProcess>();
+    private readonly listeners = new Map<TeamEvent, Set<TeamListener>>();
+    private readonly processFactory: AgentProcessFactory;
+
+    constructor(
+        private readonly configDir: string,
+        private readonly messageService: MessageService,
+        options: TeamOrchestratorOptions = {},
+    ) {
+        this.processFactory = options.processFactory ?? ((processOptions) => new TeamAgentProcess(processOptions));
+    }
+
+    loadSpecs(): AgentSpec[] {
+        this.specs = loadAgentSpecs(this.configDir);
+        return [...this.specs];
+    }
+
+    getSpec(id: string): AgentSpec | undefined {
+        if (this.specs.length === 0) this.loadSpecs();
+        return this.specs.find((spec) => spec.id === id);
+    }
+
+    async startAgent(id: string): Promise<TeamAgentProcess> {
+        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: string): Promise<void> {
+        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: string): Promise<TeamAgentProcess> {
+        await this.stopAgent(id);
+        return this.startAgent(id);
+    }
+
+    async sendMessage(fromId: string | null, toId: string, body: string, inReplyTo?: string): Promise<string> {
+        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(): Map<string, TeamAgentProcess> {
+        return new Map(this.running);
+    }
+
+    getAgentStatus(id: string): 'running' | 'stopped' | 'errored' | 'unknown' {
+        const process = this.running.get(id);
+        if (process === undefined) return this.getSpec(id) === undefined ? 'unknown' : 'stopped';
+        return process.getStatus();
+    }
+
+    getPeerSpecs(workspace: string, excludeId?: string): AgentSpec[] {
+        if (this.specs.length === 0) this.loadSpecs();
+        return this.specs.filter((spec) => spec.workspace === workspace && spec.id !== excludeId);
+    }
+
+    async stopAll(): Promise<void> {
+        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);
+    }
+
+    private requireSpec(id: string): AgentSpec {
+        const spec = this.getSpec(id);
+        if (spec === undefined) throw new Error(`Agent spec not found: ${id}`);
+        return spec;
+    }
+
+    private requireAgentName(type: string): AgentName {
+        if (!isAgentName(type)) throw new Error(`Unsupported agent type: ${type}`);
+        return type;
+    }
+
+    private injectPendingMessages(process: TeamAgentProcess): Promise<void> {
+        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);
+        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);
+        }
+    }
+
+    private emit(event: TeamEvent, payload: unknown): void {
+        for (const listener of this.listeners.get(event) ?? []) listener(payload);
+    }
+}