@ai-devkit/agent-manager 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-devkit/agent-manager",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "type": "module",
   "description": "Standalone agent detection and management utilities for AI DevKit",
   "main": "dist/index.js",

package/src/__tests__/fixtures/fake-claude.cjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+
+const args = process.argv.slice(2);
+if (args[0] === '--version') {
+  process.stdout.write('fake-claude 2.1.220\n');
+  process.exit(0);
+}
+if (args[0] === '--help') {
+  process.stdout.write('--print -p --session-id --resume --output-format stream-json --verbose\n');
+  process.exit(0);
+}
+
+let prompt = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { prompt += chunk; });
+process.stdin.on('end', () => {
+  const flag = args.includes('--session-id') ? '--session-id' : '--resume';
+  const sessionId = args[args.indexOf(flag) + 1];
+  const capture = process.env.AI_DEVKIT_FAKE_CLAUDE_CAPTURE;
+  if (capture) fs.appendFileSync(capture, `${JSON.stringify({ args, prompt, cwd: process.cwd() })}\n`);
+  process.stdout.write(`${JSON.stringify({ type: 'system', subtype: 'init', session_id: sessionId })}\n`);
+  process.stdout.write(`${JSON.stringify({ type: 'result', session_id: sessionId, result: `answer:${prompt}` })}\n`);
+});

package/src/__tests__/print/ClaudeCliProbe.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it, vi } from 'vitest';
+
+describe('ClaudeCliProbe', () => {
+    it('validates only version/help and requires the print session flags', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        expect(api).toHaveProperty('ClaudeCliProbe');
+        const exec = vi.fn()
+            .mockResolvedValueOnce({ stdout: '2.1.220\n', stderr: '' })
+            .mockResolvedValueOnce({
+                stdout: '--print --session-id --resume --output-format stream-json', stderr: '',
+            });
+        const Probe = api.ClaudeCliProbe as new (options: unknown) => { validate(): Promise<unknown> };
+
+        await expect(new Probe({ exec }).validate()).resolves.toEqual({
+            executable: 'claude', version: '2.1.220',
+        });
+        expect(exec.mock.calls).toEqual([
+            ['claude', ['--version']],
+            ['claude', ['--help']],
+        ]);
+    });
+
+    it('rejects a CLI missing a required capability', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const exec = vi.fn()
+            .mockResolvedValueOnce({ stdout: 'old', stderr: '' })
+            .mockResolvedValueOnce({ stdout: '--print only', stderr: '' });
+        const Probe = api.ClaudeCliProbe as new (options: unknown) => { validate(): Promise<unknown> };
+
+        await expect(new Probe({ exec }).validate()).rejects.toMatchObject({ code: 'CLAUDE_CLI_UNSUPPORTED' });
+    });
+});

package/src/__tests__/print/ClaudePrintAgent.integration.test.ts

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+    ClaudeCliProbe,
+    ClaudePrintAgentService,
+    ClaudePrintRunner,
+    PrintAgentStore,
+} from '../../index.js';
+
+const roots: string[] = [];
+const originalCapture = process.env.AI_DEVKIT_FAKE_CLAUDE_CAPTURE;
+
+afterEach(() => {
+    if (originalCapture === undefined) delete process.env.AI_DEVKIT_FAKE_CLAUDE_CAPTURE;
+    else process.env.AI_DEVKIT_FAKE_CLAUDE_CAPTURE = originalCapture;
+    for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('Claude print-agent fake-provider journey', () => {
+    it('creates without invocation, then starts and resumes the same session through stdin', async () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'print-agent-integration-'));
+        roots.push(root);
+        const cwd = path.join(root, 'project');
+        fs.mkdirSync(cwd);
+        const capture = path.join(root, 'capture.jsonl');
+        process.env.AI_DEVKIT_FAKE_CLAUDE_CAPTURE = capture;
+        const executable = fileURLToPath(new URL('../fixtures/fake-claude.cjs', import.meta.url));
+        const store = new PrintAgentStore({ filePath: path.join(root, 'state', 'print-agents.json') });
+        const service = new ClaudePrintAgentService({
+            store,
+            probe: new ClaudeCliProbe({ executable }),
+            runner: new ClaudePrintRunner(),
+            executable,
+        });
+
+        const created = await service.create({ name: 'reviewer', cwd });
+        expect(fs.existsSync(capture)).toBe(false);
+
+        await expect(service.send(created.id, 'first secret')).resolves.toMatchObject({ result: 'answer:first secret' });
+        await expect(service.send(created.id, 'follow up')).resolves.toMatchObject({ result: 'answer:follow up' });
+
+        const invocations = fs.readFileSync(capture, 'utf8').trim().split('\n').map((line) => JSON.parse(line));
+        expect(invocations[0]).toMatchObject({ prompt: 'first secret', cwd: fs.realpathSync(cwd) });
+        expect(invocations[0].args).toContain('--session-id');
+        expect(invocations[0].args).not.toContain('first secret');
+        expect(invocations[1]).toMatchObject({ prompt: 'follow up', cwd: fs.realpathSync(cwd) });
+        expect(invocations[1].args).toContain('--resume');
+        expect(invocations[1].args[invocations[1].args.indexOf('--resume') + 1]).toBe(created.providerSessionId);
+
+        const persisted = await store.getById(created.id);
+        expect(persisted).toMatchObject({ state: 'ready', sessionHealth: 'healthy' });
+    });
+});

