@ai-devkit/agent-manager 0.25.0 → 0.26.1

package/src/__tests__/terminal/TmuxManager.test.ts

@@ -106,6 +106,16 @@ describe('TmuxManager', () => {
             expect(await tmux.findAgentPid('foo', matchesClaude)).toBeNull();
         });
 
+        it('returns the matching pane PID when the agent replaces the shell', async () => {
+            setExecFileHandler((cmd, args) => {
+                if (cmd === 'tmux' && args[0] === 'list-panes') return '100\n';
+                if (cmd === 'pgrep') return new Error('no children');
+                if (cmd === 'ps' && args[1] === '100') return '/usr/local/bin/claude';
+                return '';
+            });
+            expect(await tmux.findAgentPid('foo', matchesClaude)).toBe(100);
+        });
+
         it('returns the matching descendant when found', async () => {
             // pane 100 → child 200 (claude) — no grandchildren
             setExecFileHandler((cmd, args) => {

package/src/adapters/CodexAdapter.ts

@@ -37,9 +37,26 @@ interface CodexEventEntry {
         id?: string;
         cwd?: string;
         timestamp?: string;
+        role?: string;
+        content?: CodexContent[];
+        item?: CodexItem;
+        turn_id?: string;
+        internal_chat_message_metadata_passthrough?: {
+            turn_id?: string;
+        };
     };
 }
 
+interface CodexContent {
+    type?: string;
+    text?: string;
+}
+
+interface CodexItem {
+    type?: string;
+    content?: string | CodexContent[];
+}
+
 interface CodexSession {
     sessionId: string;
     projectPath: string;
@@ -502,7 +519,7 @@ export class CodexAdapter implements AgentAdapter {
         }
 
         const lastEntry = this.findLastEventEntry(entries);
-        const lastPayloadType = lastEntry?.payload?.type;
+        const lastPayloadType = lastEntry ? this.normalizedPayloadType(lastEntry) : undefined;
 
         const lastActive =
             this.parseTimestamp(lastEntry?.timestamp) ||
@@ -596,15 +613,44 @@ export class CodexAdapter implements AgentAdapter {
 
     private extractSummary(entries: CodexEventEntry[]): string {
         for (let i = entries.length - 1; i >= 0; i--) {
-            const message = entries[i]?.payload?.message;
-            if (typeof message === 'string' && message.trim().length > 0) {
-                return this.truncate(message.trim(), 120);
-            }
+            const message = this.extractEntryText(entries[i]);
+            if (message) return this.truncate(message, 120);
         }
 
         return 'Codex session active';
     }
 
+    private normalizedPayloadType(entry: CodexEventEntry): string | undefined {
+        const payloadType = entry.payload?.type;
+
+        if (entry.type === 'response_item' && payloadType === 'message') {
+            if (entry.payload?.role === 'assistant') return 'agent_message';
+            if (entry.payload?.role === 'user') return 'user_message';
+            return payloadType;
+        }
+
+        if (entry.type === 'event_msg' && payloadType === 'item_completed') {
+            const itemType = entry.payload?.item?.type;
+            if (itemType === 'AgentMessage') return 'agent_message';
+            if (itemType === 'UserMessage') return 'user_message';
+            return itemType ?? payloadType;
+        }
+
+        return payloadType;
+    }
+
+    private extractEntryText(entry: CodexEventEntry | undefined): string {
+        if (!entry) return '';
+
+        const legacyMessage = entry.payload?.message;
+        if (typeof legacyMessage === 'string' && legacyMessage.trim().length > 0) {
+            return legacyMessage.trim();
+        }
+
+        const conversationMessage = this.toConversationMessage(entry, false);
+        return conversationMessage?.content.trim() ?? '';
+    }
+
     private truncate(value: string, maxLength: number): string {
         if (value.length <= maxLength) return value;
         return `${value.slice(0, maxLength - 3)}...`;
@@ -619,7 +665,8 @@ export class CodexAdapter implements AgentAdapter {
     /**
      * Read the full conversation from a Codex session JSONL file.
      *
-     * Codex entries use payload.type to indicate message role and payload.message for content.
+     * Codex entries use either legacy payload.message fields or current
+     * response_item/event_msg content arrays.
      */
     getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
         const verbose = options?.verbose ?? false;
@@ -628,45 +675,118 @@ export class CodexAdapter implements AgentAdapter {
         if (content === undefined) return [];
 
         const lines = content.trim().split('\n');
+        const entries: CodexEventEntry[] = [];
         const messages: ConversationMessage[] = [];
 
         for (const line of lines) {
-            let entry: CodexEventEntry;
             try {
-                entry = JSON.parse(line);
+                entries.push(JSON.parse(line));
             } catch {
                 continue;
             }
+        }
 
-            if (entry.type === 'session_meta') continue;
+        const responseItemMirrorKeys = new Set<string>();
+        for (const entry of entries) {
+            if (entry.type !== 'response_item') continue;
 
-            const payloadType = entry.payload?.type;
-            if (!payloadType) continue;
+            const message = this.toConversationMessage(entry, verbose);
+            const mirrorKey = message ? this.mirroredMessageKey(entry, message) : null;
+            if (mirrorKey) responseItemMirrorKeys.add(mirrorKey);
+        }
 
-            let role: ConversationMessage['role'];
-            if (payloadType === 'user_message') {
-                role = 'user';
-            } else if (payloadType === 'agent_message' || payloadType === 'task_complete') {
-                role = 'assistant';
-            } else if (verbose) {
-                role = 'system';
-            } else {
+        for (const entry of entries) {
+            const message = this.toConversationMessage(entry, verbose);
+            if (!message) continue;
+
+            const mirrorKey = this.mirroredMessageKey(entry, message);
+            if (
+                entry.type === 'event_msg' &&
+                mirrorKey &&
+                responseItemMirrorKeys.has(mirrorKey)
+            ) {
                 continue;
             }
 
-            const text = entry.payload?.message?.trim();
-            if (!text) continue;
-
-            messages.push({
-                role,
-                content: text,
-                timestamp: entry.timestamp,
-            });
+            messages.push(message);
         }
 
         return messages;
     }
 
+    private toConversationMessage(entry: CodexEventEntry, verbose: boolean): ConversationMessage | null {
+        if (entry.type === 'session_meta') return null;
+
+        const payloadType = entry.payload?.type;
+        if (entry.type === 'response_item' && payloadType === 'message') {
+            const role = this.mapCodexRole(entry.payload?.role, verbose);
+            const text = this.extractContentText(entry.payload?.content);
+            if (!role || !text) return null;
+
+            return { role, content: text, timestamp: entry.timestamp };
+        }
+
+        if (entry.type === 'event_msg' && payloadType === 'item_completed') {
+            const item = entry.payload?.item;
+            const role = this.mapCodexItemRole(item?.type, verbose);
+            const text = this.extractContentText(item?.content);
+            if (!role || !text) return null;
+
+            return { role, content: text, timestamp: entry.timestamp };
+        }
+
+        if (!payloadType) return null;
+
+        let role: ConversationMessage['role'];
+        if (payloadType === 'user_message') {
+            role = 'user';
+        } else if (payloadType === 'agent_message' || payloadType === 'task_complete') {
+            role = 'assistant';
+        } else if (verbose) {
+            role = 'system';
+        } else {
+            return null;
+        }
+
+        const text = entry.payload?.message?.trim();
+        if (!text) return null;
+
+        return { role, content: text, timestamp: entry.timestamp };
+    }
+
+    private mapCodexRole(role: string | undefined, verbose: boolean): ConversationMessage['role'] | null {
+        if (role === 'user') return 'user';
+        if (role === 'assistant') return 'assistant';
+        return verbose ? 'system' : null;
+    }
+
+    private mapCodexItemRole(itemType: string | undefined, verbose: boolean): ConversationMessage['role'] | null {
+        if (itemType === 'AgentMessage') return 'assistant';
+        if (itemType === 'UserMessage') return 'user';
+        return verbose ? 'system' : null;
+    }
+
+    private mirroredMessageKey(entry: CodexEventEntry, message: ConversationMessage): string | null {
+        const turnId =
+            entry.payload?.turn_id ||
+            entry.payload?.internal_chat_message_metadata_passthrough?.turn_id;
+
+        if (!turnId) return null;
+        return `${turnId}\0${message.role}\0${message.content}`;
+    }
+
+    private extractContentText(content: string | CodexContent[] | undefined): string {
+        if (typeof content === 'string') return content.trim();
+        if (!Array.isArray(content)) return '';
+
+        return content
+            .map((part) => part.text)
+            .filter((text): text is string => typeof text === 'string' && text.trim().length > 0)
+            .map((text) => text.trim())
+            .join('\n')
+            .trim();
+    }
+
     async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
         if (!isDirectory(this.codexSessionsDir)) return [];
 

package/src/index.ts

@@ -34,3 +34,42 @@ export type { AgentConfig, StartableAgentType } from './utils/agents.js';
 
 export type { AgentRequest } from './utils/agent-requests.js';
 export { getAgentRequestPath, readLatestAgentRequest, writeAgentRequest } from './utils/agent-requests.js';
+
+export {
+    PrintAgentError,
+    PrintAgentBusyError,
+    PrintAgentNotFoundError,
+    PrintAgentStoreError,
+    PrintAgentNameConflictError,
+    ClaudePrintError,
+} from './print/PrintAgent.js';
+export type {
+    PrintAgent,
+    PrintAgentState,
+    PrintSessionHealth,
+    PrintRunStatus,
+    PrintActiveRun,
+    PrintLastResult,
+    ProcessIdentity,
+} from './print/PrintAgent.js';
+export { PrintAgentStore } from './print/PrintAgentStore.js';
+export { LocalProcessInspector } from './print/PrintAgentStore.js';
+export type {
+    CreatePrintAgentInput,
+    PrintAgentStoreOptions,
+    ProcessInspector,
+    PrintRunCompletion,
+} from './print/PrintAgentStore.js';
+export { ClaudeCliProbe } from './print/ClaudeCliProbe.js';
+export type { ClaudeCliProbeOptions } from './print/ClaudeCliProbe.js';
+export { ClaudePrintRunner } from './print/ClaudePrintRunner.js';
+export type {
+    ClaudePrintRunnerOptions,
+    ClaudePrintRunRequest,
+    ClaudePrintRunResult,
+} from './print/ClaudePrintRunner.js';
+export { ClaudePrintAgentService } from './print/ClaudePrintAgentService.js';
+export type {
+    ClaudePrintAgentServiceOptions,
+    ClaudePrintSendResult,
+} from './print/ClaudePrintAgentService.js';

package/src/print/ClaudeCliProbe.ts

@@ -0,0 +1,58 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { ClaudePrintError } from './PrintAgent.js';
+
+type ExecResult = { stdout: string; stderr: string };
+type Exec = (file: string, args: string[]) => Promise<ExecResult>;
+
+const execFileAsync = promisify(execFile);
+const REQUIRED = ['--print', '--session-id', '--resume', '--output-format', 'stream-json'];
+
+export interface ClaudeCliProbeOptions {
+    executable?: string;
+    exec?: Exec;
+}
+
+export class ClaudeCliProbe {
+    private readonly executable: string;
+    private readonly exec: Exec;
+
+    constructor(options: ClaudeCliProbeOptions = {}) {
+        this.executable = options.executable ?? 'claude';
+        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 versionResult = await this.exec(this.executable, ['--version']);
+            const helpResult = await this.exec(this.executable, ['--help']);
+            const missing = REQUIRED.filter((capability) => !helpResult.stdout.includes(capability));
+            if (missing.length > 0) {
+                throw new ClaudePrintError(
+                    `Claude CLI does not support required print-mode capabilities: ${missing.join(', ')}.`,
+                    'CLAUDE_CLI_UNSUPPORTED',
+                );
+            }
+            return {
+                executable: this.executable,
+                version: sanitize(versionResult.stdout, 256) || 'unknown',
+            };
+        } catch (error) {
+            if (error instanceof ClaudePrintError) throw error;
+            throw new ClaudePrintError(
+                `Claude CLI validation failed: ${sanitize((error as Error).message, 512)}`,
+                'CLAUDE_CLI_UNAVAILABLE',
+            );
+        }
+    }
+}
+
+function sanitize(value: string, max: number): string {
+    return Array.from(value, (character) => {
+        const code = character.charCodeAt(0);
+        return code <= 31 || code === 127 ? ' ' : character;
+    }).join('').trim().slice(0, max);
+}

package/src/print/ClaudePrintAgentService.ts

@@ -0,0 +1,94 @@
+import type { PrintAgent, ProcessIdentity } from './PrintAgent.js';
+import { ClaudePrintError, PrintAgentNotFoundError } from './PrintAgent.js';
+import { ClaudeCliProbe } from './ClaudeCliProbe.js';
+import { ClaudePrintRunner, type ClaudePrintRunResult } from './ClaudePrintRunner.js';
+import { PrintAgentStore, type CreatePrintAgentInput, type PrintRunCompletion } from './PrintAgentStore.js';
+
+interface StoreLike {
+    create(input: CreatePrintAgentInput): Promise<PrintAgent>;
+    list(): Promise<PrintAgent[]>;
+    resolve(reference: string): Promise<PrintAgent | PrintAgent[] | null>;
+    acquireRun(id: string): Promise<{ agent: PrintAgent; token: string }>;
+    recordProviderProcess(id: string, token: string, identity: ProcessIdentity): Promise<void>;
+    completeRun(id: string, token: string, result: PrintRunCompletion): Promise<PrintAgent>;
+}
+
+interface ProbeLike { validate(): Promise<{ executable: string; version: string }> }
+interface RunnerLike { run(request: Parameters<ClaudePrintRunner['run']>[0]): Promise<ClaudePrintRunResult> }
+
+export interface ClaudePrintAgentServiceOptions {
+    store?: StoreLike;
+    probe?: ProbeLike;
+    runner?: RunnerLike;
+    executable?: string;
+}
+
+export interface ClaudePrintSendResult extends ClaudePrintRunResult {
+    agentId: string;
+    agentName: string;
+}
+
+export class ClaudePrintAgentService {
+    readonly store: StoreLike;
+    private readonly probe: ProbeLike;
+    private readonly runner: RunnerLike;
+    private readonly executable?: string;
+
+    constructor(options: ClaudePrintAgentServiceOptions = {}) {
+        this.store = options.store ?? new PrintAgentStore();
+        this.probe = options.probe ?? new ClaudeCliProbe();
+        this.runner = options.runner ?? new ClaudePrintRunner();
+        this.executable = options.executable;
+    }
+
+    async create(input: CreatePrintAgentInput): Promise<PrintAgent> {
+        await this.probe.validate();
+        return this.store.create(input);
+    }
+
+    async send(reference: string, prompt: string): Promise<ClaudePrintSendResult> {
+        const resolved = await this.store.resolve(reference);
+        if (!resolved) throw new PrintAgentNotFoundError(reference);
+        if (Array.isArray(resolved)) {
+            throw new ClaudePrintError(`Multiple print agents match "${reference}".`, 'PRINT_AGENT_AMBIGUOUS');
+        }
+        const acquired = await this.store.acquireRun(resolved.id);
+        try {
+            const result = await this.runner.run({
+                agent: acquired.agent,
+                prompt,
+                executable: this.executable,
+                firstRun: acquired.agent.sessionHealth === 'uninitialized',
+                onSpawn: (identity) => this.store.recordProviderProcess(resolved.id, acquired.token, identity),
+            });
+            await this.store.completeRun(resolved.id, acquired.token, {
+                status: 'succeeded',
+                exitCode: result.exitCode,
+                summary: sanitize(result.result, 4096),
+                sessionHealth: 'healthy',
+            });
+            return { ...result, agentId: resolved.id, agentName: resolved.name };
+        } catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            const sessionHealth = error instanceof ClaudePrintError && error.code === 'CLAUDE_SESSION_MISMATCH'
+                ? 'mismatch' as const
+                : 'unknown' as const;
+            await this.store.completeRun(resolved.id, acquired.token, {
+                status: 'failed',
+                exitCode: null,
+                summary: sanitize(failure.message, 4096),
+                sessionHealth,
+            });
+            throw error;
+        }
+    }
+}
+
+function sanitize(value: string, max: number): string {
+    return Array.from(value, (character) => {
+        const code = character.charCodeAt(0);
+        return (code <= 8 || code === 11 || code === 12 || (code >= 14 && code <= 31) || code === 127)
+            ? ' '
+            : character;
+    }).join('').trim().slice(0, max);
+}

package/src/print/ClaudePrintRunner.ts

@@ -0,0 +1,139 @@
+import { spawn as nodeSpawn, type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from 'child_process';
+import type { PrintAgent, ProcessIdentity } from './PrintAgent.js';
+import { ClaudePrintError } from './PrintAgent.js';
+import { LocalProcessInspector, type ProcessInspector } from './PrintAgentStore.js';
+
+type Spawn = (
+    command: string,
+    args: readonly string[],
+    options: SpawnOptionsWithoutStdio & { stdio: ['pipe', 'pipe', 'pipe'] },
+) => ChildProcessWithoutNullStreams;
+
+export interface ClaudePrintRunRequest {
+    agent: PrintAgent;
+    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');
+        }
+
+        let buffer = Buffer.alloc(0);
+        let terminal: ClaudePrintRunResult | null = null;
+        let protocolError: ClaudePrintError | null = null;
+
+        child.stdout.on('data', (chunk: Buffer | string) => {
+            if (protocolError) return;
+            buffer = Buffer.concat([buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+            if (buffer.length > this.maxLineBytes && buffer.indexOf(0x0a) < 0) {
+                protocolError = new ClaudePrintError('Claude stream line exceeded the safety limit.', 'CLAUDE_STREAM_OVERSIZED');
+                return;
+            }
+            let newline: number;
+            while ((newline = buffer.indexOf(0x0a)) >= 0) {
+                const line = buffer.subarray(0, newline);
+                buffer = buffer.subarray(newline + 1);
+                if (line.length === 0) continue;
+                if (line.length > this.maxLineBytes) {
+                    protocolError = new ClaudePrintError('Claude stream line exceeded the safety limit.', 'CLAUDE_STREAM_OVERSIZED');
+                    return;
+                }
+                try {
+                    const value = JSON.parse(line.toString('utf8')) as unknown;
+                    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+                        throw new ClaudePrintError('Claude emitted a non-object stream message.', 'CLAUDE_STREAM_INVALID');
+                    }
+                    const event = value as Record<string, unknown>;
+                    if (typeof event.session_id === 'string' && event.session_id !== request.agent.providerSessionId) {
+                        throw new ClaudePrintError('Claude returned a different session identity.', 'CLAUDE_SESSION_MISMATCH');
+                    }
+                    if (event.type === 'result') {
+                        if (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');
+                        }
+                        terminal = { sessionId: event.session_id, result: event.result, exitCode: 0 };
+                    }
+                } catch (error) {
+                    protocolError = error instanceof ClaudePrintError
+                        ? error
+                        : new ClaudePrintError('Claude emitted malformed stream JSON.', 'CLAUDE_STREAM_INVALID');
+                    return;
+                }
+            }
+        });
+        // Drain provider diagnostics without reflecting potentially sensitive prompt/tool data.
+        child.stderr.resume();
+
+        const closed = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
+            child.once('error', reject);
+            child.once('close', (code, signal) => resolve({ code, signal }));
+        });
+
+        try {
+            await request.onSpawn(identity);
+        } catch (error) {
+            child.kill();
+            throw error;
+        }
+
+        child.stdin.end(request.prompt);
+        const { code, signal } = await closed;
+
+        if (protocolError) throw protocolError;
+        if (buffer.length > 0) {
+            throw new ClaudePrintError('Claude stream ended with incomplete JSON.', 'CLAUDE_STREAM_INVALID');
+        }
+        if (code !== 0) {
+            throw new ClaudePrintError(
+                `Claude print run failed${signal ? ` (${signal})` : '.'}`,
+                'CLAUDE_PROCESS_FAILED',
+            );
+        }
+        if (!terminal) throw new ClaudePrintError('Claude stream ended without a terminal result.', 'CLAUDE_RESULT_MISSING');
+        const finalResult = terminal as ClaudePrintRunResult;
+        return { sessionId: finalResult.sessionId, result: finalResult.result, exitCode: code };
+    }
+}

package/src/print/PrintAgent.ts

@@ -0,0 +1,86 @@
+export type PrintAgentState = 'ready' | 'running' | 'degraded';
+export type PrintSessionHealth = 'uninitialized' | 'healthy' | 'unknown' | 'mismatch';
+export type PrintRunStatus = 'succeeded' | 'failed' | 'interrupted';
+
+export interface ProcessIdentity {
+    pid: number;
+    startedAt: string;
+}
+
+export interface PrintActiveRun {
+    token: string;
+    owner: ProcessIdentity;
+    provider: ProcessIdentity | null;
+    startedAt: string;
+}
+
+export interface PrintLastResult {
+    status: PrintRunStatus;
+    completedAt: string;
+    exitCode: number | null;
+    summary: string;
+}
+
+export interface PrintAgent {
+    id: string;
+    name: string;
+    provider: 'claude';
+    mode: 'print';
+    cwd: string;
+    providerSessionId: string;
+    state: PrintAgentState;
+    sessionHealth: PrintSessionHealth;
+    createdAt: string;
+    updatedAt: string;
+    lastActiveAt: string | null;
+    lastResult: PrintLastResult | null;
+    activeRun: PrintActiveRun | null;
+}
+
+export class PrintAgentError extends Error {
+    constructor(
+        message: string,
+        public readonly code: string,
+    ) {
+        super(message);
+        this.name = 'PrintAgentError';
+    }
+}
+
+export class PrintAgentBusyError extends PrintAgentError {
+    constructor(
+        public readonly agentId: string,
+        agentName: string,
+    ) {
+        super(`Print agent "${agentName}" is busy.`, 'PRINT_AGENT_BUSY');
+        this.name = 'PrintAgentBusyError';
+    }
+}
+
+export class PrintAgentNotFoundError extends PrintAgentError {
+    constructor(public readonly reference: string) {
+        super(`Print agent "${reference}" was not found.`, 'PRINT_AGENT_NOT_FOUND');
+        this.name = 'PrintAgentNotFoundError';
+    }
+}
+
+export class PrintAgentStoreError extends PrintAgentError {
+    constructor(message: string) {
+        super(message, 'PRINT_AGENT_STORE');
+        this.name = 'PrintAgentStoreError';
+    }
+}
+
+export class PrintAgentNameConflictError extends PrintAgentError {
+    constructor(public readonly agentName: string) {
+        super(`Print agent name "${agentName}" is already in use.`, 'PRINT_AGENT_NAME_CONFLICT');
+        this.name = 'PrintAgentNameConflictError';
+    }
+}
+
+export class ClaudePrintError extends PrintAgentError {
+    constructor(message: string, code = 'CLAUDE_PRINT_FAILED') {
+        super(message, code);
+        this.name = 'ClaudePrintError';
+    }
+}