@ai-devkit/agent-manager 0.29.0 → 0.31.0

package/src/__tests__/providers/pi/durable/PiPrintRunner.test.ts

@@ -0,0 +1,107 @@
+import { EventEmitter } from 'node:events';
+import { PassThrough, Writable } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import type { PiDurableAgent } from '../../../../index.js';
+
+const SESSION = '22222222-2222-4222-8222-222222222222';
+function agent(sessionHealth: PiDurableAgent['sessionHealth'] = 'uninitialized'): PiDurableAgent {
+    return { id: '11111111-1111-4111-8111-111111111111', name: 'reviewer', provider: 'pi', mode: 'durable',
+        cwd: '/project', providerSessionId: SESSION, state: 'running', sessionHealth, createdAt: '',
+        updatedAt: '', lastActiveAt: null, lastResult: null, activeRun: null };
+}
+function fakeSpawn(lines: string[], exitCode = 0) {
+    const promptChunks: Buffer[] = [];
+    const child = new EventEmitter() as any;
+    child.pid = 4242; child.stdout = new PassThrough(); child.stderr = new PassThrough(); child.kill = vi.fn();
+    child.stdin = new Writable({
+        write(chunk, _encoding, callback) { promptChunks.push(Buffer.from(chunk)); callback(); },
+        final(callback) { child.stdout.end(lines.join('\n')); queueMicrotask(() => child.emit('close', exitCode, null)); callback(); },
+    });
+    return { child, spawn: vi.fn(() => child), promptChunks };
+}
+function events(session = SESSION): string[] { return [
+    JSON.stringify({ type: 'session', version: 3, id: session, cwd: '/project' }),
+    JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'first' }] } }),
+    JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'thinking', thinking: 'hidden' }, { type: 'text', text: 'final' }] } }),
+    JSON.stringify({ type: 'agent_end', messages: [] }), '',
+]; }
+async function runner(fixture: ReturnType<typeof fakeSpawn>, maxLineBytes?: number) {
+    const api = await import('../../../../index.js') as Record<string, unknown>;
+    expect(api).toHaveProperty('PiPrintRunner');
+    const Runner = api.PiPrintRunner as new (options: unknown) => any;
+    return new Runner({ spawn: fixture.spawn, maxLineBytes, processInspector: { getIdentity: () => ({ pid: 4242, startedAt: 'start' }) } });
+}
+
+describe('PiPrintRunner', () => {
+    it('binds a first session and returns the last completed assistant text', async () => {
+        const fixture = fakeSpawn(events()); const instance = await runner(fixture); const order: string[] = [];
+        const result = await instance.run({ agent: agent(), prompt: 'secret', executable: 'fake-pi',
+            onSpawn: async () => { expect(fixture.promptChunks).toHaveLength(0); order.push('spawn'); } });
+        expect(order).toEqual(['spawn']);
+        expect(fixture.spawn).toHaveBeenCalledWith('fake-pi', ['--mode', 'json', '--session-id', SESSION], expect.objectContaining({ cwd: '/project', shell: false }));
+        expect(Buffer.concat(fixture.promptChunks).toString()).toBe('secret');
+        expect(result).toEqual({ sessionId: SESSION, result: 'final', messages: ['first', 'final'], exitCode: 0 });
+    });
+
+    it('resumes the exact stored session and rejects mismatch', async () => {
+        const fixture = fakeSpawn(events('33333333-3333-4333-8333-333333333333'));
+        await expect((await runner(fixture)).run({ agent: agent('healthy'), prompt: 'later', onSpawn: vi.fn() }))
+            .rejects.toMatchObject({ code: 'PI_SESSION_MISMATCH' });
+        expect(fixture.spawn.mock.calls[0]![1]).toEqual(['--mode', 'json', '--session', SESSION]);
+    });
+
+    it.each([
+        ['malformed', ['{bad\n'], 'PI_PROTOCOL'], ['non-object', ['[]\n'], 'PI_PROTOCOL'],
+        ['truncated', ['{}'], 'PI_PROTOCOL'], ['missing session', [JSON.stringify({ type: 'agent_end' }), ''], 'PI_PROTOCOL'],
+        ['missing result', [JSON.stringify({ type: 'session', id: SESSION }), JSON.stringify({ type: 'agent_end' }), ''], 'PI_RESULT_MISSING'],
+        ['missing end', [JSON.stringify({ type: 'session', id: SESSION }), JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'x' }] } }), ''], 'PI_PROTOCOL'],
+    ])('rejects %s output', async (_name, lines, code) => {
+        await expect((await runner(fakeSpawn(lines as string[]))).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn() }))
+            .rejects.toMatchObject({ code });
+    });
+
+    it('rejects oversized output, failed processes, and unverifiable identities', async () => {
+        await expect((await runner(fakeSpawn(['x'.repeat(20)]), 10)).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn() }))
+            .rejects.toMatchObject({ code: 'PI_PROTOCOL' });
+        await expect((await runner(fakeSpawn(events(), 1))).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn() }))
+            .rejects.toMatchObject({ code: 'PI_PROCESS' });
+        const fixture = fakeSpawn([]); const api = await import('../../../../index.js') as Record<string, unknown>;
+        const Runner = api.PiPrintRunner as new (options: unknown) => any;
+        await expect(new Runner({ spawn: fixture.spawn, processInspector: { getIdentity: () => null } }).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn() }))
+            .rejects.toMatchObject({ code: 'PI_PROCESS' });
+        expect(fixture.child.kill).toHaveBeenCalledOnce();
+    });
+
+    it('rejects invalid and duplicate session identities', async () => {
+        for (const lines of [
+            [JSON.stringify({ type: 'session', id: 'bad' }), ''],
+            [JSON.stringify({ type: 'session', id: SESSION }), JSON.stringify({ type: 'session', id: SESSION }), ''],
+        ]) await expect((await runner(fakeSpawn(lines))).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn() }))
+            .rejects.toMatchObject({ code: 'PI_PROTOCOL' });
+    });
+
+    it('kills on spawn persistence failure', async () => {
+        const spawnFailure = fakeSpawn([]); const failure = new Error('cannot persist');
+        await expect((await runner(spawnFailure)).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn().mockRejectedValue(failure), onSession: vi.fn() })).rejects.toBe(failure);
+        expect(spawnFailure.child.kill).toHaveBeenCalledOnce();
+    });
+
+    it('classifies spawn errors and a missing PID as process failures', async () => {
+        const errored = fakeSpawn([]);
+        errored.child.stdin = new Writable({ write(_chunk, _encoding, callback) { callback(); }, final(callback) { queueMicrotask(() => errored.child.emit('error', new Error('spawn'))); callback(); } });
+        await expect((await runner(errored)).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn() })).rejects.toMatchObject({ code: 'PI_PROCESS' });
+        const missing = fakeSpawn([]); missing.child.pid = undefined;
+        await expect((await runner(missing)).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn() })).rejects.toMatchObject({ code: 'PI_PROCESS' });
+        expect(missing.child.kill).toHaveBeenCalledOnce();
+    });
+
+    it('accepts string assistant content and ignores empty or unrelated messages', async () => {
+        const lines = [JSON.stringify({ type: 'session', id: SESSION }), JSON.stringify({ type: 'future' }),
+            JSON.stringify({ type: 'message_end', message: { role: 'user', content: 'ignored' } }),
+            JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: ' ' } }),
+            JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: 'answer' } }),
+            JSON.stringify({ type: 'agent_end' }), ''];
+        await expect((await runner(fakeSpawn(lines))).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn() }))
+            .resolves.toMatchObject({ result: 'answer' });
+    });
+});