package/src/__tests__/print/ClaudePrintAgentService.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from 'vitest';
+
+describe('ClaudePrintAgentService', () => {
+    it('validates before create and does not run Claude', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        expect(api).toHaveProperty('ClaudePrintAgentService');
+        const probe = { validate: vi.fn().mockResolvedValue({ executable: 'claude', version: '2.1.220' }) };
+        const store = { create: vi.fn().mockResolvedValue({ id: 'agent-id', name: 'reviewer' }) };
+        const runner = { run: vi.fn() };
+        const Service = api.ClaudePrintAgentService as new (options: unknown) => any;
+
+        await expect(new Service({ store, probe, runner }).create({ name: 'reviewer', cwd: '/project' }))
+            .resolves.toMatchObject({ id: 'agent-id' });
+        expect(probe.validate).toHaveBeenCalledOnce();
+        expect(store.create).toHaveBeenCalledWith({ name: 'reviewer', cwd: '/project' });
+        expect(runner.run).not.toHaveBeenCalled();
+    });
+
+    it('runs first and resumed sends and records provider identity/results', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const base = { id: 'id', name: 'reviewer', providerSessionId: 'session', sessionHealth: 'uninitialized' };
+        const store = {
+            resolve: vi.fn().mockResolvedValue(base),
+            acquireRun: vi.fn()
+                .mockResolvedValueOnce({ agent: base, token: 'one' })
+                .mockResolvedValueOnce({ agent: { ...base, sessionHealth: 'healthy' }, token: 'two' }),
+            recordProviderProcess: vi.fn(), completeRun: vi.fn().mockResolvedValue({}),
+        };
+        const runner = { run: vi.fn().mockImplementation(async (request) => {
+            await request.onSpawn({ pid: 42, startedAt: 'start' });
+            return { sessionId: 'session', result: 'answer', exitCode: 0 };
+        }) };
+        const Service = api.ClaudePrintAgentService as new (options: unknown) => any;
+        const service = new Service({ store, probe: { validate: vi.fn() }, runner, executable: 'fake-claude' });
+
+        await service.send('reviewer', 'first');
+        await service.send('id', 'later');
+
+        expect(runner.run.mock.calls[0][0]).toMatchObject({ prompt: 'first', firstRun: true, executable: 'fake-claude' });
+        expect(runner.run.mock.calls[1][0]).toMatchObject({ prompt: 'later', firstRun: false, executable: 'fake-claude' });
+        expect(store.recordProviderProcess).toHaveBeenCalledWith('id', 'one', { pid: 42, startedAt: 'start' });
+        expect(store.completeRun).toHaveBeenCalledWith('id', 'one', expect.objectContaining({
+            status: 'succeeded', exitCode: 0, sessionHealth: 'healthy',
+        }));
+    });
+});

package/src/__tests__/print/ClaudePrintRunner.test.ts

