@ai-devkit/agent-manager 0.28.1 → 0.30.0

package/src/providers/claude/durable/ClaudePrintRunner.ts

@@ -0,0 +1,92 @@
+import { spawn as nodeSpawn, type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from 'child_process';
+import type { ClaudeDurableAgent, ProcessIdentity } from '../../../durable/DurableAgent.js';
+import { ClaudePrintError } from '../../../durable/DurableAgent.js';
+import { LocalProcessInspector, type ProcessInspector } from '../../../durable/process.js';
+import { waitForChildClose } from '../../../durable/utils.js';
+import { ClaudeStreamParser } from './ClaudeStreamParser.js';
+
+type Spawn = (
+    command: string,
+    args: readonly string[],
+    options: SpawnOptionsWithoutStdio & { stdio: ['pipe', 'pipe', 'pipe'] },
+) => ChildProcessWithoutNullStreams;
+
+export interface ClaudePrintRunRequest {
+    agent: ClaudeDurableAgent;
+    prompt: string;
+    executable?: string;
+    firstRun: boolean;
+    onSpawn(identity: ProcessIdentity): Promise<void>;
+}
+
+export interface ClaudePrintRunResult {
+    sessionId: string;
+    result: string;
+    exitCode: number;
+}
+
+export interface ClaudePrintRunnerOptions {
+    spawn?: Spawn;
+    processInspector?: ProcessInspector;
+    maxLineBytes?: number;
+}
+
+export class ClaudePrintRunner {
+    private readonly spawn: Spawn;
+    private readonly processInspector: ProcessInspector;
+    private readonly maxLineBytes: number;
+
+    constructor(options: ClaudePrintRunnerOptions = {}) {
+        this.spawn = options.spawn ?? (nodeSpawn as Spawn);
+        this.processInspector = options.processInspector ?? new LocalProcessInspector();
+        this.maxLineBytes = options.maxLineBytes ?? 1024 * 1024;
+    }
+
+    async run(request: ClaudePrintRunRequest): Promise<ClaudePrintRunResult> {
+        const sessionArgs = request.firstRun
+            ? ['--session-id', request.agent.providerSessionId]
+            : ['--resume', request.agent.providerSessionId];
+        const args = ['-p', ...sessionArgs, '--output-format', 'stream-json', '--verbose'];
+        const child = this.spawn(request.executable ?? 'claude', args, {
+            cwd: request.agent.cwd,
+            shell: false,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        if (!child.pid) {
+            child.kill();
+            throw new ClaudePrintError('Claude process did not provide a PID.', 'CLAUDE_PROCESS_IDENTITY');
+        }
+        const identity = this.processInspector.getIdentity(child.pid);
+        if (!identity) {
+            child.kill();
+            throw new ClaudePrintError('Cannot verify Claude process identity.', 'CLAUDE_PROCESS_IDENTITY');
+        }
+
+        const parser = new ClaudeStreamParser(request.agent.providerSessionId, this.maxLineBytes);
+
+        child.stdout.on('data', (chunk: Buffer | string) => {
+            if (parser.hasFailed()) return;
+            try {
+                parser.accept(chunk);
+            } catch (error) {
+                parser.fail(error);
+            }
+        });
+        // Drain provider diagnostics without reflecting potentially sensitive prompt/tool data.
+        child.stderr.resume();
+
+        const closed = waitForChildClose(child);
+
+        try {
+            await request.onSpawn(identity);
+        } catch (error) {
+            child.kill();
+            throw error;
+        }
+
+        child.stdin.end(request.prompt);
+        const { code, signal } = await closed;
+
+        return parser.result({ code, signal });
+    }
+}

package/src/providers/claude/durable/ClaudeStreamParser.ts

@@ -0,0 +1,79 @@
+import { ClaudePrintError } from '../../../durable/DurableAgent.js';
+import { LineBuffer, type ChildCloseResult } from '../../../durable/utils.js';
+import type { ClaudePrintRunResult } from './ClaudePrintRunner.js';
+
+export class ClaudeStreamParser {
+    private readonly lines: LineBuffer;
+    private terminal: ClaudePrintRunResult | null = null;
+    private protocolError: ClaudePrintError | null = null;
+
+    constructor(
+        private readonly expectedSessionId: string,
+        maxLineBytes: number,
+    ) {
+        this.lines = new LineBuffer(
+            maxLineBytes,
+            () => new ClaudePrintError('Claude stream line exceeded the safety limit.', 'CLAUDE_STREAM_OVERSIZED'),
+        );
+    }
+
+    hasFailed(): boolean {
+        return this.protocolError !== null;
+    }
+
+    accept(chunk: Buffer | string): void {
+        for (const line of this.lines.accept(chunk)) {
+            this.processLine(line);
+        }
+    }
+
+    fail(error: unknown): void {
+        this.protocolError = error instanceof ClaudePrintError
+            ? error
+            : new ClaudePrintError('Claude stream processing failed.', 'CLAUDE_STREAM_INVALID');
+    }
+
+    result(close: ChildCloseResult): ClaudePrintRunResult {
+        if (this.protocolError) throw this.protocolError;
+        this.lines.assertComplete(() => new ClaudePrintError('Claude stream ended with incomplete JSON.', 'CLAUDE_STREAM_INVALID'));
+        if (close.code !== 0) {
+            throw new ClaudePrintError(
+                `Claude print run failed${close.signal ? ` (${close.signal})` : '.'}`,
+                'CLAUDE_PROCESS_FAILED',
+            );
+        }
+        if (!this.terminal) throw new ClaudePrintError('Claude stream ended without a terminal result.', 'CLAUDE_RESULT_MISSING');
+        return { sessionId: this.terminal.sessionId, result: this.terminal.result, exitCode: close.code };
+    }
+
+    private processLine(line: Buffer): void {
+        if (line.length === 0) return;
+
+        const event = this.parseEvent(line);
+        if (typeof event.session_id === 'string' && event.session_id !== this.expectedSessionId) {
+            throw new ClaudePrintError('Claude returned a different session identity.', 'CLAUDE_SESSION_MISMATCH');
+        }
+        if (event.type === 'result') this.recordTerminalResult(event);
+    }
+
+    private parseEvent(line: Buffer): Record<string, unknown> {
+        let value: unknown;
+        try {
+            value = JSON.parse(line.toString('utf8'));
+        } catch {
+            throw new ClaudePrintError('Claude emitted malformed stream JSON.', 'CLAUDE_STREAM_INVALID');
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new ClaudePrintError('Claude emitted a non-object stream message.', 'CLAUDE_STREAM_INVALID');
+        }
+        return value as Record<string, unknown>;
+    }
+
+    private recordTerminalResult(event: Record<string, unknown>): void {
+        if (this.terminal) throw new ClaudePrintError('Claude emitted more than one terminal result.', 'CLAUDE_STREAM_INVALID');
+        if (typeof event.session_id !== 'string' || typeof event.result !== 'string') {
+            throw new ClaudePrintError('Claude emitted an invalid terminal result.', 'CLAUDE_STREAM_INVALID');
+        }
+        this.terminal = { sessionId: event.session_id, result: event.result, exitCode: 0 };
+    }
+}

package/src/providers/codex/durable/CodexCliProbe.ts

@@ -0,0 +1,60 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { CodexPrintError } from '../../../durable/DurableAgent.js';
+import { sanitizeText } from '../../../durable/utils.js';
+
+type ExecResult = { stdout: string; stderr: string };
+type Exec = (file: string, args: string[]) => Promise<ExecResult>;
+
+const execFileAsync = promisify(execFile);
+
+export interface CodexCliProbeOptions {
+    executable?: string;
+    exec?: Exec;
+}
+
+export class CodexCliProbe {
+    private readonly executable: string;
+    private readonly exec: Exec;
+
+    constructor(options: CodexCliProbeOptions = {}) {
+        this.executable = options.executable ?? 'codex';
+        this.exec = options.exec ?? (async (file, args) => {
+            const result = await execFileAsync(file, args, { encoding: 'utf8', maxBuffer: 1024 * 1024 });
+            return { stdout: result.stdout, stderr: result.stderr };
+        });
+    }
+
+    async validate(): Promise<{ executable: string; version: string }> {
+        try {
+            const version = await this.exec(this.executable, ['--version']);
+            const execHelp = await this.exec(this.executable, ['exec', '--help']);
+            const resumeHelp = await this.exec(this.executable, ['exec', 'resume', '--help']);
+            const missing = [
+                !execHelp.stdout.includes('exec') && 'exec',
+                !execHelp.stdout.includes('--json') && '--json',
+                !hasStdinDash(execHelp.stdout) && 'stdin -',
+                !resumeHelp.stdout.includes('resume') && 'resume',
+                !resumeHelp.stdout.includes('--json') && 'resume --json',
+                !hasStdinDash(resumeHelp.stdout) && 'resume stdin -',
+            ].filter((value): value is string => typeof value === 'string');
+            if (missing.length > 0) {
+                throw new CodexPrintError(
+                    `Codex CLI does not support required print-mode capabilities: ${missing.join(', ')}.`,
+                    'CODEX_CLI_UNSUPPORTED',
+                );
+            }
+            return { executable: this.executable, version: sanitizeText(version.stdout, 256) || 'unknown' };
+        } catch (error) {
+            if (error instanceof CodexPrintError) throw error;
+            throw new CodexPrintError(
+                `Codex CLI validation failed: ${sanitizeText((error as Error).message, 512)}`,
+                'CODEX_CLI_UNAVAILABLE',
+            );
+        }
+    }
+}
+
+function hasStdinDash(help: string): boolean {
+    return /(?:^|\s)-(?:\s|$)/m.test(help);
+}

package/src/providers/codex/durable/CodexPrintAgentService.ts

@@ -0,0 +1,65 @@
+import type { DurableAgent, ProcessIdentity } from '../../../durable/DurableAgent.js';
+import { CodexPrintError } from '../../../durable/DurableAgent.js';
+import { CodexCliProbe } from './CodexCliProbe.js';
+import { CodexPrintRunner, type CodexPrintRunResult } from './CodexPrintRunner.js';
+import { DurableAgentRepository, type CreateDurableAgentInput } from '../../../durable/DurableAgentRepository.js';
+import { runDurableAgent, type DurableRunRepository } from '../../../durable/run.js';
+
+interface RepositoryLike extends DurableRunRepository {
+    create(input: CreateDurableAgentInput): Promise<DurableAgent>;
+    list(): Promise<DurableAgent[]>;
+    recordProviderProcess(id: string, token: string, identity: ProcessIdentity): Promise<void>;
+    bindProviderSession(id: string, token: string, providerSessionId: string): Promise<DurableAgent>;
+}
+
+interface ProbeLike { validate(): Promise<{ executable: string; version: string }> }
+interface RunnerLike { run(request: Parameters<CodexPrintRunner['run']>[0]): Promise<CodexPrintRunResult> }
+
+export interface CodexPrintAgentServiceOptions {
+    repository?: RepositoryLike;
+    probe?: ProbeLike;
+    runner?: RunnerLike;
+    executable?: string;
+}
+
+export interface CodexPrintSendResult extends CodexPrintRunResult {
+    agentId: string;
+    agentName: string;
+}
+
+export class CodexPrintAgentService {
+    readonly repository: RepositoryLike;
+    private readonly probe: ProbeLike;
+    private readonly runner: RunnerLike;
+    private readonly executable?: string;
+
+    constructor(options: CodexPrintAgentServiceOptions = {}) {
+        this.repository = options.repository ?? new DurableAgentRepository();
+        this.probe = options.probe ?? new CodexCliProbe();
+        this.runner = options.runner ?? new CodexPrintRunner();
+        this.executable = options.executable;
+    }
+
+    async create(input: Omit<CreateDurableAgentInput, 'provider'>): Promise<DurableAgent> {
+        await this.probe.validate();
+        return this.repository.create({ ...input, provider: 'codex' });
+    }
+
+    async send(reference: string, prompt: string): Promise<CodexPrintSendResult> {
+        const completed = await runDurableAgent({
+            reference, provider: 'codex', repository: this.repository,
+            ambiguousError: () => new CodexPrintError('Multiple print agents match.', 'CODEX_UNSUPPORTED'),
+            providerError: () => new CodexPrintError('Print agent provider is not Codex.', 'CODEX_UNSUPPORTED'),
+            execute: (agent, token) => this.runner.run({
+                agent,
+                prompt,
+                executable: this.executable,
+                onSpawn: (identity) => this.repository.recordProviderProcess(agent.id, token, identity),
+                onSession: async (sessionId) => { await this.repository.bindProviderSession(agent.id, token, sessionId); },
+            }),
+            isSessionMismatch: (error) => error instanceof CodexPrintError
+                && error.code === 'CODEX_SESSION_MISMATCH',
+        });
+        return { ...completed.result, agentId: completed.agent.id, agentName: completed.agent.name };
+    }
+}

package/src/providers/codex/durable/CodexPrintRunner.ts

@@ -0,0 +1,94 @@
+import { spawn as nodeSpawn, type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from 'child_process';
+import type { CodexDurableAgent, ProcessIdentity } from '../../../durable/DurableAgent.js';
+import { CodexPrintError } from '../../../durable/DurableAgent.js';
+import { LocalProcessInspector, type ProcessInspector } from '../../../durable/process.js';
+import { waitForChildClose } from '../../../durable/utils.js';
+import { CodexStreamParser } from './CodexStreamParser.js';
+
+type Spawn = (
+    command: string,
+    args: readonly string[],
+    options: SpawnOptionsWithoutStdio & { stdio: ['pipe', 'pipe', 'pipe'] },
+) => ChildProcessWithoutNullStreams;
+
+export interface CodexPrintRunRequest {
+    agent: CodexDurableAgent;
+    prompt: string;
+    executable?: string;
+    onSpawn(identity: ProcessIdentity): Promise<void>;
+    onSession(providerSessionId: string): Promise<void>;
+}
+
+export interface CodexPrintRunResult {
+    sessionId: string;
+    result: string;
+    messages: string[];
+    exitCode: number;
+}
+
+export interface CodexPrintRunnerOptions {
+    spawn?: Spawn;
+    processInspector?: ProcessInspector;
+    maxLineBytes?: number;
+}
+
+export class CodexPrintRunner {
+    private readonly spawn: Spawn;
+    private readonly processInspector: ProcessInspector;
+    private readonly maxLineBytes: number;
+
+    constructor(options: CodexPrintRunnerOptions = {}) {
+        this.spawn = options.spawn ?? (nodeSpawn as Spawn);
+        this.processInspector = options.processInspector ?? new LocalProcessInspector();
+        this.maxLineBytes = options.maxLineBytes ?? 1024 * 1024;
+    }
+
+    async run(request: CodexPrintRunRequest): Promise<CodexPrintRunResult> {
+        const args = buildCodexExecArgs(request.agent);
+        const child = this.spawn(request.executable ?? 'codex', args, {
+            cwd: request.agent.cwd, shell: false, stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const identity = this.verifyProcessIdentity(child);
+
+        const parser = new CodexStreamParser(request.agent.providerSessionId, request.onSession, this.maxLineBytes);
+        let processing = Promise.resolve();
+
+        child.stdout.on('data', (chunk: Buffer | string) => {
+            if (parser.hasFailed()) return;
+            processing = processing.then(() => parser.accept(chunk)).catch((error) => parser.fail(error));
+        });
+        child.stderr.resume();
+        const closed = waitForChildClose(child);
+        try {
+            await request.onSpawn(identity);
+        } catch (error) {
+            child.kill();
+            throw error;
+        }
+        child.stdin.end(request.prompt);
+        const { code, signal } = await closed.catch(() => {
+            throw new CodexPrintError('Codex process failed to start or communicate.', 'CODEX_PROCESS');
+        });
+        await processing;
+        return parser.result({ code, signal });
+    }
+
+    private verifyProcessIdentity(child: ChildProcessWithoutNullStreams): ProcessIdentity {
+        if (!child.pid) {
+            child.kill();
+            throw new CodexPrintError('Codex process did not provide a PID.', 'CODEX_PROCESS');
+        }
+        const identity = this.processInspector.getIdentity(child.pid);
+        if (!identity) {
+            child.kill();
+            throw new CodexPrintError('Cannot verify Codex process identity.', 'CODEX_PROCESS');
+        }
+        return identity;
+    }
+}
+
+function buildCodexExecArgs(agent: CodexDurableAgent): string[] {
+    return agent.providerSessionId === null
+        ? ['exec', '--json', '-']
+        : ['exec', 'resume', '--json', agent.providerSessionId, '-'];
+}

package/src/providers/codex/durable/CodexStreamParser.ts

@@ -0,0 +1,104 @@
+import { CodexPrintError } from '../../../durable/DurableAgent.js';
+import { isUuid, LineBuffer, type ChildCloseResult } from '../../../durable/utils.js';
+import type { CodexPrintRunResult } from './CodexPrintRunner.js';
+
+export class CodexStreamParser {
+    private readonly lines: LineBuffer;
+    private sessionId: string | null = null;
+    private turnCompleted = false;
+    private readonly messages: string[] = [];
+    private protocolError: CodexPrintError | null = null;
+
+    constructor(
+        private readonly expectedSessionId: string | null,
+        private readonly onSession: (providerSessionId: string) => Promise<void>,
+        maxLineBytes: number,
+    ) {
+        this.lines = new LineBuffer(
+            maxLineBytes,
+            () => new CodexPrintError('Codex stream line exceeded the safety limit.', 'CODEX_PROTOCOL'),
+        );
+    }
+
+    hasFailed(): boolean {
+        return this.protocolError !== null;
+    }
+
+    async accept(chunk: Buffer | string): Promise<void> {
+        for (const line of this.lines.accept(chunk)) {
+            await this.processLine(line);
+        }
+    }
+
+    fail(error: unknown): void {
+        this.protocolError = error instanceof CodexPrintError
+            ? error
+            : new CodexPrintError('Codex stream processing failed.', 'CODEX_PROTOCOL');
+    }
+
+    result(close: ChildCloseResult): CodexPrintRunResult {
+        if (this.protocolError) throw this.protocolError;
+        this.lines.assertComplete(
+            () => new CodexPrintError('Codex stream ended with incomplete JSON.', 'CODEX_PROTOCOL'),
+        );
+
+        if (close.code !== 0) {
+            throw new CodexPrintError(`Codex print run failed${close.signal ? ` (${close.signal})` : '.'}`, 'CODEX_PROCESS');
+        }
+        if (this.sessionId === null) throw new CodexPrintError('Codex stream ended without a thread identity.', 'CODEX_PROTOCOL');
+        if (!this.turnCompleted) throw new CodexPrintError('Codex stream ended before turn completion.', 'CODEX_PROTOCOL');
+        if (this.messages.length === 0) throw new CodexPrintError('Codex stream ended without an assistant result.', 'CODEX_RESULT_MISSING');
+        return {
+            sessionId: this.sessionId,
+            result: this.messages.at(-1)!,
+            messages: this.messages,
+            exitCode: close.code,
+        };
+    }
+
+    private async processLine(line: Buffer): Promise<void> {
+        if (this.protocolError || line.length === 0) return;
+
+        const event = this.parseEvent(line);
+        if (event.type === 'thread.started') {
+            await this.recordSession(event);
+        } else if (event.type === 'item.completed') {
+            this.recordAssistantMessage(event.item);
+        } else if (event.type === 'turn.completed') {
+            this.turnCompleted = true;
+        }
+    }
+
+    private parseEvent(line: Buffer): Record<string, unknown> {
+        let value: unknown;
+        try {
+            value = JSON.parse(line.toString('utf8'));
+        } catch {
+            throw new CodexPrintError('Codex emitted malformed stream JSON.', 'CODEX_PROTOCOL');
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new CodexPrintError('Codex emitted a non-object stream message.', 'CODEX_PROTOCOL');
+        }
+        return value as Record<string, unknown>;
+    }
+
+    private async recordSession(event: Record<string, unknown>): Promise<void> {
+        const sessionId = String(event.thread_id ?? '');
+        if (this.sessionId !== null || !isUuid(sessionId)) {
+            throw new CodexPrintError('Codex emitted an invalid thread identity.', 'CODEX_PROTOCOL');
+        }
+        if (this.expectedSessionId !== null && this.expectedSessionId !== sessionId) {
+            throw new CodexPrintError('Codex returned a different session identity.', 'CODEX_SESSION_MISMATCH');
+        }
+        this.sessionId = sessionId;
+        await this.onSession(sessionId);
+    }
+
+    private recordAssistantMessage(item: unknown): void {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) return;
+        const record = item as Record<string, unknown>;
+        if (record.type === 'agent_message' && typeof record.text === 'string' && record.text.trim()) {
+            this.messages.push(record.text);
+        }
+    }
+}

package/src/providers/pi/durable/PiCliProbe.ts

@@ -0,0 +1,48 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { PiPrintError } from '../../../durable/DurableAgent.js';
+import { sanitizeText } from '../../../durable/utils.js';
+
+type ExecResult = { stdout: string; stderr: string };
+type Exec = (file: string, args: string[]) => Promise<ExecResult>;
+const execFileAsync = promisify(execFile);
+const REQUIRED = ['--mode', 'json', '--session-id', '--session'];
+
+export interface PiCliProbeOptions {
+    executable?: string;
+    exec?: Exec;
+}
+
+export class PiCliProbe {
+    private readonly executable: string;
+    private readonly exec: Exec;
+
+    constructor(options: PiCliProbeOptions = {}) {
+        this.executable = options.executable ?? 'pi';
+        this.exec = options.exec ?? (async (file, args) => {
+            const result = await execFileAsync(file, args, { encoding: 'utf8', maxBuffer: 1024 * 1024 });
+            return { stdout: result.stdout, stderr: result.stderr };
+        });
+    }
+
+    async validate(): Promise<{ executable: string; version: string }> {
+        try {
+            const version = await this.exec(this.executable, ['--version']);
+            const help = await this.exec(this.executable, ['--help']);
+            const missing = REQUIRED.filter((capability) => !help.stdout.includes(capability));
+            if (missing.length > 0) {
+                throw new PiPrintError(
+                    `Pi CLI does not support required print-mode capabilities: ${missing.join(', ')}.`,
+                    'PI_CLI_UNSUPPORTED',
+                );
+            }
+            return { executable: this.executable, version: sanitizeText(version.stdout, 256) || 'unknown' };
+        } catch (error) {
+            if (error instanceof PiPrintError) throw error;
+            throw new PiPrintError(
+                `Pi CLI validation failed: ${sanitizeText((error as Error).message, 512)}`,
+                'PI_CLI_UNAVAILABLE',
+            );
+        }
+    }
+}

package/src/providers/pi/durable/PiPrintAgentService.ts

@@ -0,0 +1,69 @@
+import type { DurableAgent, ProcessIdentity } from '../../../durable/DurableAgent.js';
+import { PiPrintError } from '../../../durable/DurableAgent.js';
+import { PiCliProbe } from './PiCliProbe.js';
+import { PiPrintRunner, type PiPrintRunResult } from './PiPrintRunner.js';
+import { DurableAgentRepository, type CreateDurableAgentInput } from '../../../durable/DurableAgentRepository.js';
+import { runDurableAgent, type DurableRunRepository } from '../../../durable/run.js';
+
+interface RepositoryLike extends DurableRunRepository {
+    create(input: CreateDurableAgentInput): Promise<DurableAgent>;
+    list(): Promise<DurableAgent[]>;
+    recordProviderProcess(id: string, token: string, identity: ProcessIdentity): Promise<void>;
+}
+
+interface ProbeLike { validate(): Promise<{ executable: string; version: string }> }
+interface RunnerLike { run(request: Parameters<PiPrintRunner['run']>[0]): Promise<PiPrintRunResult> }
+
+export interface PiPrintAgentServiceOptions {
+    repository?: RepositoryLike;
+    probe?: ProbeLike;
+    runner?: RunnerLike;
+    executable?: string;
+}
+
+export interface PiPrintSendResult extends PiPrintRunResult {
+    agentId: string;
+    agentName: string;
+}
+
+export class PiPrintAgentService {
+    readonly repository: RepositoryLike;
+    private readonly probe: ProbeLike;
+    private readonly runner: RunnerLike;
+    private readonly executable?: string;
+
+    constructor(options: PiPrintAgentServiceOptions = {}) {
+        this.repository = options.repository ?? new DurableAgentRepository();
+        this.probe = options.probe ?? new PiCliProbe();
+        this.runner = options.runner ?? new PiPrintRunner();
+        this.executable = options.executable;
+    }
+
+    async create(input: Omit<CreateDurableAgentInput, 'provider'>): Promise<DurableAgent> {
+        await this.probe.validate();
+        return this.repository.create({ ...input, provider: 'pi' });
+    }
+
+    async send(reference: string, prompt: string): Promise<PiPrintSendResult> {
+        const completed = await runDurableAgent({
+            reference,
+            provider: 'pi',
+            repository: this.repository,
+            ambiguousError: () => new PiPrintError('Multiple print agents match.', 'PI_UNSUPPORTED'),
+            providerError: () => new PiPrintError('Print agent provider is not Pi.', 'PI_UNSUPPORTED'),
+            execute: (agent, token) => this.runner.run({
+                agent,
+                prompt,
+                executable: this.executable,
+                onSpawn: (identity) => this.repository.recordProviderProcess(agent.id, token, identity),
+            }),
+            isSessionMismatch: (error) => error instanceof PiPrintError
+                && error.code === 'PI_SESSION_MISMATCH',
+        });
+        return {
+            ...completed.result,
+            agentId: completed.agent.id,
+            agentName: completed.agent.name,
+        };
+    }
+}

package/src/providers/pi/durable/PiPrintProtocol.ts

@@ -0,0 +1,39 @@
+import { PiPrintError } from '../../../durable/DurableAgent.js';
+import { isUuid } from '../../../durable/utils.js';
+
+export function buildPiPrintArgs(providerSessionId: string, firstRun: boolean): string[] {
+    return firstRun
+        ? ['--mode', 'json', '--session-id', providerSessionId]
+        : ['--mode', 'json', '--session', providerSessionId];
+}
+
+export function readPiSessionId(
+    event: Record<string, unknown>,
+    currentSessionId: string | null,
+    expectedSessionId: string,
+): string {
+    if (currentSessionId !== null || typeof event.id !== 'string' || !isUuid(event.id)) {
+        throw new PiPrintError('Pi emitted an invalid session identity.', 'PI_PROTOCOL');
+    }
+    const sessionId = event.id;
+    if (expectedSessionId !== sessionId) {
+        throw new PiPrintError('Pi returned a different session identity.', 'PI_SESSION_MISMATCH');
+    }
+    return sessionId;
+}
+
+export function readPiAssistantText(event: Record<string, unknown>): string | null {
+    if (event.type !== 'message_end') return null;
+    const message = event.message;
+    if (!message || typeof message !== 'object' || Array.isArray(message)) return null;
+    const record = message as Record<string, unknown>;
+    if (record.role !== 'assistant') return null;
+    if (typeof record.content === 'string') return record.content.trim() ? record.content : null;
+    if (!Array.isArray(record.content)) return null;
+    const text = record.content.flatMap((part) => {
+        if (!part || typeof part !== 'object' || Array.isArray(part)) return [];
+        const block = part as Record<string, unknown>;
+        return block.type === 'text' && typeof block.text === 'string' ? [block.text] : [];
+    }).join('');
+    return text.trim() ? text : null;
+}