package/src/__tests__/providers/pi/durable/PiStreamParser.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { PiStreamParser } from '../../../../providers/pi/durable/PiStreamParser.js';
+
+const SESSION = '22222222-2222-4222-8222-222222222222';
+
+describe('PiStreamParser', () => {
+    it('ignores blank lines and normalizes unexpected parser failures', () => {
+        const parser = new PiStreamParser(SESSION, 1024);
+        parser.accept('\n');
+        parser.fail(new Error('unexpected'));
+
+        expect(parser.hasFailed()).toBe(true);
+        expect(() => parser.result({ code: 0, signal: null }))
+            .toThrowError(expect.objectContaining({ code: 'PI_PROTOCOL', message: 'Pi stream processing failed.' }));
+    });
+
+    it('includes the terminating signal in process failures', () => {
+        const parser = new PiStreamParser(SESSION, 1024);
+        parser.accept(`${JSON.stringify({ type: 'session', id: SESSION })}\n`);
+
+        expect(() => parser.result({ code: null, signal: 'SIGTERM' }))
+            .toThrowError(expect.objectContaining({ code: 'PI_PROCESS', message: 'Pi print run failed (SIGTERM)' }));
+    });
+});

package/src/__tests__/utils/ClaudeSessionParser.test.ts

@@ -1,5 +1,5 @@
 /**
- * Tests for utils/ClaudeSessionParser.ts — focused on stripping
+ * Tests for providers/claude/ClaudeSessionParser.ts — focused on stripping
  * harness-injected XML tags from conversation content.
  */
 