@@ -0,0 +1,105 @@
+import { EventEmitter } from 'node:events';
+import { PassThrough, Writable } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import type { PrintAgent } from '../../index.js';
+
+function agent(): PrintAgent {
+    return {
+        id: '11111111-1111-4111-8111-111111111111', name: 'reviewer', provider: 'claude', mode: 'print',
+        cwd: '/project', providerSessionId: '22222222-2222-4222-8222-222222222222', state: 'running',
+        sessionHealth: 'uninitialized', createdAt: '', updatedAt: '', lastActiveAt: null, lastResult: null,
+        activeRun: null,
+    };
+}
+
+function fakeSpawn(events: object[], exitCode = 0) {
+    const calls: unknown[][] = [];
+    const promptChunks: Buffer[] = [];
+    const child = new EventEmitter() as any;
+    child.pid = 4242;
+    child.stdout = new PassThrough();
+    child.stderr = new PassThrough();
+    child.stdin = new Writable({
+        write(chunk, _encoding, callback) { promptChunks.push(Buffer.from(chunk)); callback(); },
+        final(callback) {
+            for (const event of events) child.stdout.write(`${JSON.stringify(event)}\n`);
+            child.stdout.end();
+            queueMicrotask(() => child.emit('close', exitCode, null));
+            callback();
+        },
+    });
+    const spawn = vi.fn((...args: unknown[]) => { calls.push(args); return child; });
+    return { spawn, calls, promptChunks };
+}
+
+describe('ClaudePrintRunner', () => {
+    it('starts a caller-assigned session and persists provider identity before stdin', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        expect(api).toHaveProperty('ClaudePrintRunner');
+        const fixture = fakeSpawn([
+            { type: 'system', subtype: 'init', session_id: agent().providerSessionId },
+            { type: 'result', session_id: agent().providerSessionId, result: 'done' },
+        ]);
+        let persisted = false;
+        const Runner = api.ClaudePrintRunner as new (options: unknown) => any;
+        const runner = new Runner({ spawn: fixture.spawn, processInspector: {
+            getIdentity: () => ({ pid: 4242, startedAt: 'provider-start' }),
+        } });
+
+        const result = await runner.run({
+            agent: agent(), prompt: 'secret prompt', executable: 'claude-test', firstRun: true,
+            onSpawn: async () => { expect(fixture.promptChunks).toHaveLength(0); persisted = true; },
+        });
+
+        expect(persisted).toBe(true);
+        expect(fixture.calls[0]).toEqual([
+            'claude-test',
+            ['-p', '--session-id', agent().providerSessionId, '--output-format', 'stream-json', '--verbose'],
+            expect.objectContaining({ cwd: '/project', shell: false, stdio: ['pipe', 'pipe', 'pipe'] }),
+        ]);
+        expect(JSON.stringify(fixture.calls)).not.toContain('secret prompt');
+        expect(Buffer.concat(fixture.promptChunks).toString()).toBe('secret prompt');
+        expect(result).toEqual({ sessionId: agent().providerSessionId, result: 'done', exitCode: 0 });
+    });
+
+    it('uses exact resume and rejects a mismatched result session', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const fixture = fakeSpawn([{ type: 'result', session_id: 'wrong', result: 'nope' }]);
+        const Runner = api.ClaudePrintRunner as new (options: unknown) => any;
+        const runner = new Runner({ spawn: fixture.spawn, processInspector: {
+            getIdentity: () => ({ pid: 4242, startedAt: 'provider-start' }),
+        } });
+
+        await expect(runner.run({
+            agent: agent(), prompt: 'followup', executable: 'claude', firstRun: false, onSpawn: vi.fn(),
+        })).rejects.toMatchObject({ code: 'CLAUDE_SESSION_MISMATCH' });
+        expect(fixture.calls[0]![1]).toEqual([
+            '-p', '--resume', agent().providerSessionId, '--output-format', 'stream-json', '--verbose',
+        ]);
+    });
+
+    it('does not disclose provider stderr in a failed-run error', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const fixture = fakeSpawn([], 1);
+        const Runner = api.ClaudePrintRunner as new (options: unknown) => any;
+        const runner = new Runner({ spawn: fixture.spawn, processInspector: {
+            getIdentity: () => ({ pid: 4242, startedAt: 'provider-start' }),
+        } });
+        fixture.spawn.mockImplementationOnce((...args: unknown[]) => {
+            const child = (fakeSpawn([], 1).spawn as any)(...args);
+            child.stdin = new Writable({
+                final(callback) {
+                    child.stderr.write('secret prompt echoed by provider');
+                    child.stderr.end();
+                    queueMicrotask(() => child.emit('close', 1, null));
+                    callback();
+                },
+            });
+            return child;
+        });
+
+        await expect(runner.run({
+            agent: agent(), prompt: 'secret prompt', firstRun: true, onSpawn: vi.fn(),
+        })).rejects.not.toThrow(/secret prompt/);
+    });
+});

package/src/__tests__/print/PrintAgent.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+describe('print-agent public domain', () => {
+    it('exports a classified busy error without exposing prompt data', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+
+        expect(api).toHaveProperty('PrintAgentBusyError');
+        const ErrorType = api.PrintAgentBusyError as new (agentId: string, name: string) => Error & {
+            code: string;
+            agentId: string;
+        };
+        const error = new ErrorType('agent-id', 'reviewer');
+
+        expect(error).toMatchObject({
+            name: 'PrintAgentBusyError',
+            code: 'PRINT_AGENT_BUSY',
+            agentId: 'agent-id',
+            message: 'Print agent "reviewer" is busy.',
+        });
+    });
+});

package/src/__tests__/print/PrintAgentStore.test.ts

@@ -0,0 +1,192 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+async function loadStore(): Promise<any> {
+    const api = await import('../../index.js') as Record<string, unknown>;
+    expect(api).toHaveProperty('PrintAgentStore');
+    return api.PrintAgentStore;
+}
+
+function fixture(): { root: string; cwd: string; filePath: string } {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'print-agent-store-'));
+    tempDirs.push(root);
+    const cwd = path.join(root, 'project');
+    fs.mkdirSync(cwd);
+    return { root, cwd, filePath: path.join(root, 'state', 'print-agents.json') };
+}
+
+describe('PrintAgentStore create/list/resolve', () => {
+    it('creates distinct durable identities with a canonical cwd and lists them', async () => {
+        const PrintAgentStore = await loadStore();
+        const { cwd, filePath } = fixture();
+        const store = new PrintAgentStore({ filePath, now: () => new Date('2026-08-07T09:00:00Z') });
+
+        const agent = await store.create({ name: 'reviewer', cwd });
+
+        expect(agent).toMatchObject({
+            name: 'reviewer',
+            provider: 'claude',
+            mode: 'print',
+            cwd: fs.realpathSync(cwd),
+            state: 'ready',
+            sessionHealth: 'uninitialized',
+            activeRun: null,
+        });
+        expect(agent.id).toMatch(/^[0-9a-f-]{36}$/);
+        expect(agent.providerSessionId).toMatch(/^[0-9a-f-]{36}$/);
+        expect(agent.id).not.toBe(agent.providerSessionId);
+        expect(await store.list()).toEqual([agent]);
+        expect(fs.statSync(filePath).mode & 0o777).toBe(0o600);
+    });
+
+    it('resolves exact ids and names and rejects duplicate names', async () => {
+        const PrintAgentStore = await loadStore();
+        const { cwd, filePath } = fixture();
+        const store = new PrintAgentStore({ filePath });
+        const agent = await store.create({ name: 'Reviewer', cwd });
+
+        expect(await store.resolve(agent.id)).toMatchObject({ id: agent.id });
+        expect(await store.resolve('reviewer')).toMatchObject({ id: agent.id });
+        expect(await store.resolve('view')).toBeNull();
+        await expect(store.create({ name: 'reviewer', cwd })).rejects.toMatchObject({
+            code: 'PRINT_AGENT_NAME_CONFLICT',
+        });
+    });
+
+    it('rejects missing cwd, malformed storage, and symlinked store targets', async () => {
+        const PrintAgentStore = await loadStore();
+        const { root, cwd, filePath } = fixture();
+        const store = new PrintAgentStore({ filePath });
+
+        await expect(store.create({ name: 'missing', cwd: path.join(root, 'missing') }))
+            .rejects.toMatchObject({ code: 'PRINT_AGENT_STORE' });
+
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, '{bad json', { mode: 0o600 });
+        await expect(store.list()).rejects.toMatchObject({ code: 'PRINT_AGENT_STORE' });
+
+        fs.rmSync(filePath);
+        const target = path.join(root, 'target.json');
+        fs.writeFileSync(target, JSON.stringify({ version: 1, agents: [] }));
+        fs.symlinkSync(target, filePath);
+        await expect(store.create({ name: 'unsafe', cwd })).rejects.toMatchObject({
+            code: 'PRINT_AGENT_STORE',
+        });
+    });
+
+    it('recovers an abandoned old mutation lock after a crash', async () => {
+        const PrintAgentStore = await loadStore();
+        const { cwd, filePath } = fixture();
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        const lockPath = `${filePath}.lock`;
+        fs.mkdirSync(lockPath);
+        const old = new Date(Date.now() - 60_000);
+        fs.utimesSync(lockPath, old, old);
+        const store = new PrintAgentStore({ filePath, mutationLockStaleMs: 10 });
+
+        await expect(store.create({ name: 'recovered', cwd })).resolves.toMatchObject({ name: 'recovered' });
+    });
+});
+
+describe('PrintAgentStore run ownership', () => {
+    it('fails fast when another exact owner is live and completes only for its token', async () => {
+        const PrintAgentStore = await loadStore();
+        const { cwd, filePath } = fixture();
+        const live = new Map<number, string>([[process.pid, 'owner-start']]);
+        const processInspector = { getIdentity: (pid: number) => {
+            const startedAt = live.get(pid);
+            return startedAt ? { pid, startedAt } : null;
+        } };
+        const store = new PrintAgentStore({ filePath, processInspector });
+        const agent = await store.create({ name: 'runner', cwd });
+
+        const acquired = await store.acquireRun(agent.id);
+        await expect(store.acquireRun(agent.id)).rejects.toMatchObject({ code: 'PRINT_AGENT_BUSY' });
+        await expect(store.completeRun(agent.id, 'wrong-token', {
+            status: 'succeeded', exitCode: 0, summary: 'done', sessionHealth: 'healthy',
+        })).rejects.toMatchObject({ code: 'PRINT_AGENT_STORE' });
+
+        const completed = await store.completeRun(agent.id, acquired.token, {
+            status: 'succeeded', exitCode: 0, summary: 'done', sessionHealth: 'healthy',
+        });
+        expect(completed).toMatchObject({ state: 'ready', sessionHealth: 'healthy', activeRun: null });
+    });
+
+    it('retains busy for a live provider then recovers a dead run without signaling it', async () => {
+        const PrintAgentStore = await loadStore();
+        const { cwd, filePath } = fixture();
+        const live = new Map<number, string>([[process.pid, 'owner-start'], [4242, 'provider-start']]);
+        const processInspector = { getIdentity: (pid: number) => {
+            const startedAt = live.get(pid);
+            return startedAt ? { pid, startedAt } : null;
+        } };
+        const first = new PrintAgentStore({ filePath, processInspector });
+        const agent = await first.create({ name: 'recoverable', cwd });
+        const run = await first.acquireRun(agent.id);
+        await first.recordProviderProcess(agent.id, run.token, { pid: 4242, startedAt: 'provider-start' });
+
+        live.delete(process.pid);
+        await expect(first.acquireRun(agent.id)).rejects.toMatchObject({ code: 'PRINT_AGENT_BUSY' });
+
+        live.delete(4242);
+        live.set(process.pid, 'replacement-owner-start');
+        const recovered = await first.acquireRun(agent.id);
+        expect(recovered.agent).toMatchObject({
+            state: 'running',
+            lastResult: { status: 'interrupted' },
+        });
+        await first.completeRun(agent.id, recovered.token, {
+            status: 'failed', exitCode: 1, summary: 'failed', sessionHealth: 'unknown',
+        });
+    });
+
+    it('reconciles an old incomplete lock to degraded during list', async () => {
+        const PrintAgentStore = await loadStore();
+        const { root, cwd, filePath } = fixture();
+        const live = new Map<number, string>([[process.pid, 'owner-start']]);
+        const store = new PrintAgentStore({ filePath, incompleteLockGraceMs: 10, processInspector: {
+            getIdentity: (pid: number) => {
+                const startedAt = live.get(pid);
+                return startedAt ? { pid, startedAt } : null;
+            },
+        } });
+        const agent = await store.create({ name: 'crashed', cwd });
+        await store.acquireRun(agent.id);
+        const lockPath = path.join(root, 'state', 'print-agent-locks', `${agent.id}.lock`);
+        fs.unlinkSync(path.join(lockPath, 'owner.json'));
+        const old = new Date(Date.now() - 1000);
+        fs.utimesSync(lockPath, old, old);
+        live.clear();
+
+        const listed = await store.list();
+
+        expect(listed[0]).toMatchObject({
+            state: 'degraded',
+            sessionHealth: 'unknown',
+            activeRun: null,
+            lastResult: { status: 'interrupted' },
+        });
+    });
+
+    it('rejects send acquisition when the bound cwd is replaced by a symlink', async () => {
+        const PrintAgentStore = await loadStore();
+        const { root, cwd, filePath } = fixture();
+        const store = new PrintAgentStore({ filePath });
+        const agent = await store.create({ name: 'bound', cwd });
+        const moved = path.join(root, 'moved-project');
+        const other = path.join(root, 'other-project');
+        fs.renameSync(cwd, moved);
+        fs.mkdirSync(other);
+        fs.symlinkSync(other, cwd);
+
+        await expect(store.acquireRun(agent.id)).rejects.toMatchObject({ code: 'PRINT_AGENT_STORE' });
+    });
+});

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/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);
+}