@@ -7,7 +7,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { ClaudeSessionParser } from '../../utils/ClaudeSessionParser.js';
+import { ClaudeSessionParser } from '../../providers/claude/ClaudeSessionParser.js';
 
 interface JsonlEntry {
     type: 'user' | 'assistant' | 'system';

package/src/adapters/index.ts

@@ -1,4 +1,4 @@
-export { ClaudeCodeAdapter } from './ClaudeCodeAdapter.js';
+export { ClaudeCodeAdapter } from '../providers/claude/ClaudeCodeAdapter.js';
 export { CodexAdapter } from './CodexAdapter.js';
 export { CopilotAdapter } from './CopilotAdapter.js';
 export { GeminiCliAdapter } from './GeminiCliAdapter.js';

package/src/database/connection.ts

@@ -32,6 +32,7 @@ export class DatabaseConnection {
 
         this.db = new Database(this.dbPath, {
             readonly: this.readonly,
+            timeout: 5000,
             verbose: typeof options.verbose === 'function'
                 ? options.verbose
                 : options.verbose ? console.log : undefined,
@@ -50,7 +51,8 @@ export class DatabaseConnection {
     }
 
     private configure(): void {
-        this.db.pragma('journal_mode = WAL');
+        const journalMode = this.db.pragma('journal_mode', { simple: true }) as string;
+        if (journalMode.toLowerCase() !== 'wal') this.db.pragma('journal_mode = WAL');
         this.db.pragma('foreign_keys = ON');
         this.db.pragma('synchronous = NORMAL');
         this.db.pragma('busy_timeout = 5000');

package/src/database/migrations/004_codex_durable_sessions.sql

@@ -0,0 +1 @@
+ALTER TABLE durable_agents ALTER COLUMN provider_session_id DROP NOT NULL;

package/src/durable/DurableAgent.ts

@@ -1,6 +1,14 @@
 export type DurableAgentState = 'ready' | 'running' | 'degraded';
 export type DurableSessionHealth = 'uninitialized' | 'healthy' | 'unknown' | 'mismatch';
 export type DurableRunStatus = 'succeeded' | 'failed' | 'interrupted';
+export type PiPrintErrorCode =
+    | 'PI_CLI_UNAVAILABLE'
+    | 'PI_CLI_UNSUPPORTED'
+    | 'PI_PROCESS'
+    | 'PI_PROTOCOL'
+    | 'PI_RESULT_MISSING'
+    | 'PI_SESSION_MISMATCH'
+    | 'PI_UNSUPPORTED';
 
 export const AGENT_MODES = {
     INTERACTIVE: 'interactive',
@@ -26,13 +34,13 @@ export interface DurableLastResult {
     summary: string;
 }
 
-export interface DurableAgent {
+export type DurableProvider = 'claude' | 'codex' | 'pi';
+
+export interface DurableAgentBase {
     id: string;
     name: string;
-    provider: 'claude';
     mode: typeof AGENT_MODES.DURABLE;
     cwd: string;
-    providerSessionId: string;
     state: DurableAgentState;
     sessionHealth: DurableSessionHealth;
     createdAt: string;
@@ -42,6 +50,23 @@ export interface DurableAgent {
     activeRun: DurableActiveRun | null;
 }
 
+export interface ClaudeDurableAgent extends DurableAgentBase {
+    provider: 'claude';
+    providerSessionId: string;
+}
+
+export interface CodexDurableAgent extends DurableAgentBase {
+    provider: 'codex';
+    providerSessionId: string | null;
+}
+
+export interface PiDurableAgent extends DurableAgentBase {
+    provider: 'pi';
+    providerSessionId: string;
+}
+
+export type DurableAgent = ClaudeDurableAgent | CodexDurableAgent | PiDurableAgent;
+
 export class DurableAgentError extends Error {
     constructor(
         message: string,
@@ -89,3 +114,26 @@ export class ClaudePrintError extends DurableAgentError {
         this.name = 'ClaudePrintError';
     }
 }
+
+export type CodexPrintErrorCode =
+    | 'CODEX_PROTOCOL'
+    | 'CODEX_PROCESS'
+    | 'CODEX_SESSION_MISMATCH'
+    | 'CODEX_UNSUPPORTED'
+    | 'CODEX_RESULT_MISSING'
+    | 'CODEX_CLI_UNSUPPORTED'
+    | 'CODEX_CLI_UNAVAILABLE';
+
+export class CodexPrintError extends DurableAgentError {
+    constructor(message: string, code: CodexPrintErrorCode) {
+        super(message, code);
+        this.name = 'CodexPrintError';
+    }
+}
+
+export class PiPrintError extends DurableAgentError {
+    constructor(message: string, code: PiPrintErrorCode = 'PI_PROCESS') {
+        super(message, code);
+        this.name = 'PiPrintError';
+    }
+}

package/src/durable/DurableAgentRepository.ts

@@ -1,8 +1,9 @@
 import fs from 'fs';
 import { randomUUID } from 'crypto';
-import { execFileSync } from 'child_process';
 import { DatabaseConnection, DEFAULT_AGENT_REGISTRY_DB_PATH } from '../database/index.js';
-import { AGENT_MODES, type DurableActiveRun, type DurableAgent, type ProcessIdentity, type DurableRunStatus, type DurableSessionHealth } from './DurableAgent.js';
+import { AGENT_MODES, CodexPrintError, type DurableActiveRun, type DurableAgent, type DurableProvider, type ProcessIdentity, type DurableRunStatus, type DurableSessionHealth } from './DurableAgent.js';
+import { LocalProcessInspector, type ProcessInspector } from './process.js';
+import { isUuid } from './utils.js';
 import {
     DurableAgentBusyError,
     DurableAgentNameConflictError,
@@ -11,7 +12,7 @@ import {
 } from './DurableAgent.js';
 
 interface DurableAgentRow {
-    id: string; name: string; provider: 'claude'; mode: typeof AGENT_MODES.DURABLE; cwd: string; provider_session_id: string;
+    id: string; name: string; provider: DurableProvider; mode: typeof AGENT_MODES.DURABLE; cwd: string; provider_session_id: string | null;
     state: DurableAgent['state']; session_health: DurableSessionHealth; created_at: string; updated_at: string;
     last_active_at: string | null; last_result_status: DurableRunStatus | null;
     last_result_completed_at: string | null; last_result_exit_code: number | null; last_result_summary: string | null;
@@ -19,7 +20,7 @@ interface DurableAgentRow {
     active_provider_pid: number | null; active_provider_started_at: string | null; active_run_started_at: string | null;
 }
 
-export interface CreateDurableAgentInput { name: string; cwd: string }
+export interface CreateDurableAgentInput { name: string; cwd: string; provider?: DurableProvider }
 
 export interface DurableAgentRepositoryOptions {
     dbPath?: string;
@@ -34,7 +35,8 @@ export interface DurableAgentRepositoryOptions {
     mutationLockStaleMs?: number;
 }
 
-export interface ProcessInspector { getIdentity(pid: number): ProcessIdentity | null }
+export { LocalProcessInspector } from './process.js';
+export type { ProcessInspector } from './process.js';
 export interface DurableRunCompletion {
     status: DurableRunStatus; exitCode: number | null; summary: string; sessionHealth: DurableSessionHealth;
 }
@@ -64,13 +66,14 @@ export class DurableAgentRepository {
         const cwd = this.canonicalDirectory(input.cwd);
         const timestamp = this.now().toISOString();
         const id = randomUUID();
-        let providerSessionId = randomUUID();
+        const provider = input.provider ?? 'claude';
+        let providerSessionId = provider === 'codex' ? null : randomUUID();
         while (providerSessionId === id) providerSessionId = randomUUID();
         try {
             this.db.execute(`INSERT INTO durable_agents (
                 id, name, provider, mode, cwd, provider_session_id, state, session_health, created_at, updated_at
-            ) VALUES (?, ?, 'claude', ?, ?, ?, 'ready', 'uninitialized', ?, ?)`,
-            [id, input.name, AGENT_MODES.DURABLE, cwd, providerSessionId, timestamp, timestamp]);
+            ) VALUES (?, ?, ?, ?, ?, ?, 'ready', 'uninitialized', ?, ?)`,
+            [id, input.name, provider, AGENT_MODES.DURABLE, cwd, providerSessionId, timestamp, timestamp]);
         } catch (error) {
             if (/UNIQUE constraint failed: durable_agents\.name/i.test((error as Error).message)) {
                 throw new DurableAgentNameConflictError(input.name);
@@ -157,6 +160,42 @@ export class DurableAgentRepository {
         if (changed.changes !== 1) throw new DurableAgentRepositoryError('Print run ownership changed.');
     }
 
+    async bindProviderSession(id: string, token: string, providerSessionId: string): Promise<DurableAgent> {
+        this.assertWritable();
+        if (!isUuid(providerSessionId)) {
+            throw new DurableAgentRepositoryError('Invalid provider session id.');
+        }
+        try {
+            this.immediate(() => {
+                const agent = this.findById(id);
+                if (!agent) throw new DurableAgentNotFoundError(id);
+                if (agent.provider !== 'codex') {
+                    throw new DurableAgentRepositoryError('Only Codex durable sessions can be bound after creation.');
+                }
+                if (agent.activeRun?.token !== token) {
+                    throw new DurableAgentRepositoryError('Print run ownership changed.');
+                }
+                if (agent.providerSessionId !== null && agent.providerSessionId !== providerSessionId) {
+                    throw new CodexPrintError('Durable agent provider session identity does not match.', 'CODEX_SESSION_MISMATCH');
+                }
+                if (agent.providerSessionId === providerSessionId) return;
+                const changed = this.db.execute(`UPDATE durable_agents SET provider_session_id = ?, updated_at = ?
+                    WHERE id = ? AND provider = 'codex' AND state = 'running' AND active_run_token = ?
+                        AND provider_session_id IS NULL`,
+                [providerSessionId, this.now().toISOString(), id, token]);
+                if (changed.changes !== 1) throw new DurableAgentRepositoryError('Print run ownership changed.');
+            });
+        } catch (error) {
+            if (error instanceof DurableAgentRepositoryError || error instanceof DurableAgentNotFoundError
+                || error instanceof CodexPrintError) throw error;
+            if (/UNIQUE constraint failed: durable_agents\.provider_session_id/i.test((error as Error).message)) {
+                throw new CodexPrintError('Provider session is already bound to another durable agent.', 'CODEX_SESSION_MISMATCH');
+            }
+            throw this.storageError('Failed to bind durable-agent provider session', error);
+        }
+        return this.requireById(id);
+    }
+
     async completeRun(id: string, token: string, result: DurableRunCompletion): Promise<DurableAgent> {
         this.assertWritable();
         const completedAt = this.now().toISOString();
@@ -227,6 +266,10 @@ export class DurableAgentRepository {
     }
 
     private fromRow(row: DurableAgentRow): DurableAgent {
+        if (!['claude', 'codex', 'pi'].includes(row.provider)
+            || (row.provider !== 'codex' && row.provider_session_id === null)) {
+            throw new DurableAgentRepositoryError(`Invalid durable-agent provider record: ${row.id}`);
+        }
         const activeRun: DurableActiveRun | null = row.active_run_token === null ? null : {
             token: row.active_run_token,
             owner: { pid: row.active_owner_pid!, startedAt: row.active_owner_started_at! },
@@ -235,9 +278,9 @@ export class DurableAgentRepository {
             },
             startedAt: row.active_run_started_at!,
         };
-        return {
+        const base = {
             id: row.id, name: row.name, provider: row.provider, mode: row.mode, cwd: row.cwd,
-            providerSessionId: row.provider_session_id, state: row.state, sessionHealth: row.session_health,
+            state: row.state, sessionHealth: row.session_health,
             createdAt: row.created_at, updatedAt: row.updated_at, lastActiveAt: row.last_active_at,
             lastResult: row.last_result_status === null ? null : {
                 status: row.last_result_status, completedAt: row.last_result_completed_at!,
@@ -245,6 +288,13 @@ export class DurableAgentRepository {
             },
             activeRun,
         };
+        if (row.provider === 'claude') {
+            return { ...base, provider: 'claude', providerSessionId: row.provider_session_id! };
+        }
+        if (row.provider === 'pi') {
+            return { ...base, provider: 'pi', providerSessionId: row.provider_session_id! };
+        }
+        return { ...base, provider: 'codex', providerSessionId: row.provider_session_id };
     }
 
     private canonicalDirectory(input: string): string {
@@ -284,24 +334,3 @@ export class DurableAgentRepository {
             : new DurableAgentRepositoryError(`${prefix}: ${(error as Error).message}`);
     }
 }
-
-export class LocalProcessInspector implements ProcessInspector {
-    getIdentity(pid: number): ProcessIdentity | null {
-        if (!Number.isInteger(pid) || pid <= 0) return null;
-        try {
-            if (process.platform === 'linux') {
-                const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
-                const close = stat.lastIndexOf(')');
-                const fields = stat.slice(close + 2).split(' ');
-                const startTicks = fields[19];
-                return startTicks ? { pid, startedAt: `linux:${startTicks}` } : null;
-            }
-            const startedAt = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
-                encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
-            }).trim();
-            return startedAt ? { pid, startedAt } : null;
-        } catch {
-            return null;
-        }
-    }
-}

package/src/durable/process.ts

@@ -0,0 +1,28 @@
+import fs from 'fs';
+import { execFileSync } from 'child_process';
+import type { ProcessIdentity } from './DurableAgent.js';
+
+export interface ProcessInspector {
+    getIdentity(pid: number): ProcessIdentity | null;
+}
+
+export class LocalProcessInspector implements ProcessInspector {
+    getIdentity(pid: number): ProcessIdentity | null {
+        if (!Number.isInteger(pid) || pid <= 0) return null;
+        try {
+            if (process.platform === 'linux') {
+                const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+                const close = stat.lastIndexOf(')');
+                const fields = stat.slice(close + 2).split(' ');
+                const startTicks = fields[19];
+                return startTicks ? { pid, startedAt: `linux:${startTicks}` } : null;
+            }
+            const startedAt = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+                encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            return startedAt ? { pid, startedAt } : null;
+        } catch {
+            return null;
+        }
+    }
+}

package/src/durable/run.ts

@@ -0,0 +1,74 @@
+import type { DurableAgent, DurableProvider } from './DurableAgent.js';
+import { DurableAgentNotFoundError } from './DurableAgent.js';
+import type { DurableRunCompletion } from './DurableAgentRepository.js';
+import { sanitizeText } from './utils.js';
+
+const MAX_RESULT_SUMMARY_LENGTH = 4096;
+
+export interface DurableRunRepository {
+    resolve(reference: string): Promise<DurableAgent | DurableAgent[] | null>;
+    acquireRun(id: string): Promise<{ agent: DurableAgent; token: string }>;
+    completeRun(id: string, token: string, result: DurableRunCompletion): Promise<DurableAgent>;
+}
+
+type ProviderAgent<Provider extends DurableProvider> = Extract<DurableAgent, { provider: Provider }>;
+
+interface DurableRunResult {
+    result: string;
+    exitCode: number;
+}
+
+interface DurableRunOptions<Provider extends DurableProvider, Result extends DurableRunResult> {
+    reference: string;
+    provider: Provider;
+    repository: DurableRunRepository;
+    ambiguousError(): Error;
+    providerError(): Error;
+    execute(agent: ProviderAgent<Provider>, token: string): Promise<Result>;
+    isSessionMismatch(error: unknown): boolean;
+}
+
+export async function runDurableAgent<Provider extends DurableProvider, Result extends DurableRunResult>(
+    options: DurableRunOptions<Provider, Result>,
+): Promise<{ agent: ProviderAgent<Provider>; result: Result }> {
+    const resolved = await options.repository.resolve(options.reference);
+    if (!resolved) throw new DurableAgentNotFoundError(options.reference);
+    if (Array.isArray(resolved)) throw options.ambiguousError();
+    if (resolved.provider !== options.provider) throw options.providerError();
+
+    const target = resolved as ProviderAgent<Provider>;
+    const acquired = await options.repository.acquireRun(target.id);
+    let result: Result;
+    try {
+        result = await options.execute(acquired.agent as ProviderAgent<Provider>, acquired.token);
+    } catch (error) {
+        await options.repository.completeRun(
+            target.id,
+            acquired.token,
+            createFailedCompletion(error, options.isSessionMismatch(error)),
+        );
+        throw error;
+    }
+
+    await options.repository.completeRun(target.id, acquired.token, createSucceededCompletion(result));
+    return { agent: target, result };
+}
+
+function createSucceededCompletion(result: DurableRunResult): DurableRunCompletion {
+    return {
+        status: 'succeeded',
+        exitCode: result.exitCode,
+        summary: sanitizeText(result.result, MAX_RESULT_SUMMARY_LENGTH, { preserveFormatting: true }),
+        sessionHealth: 'healthy',
+    };
+}
+
+function createFailedCompletion(error: unknown, sessionMismatch: boolean): DurableRunCompletion {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        status: 'failed',
+        exitCode: null,
+        summary: sanitizeText(message, MAX_RESULT_SUMMARY_LENGTH, { preserveFormatting: true }),
+        sessionHealth: sessionMismatch ? 'mismatch' : 'unknown',
+    };
+}

package/src/durable/utils.ts

@@ -0,0 +1,61 @@
+import type { ChildProcessWithoutNullStreams } from 'child_process';
+
+export interface ChildCloseResult {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}
+
+export function waitForChildClose(child: ChildProcessWithoutNullStreams): Promise<ChildCloseResult> {
+    return new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (code, signal) => resolve({ code, signal }));
+    });
+}
+
+export function sanitizeText(
+    value: string,
+    max: number,
+    options: { preserveFormatting?: boolean } = {},
+): string {
+    return Array.from(value, (character) => {
+        const code = character.charCodeAt(0);
+        if (options.preserveFormatting && (code === 9 || code === 10 || code === 13)) return character;
+        return code <= 31 || code === 127 ? ' ' : character;
+    }).join('').trim().slice(0, max);
+}
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function isUuid(value: string): boolean {
+    return UUID_PATTERN.test(value);
+}
+
+export class LineBuffer {
+    private buffer = Buffer.alloc(0);
+
+    constructor(
+        private readonly maxLineBytes: number,
+        private readonly createOversizedLineError: () => Error,
+    ) {}
+
+    accept(chunk: Buffer | string): Buffer[] {
+        this.buffer = Buffer.concat([this.buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+        if (this.buffer.length > this.maxLineBytes && this.buffer.indexOf(0x0a) < 0) {
+            throw this.createOversizedLineError();
+        }
+
+        const lines: Buffer[] = [];
+        let newline: number;
+        while ((newline = this.buffer.indexOf(0x0a)) >= 0) {
+            const line = this.buffer.subarray(0, newline);
+            this.buffer = this.buffer.subarray(newline + 1);
+            if (line.length > this.maxLineBytes) throw this.createOversizedLineError();
+            lines.push(line);
+        }
+        return lines;
+    }
+
+    assertComplete(createIncompleteLineError: () => Error): void {
+        if (this.buffer.length > 0) throw createIncompleteLineError();
+    }
+}