@ai-devkit/agent-manager 0.27.0 → 0.28.1

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

@@ -0,0 +1,163 @@
+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('DurableAgentRepository');
+    return api.DurableAgentRepository;
+}
+
+function fixture(): { root: string; cwd: string; dbPath: string } {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'durable-agent-store-'));
+    tempDirs.push(root);
+    const cwd = path.join(root, 'project');
+    fs.mkdirSync(cwd);
+    return { root, cwd, dbPath: path.join(root, 'state', 'agents.db') };
+}
+
+describe('DurableAgentRepository create/list/resolve', () => {
+    it('creates distinct durable identities with a canonical cwd and lists them', async () => {
+        const DurableAgentRepository = await loadStore();
+        const { cwd, dbPath } = fixture();
+        const repository = new DurableAgentRepository({ dbPath, now: () => new Date('2026-08-07T09:00:00Z') });
+
+        const agent = await repository.create({ name: 'reviewer', cwd });
+
+        expect(agent).toMatchObject({
+            name: 'reviewer',
+            provider: 'claude',
+            mode: 'durable',
+            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 repository.list()).toEqual([agent]);
+        expect(fs.existsSync(dbPath)).toBe(true);
+    });
+
+    it('resolves exact ids and names and rejects duplicate names', async () => {
+        const DurableAgentRepository = await loadStore();
+        const { cwd, dbPath } = fixture();
+        const repository = new DurableAgentRepository({ dbPath });
+        const agent = await repository.create({ name: 'Reviewer', cwd });
+
+        expect(await repository.resolve(agent.id)).toMatchObject({ id: agent.id });
+        expect(await repository.resolve('reviewer')).toMatchObject({ id: agent.id });
+        expect(await repository.resolve('view')).toBeNull();
+        await expect(repository.create({ name: 'reviewer', cwd })).rejects.toMatchObject({
+            code: 'DURABLE_AGENT_NAME_CONFLICT',
+        });
+    });
+
+    it('rejects a missing cwd', async () => {
+        const DurableAgentRepository = await loadStore();
+        const { root, dbPath } = fixture();
+        const repository = new DurableAgentRepository({ dbPath });
+
+        await expect(repository.create({ name: 'missing', cwd: path.join(root, 'missing') }))
+            .rejects.toMatchObject({ code: 'DURABLE_AGENT_REPOSITORY' });
+    });
+});
+
+describe('DurableAgentRepository run ownership', () => {
+    it('fails fast when another exact owner is live and completes only for its token', async () => {
+        const DurableAgentRepository = await loadStore();
+        const { cwd, dbPath } = 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 repository = new DurableAgentRepository({ dbPath, processInspector });
+        const agent = await repository.create({ name: 'runner', cwd });
+
+        const acquired = await repository.acquireRun(agent.id);
+        await expect(repository.acquireRun(agent.id)).rejects.toMatchObject({ code: 'DURABLE_AGENT_BUSY' });
+        await expect(repository.completeRun(agent.id, 'wrong-token', {
+            status: 'succeeded', exitCode: 0, summary: 'done', sessionHealth: 'healthy',
+        })).rejects.toMatchObject({ code: 'DURABLE_AGENT_REPOSITORY' });
+
+        const completed = await repository.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 DurableAgentRepository = await loadStore();
+        const { cwd, dbPath } = 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 DurableAgentRepository({ dbPath, 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: 'DURABLE_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 interrupted run to degraded during list', async () => {
+        const DurableAgentRepository = await loadStore();
+        const { cwd, dbPath } = fixture();
+        const live = new Map<number, string>([[process.pid, 'owner-start']]);
+        const repository = new DurableAgentRepository({ dbPath, incompleteLockGraceMs: 10, processInspector: {
+            getIdentity: (pid: number) => {
+                const startedAt = live.get(pid);
+                return startedAt ? { pid, startedAt } : null;
+            },
+        } });
+        const agent = await repository.create({ name: 'crashed', cwd });
+        await repository.acquireRun(agent.id);
+        live.clear();
+
+        const listed = await repository.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 DurableAgentRepository = await loadStore();
+        const { root, cwd, dbPath } = fixture();
+        const repository = new DurableAgentRepository({ dbPath });
+        const agent = await repository.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(repository.acquireRun(agent.id)).rejects.toMatchObject({ code: 'DURABLE_AGENT_REPOSITORY' });
+    });
+});

package/src/adapters/CodexAdapter.ts

@@ -119,11 +119,11 @@ export class CodexAdapter implements AgentAdapter {
         const processes = relevant.filter((process) => this.canHandle(process));
         if (processes.length === 0) return [];
 
-        const { cachedAgents, remaining } = this.tryRegistryCache(processes);
-        if (remaining.length === 0) return cachedAgents;
+        const mappingResult = this.mapSessionMappingMatches(processes);
+        const { cachedAgents, remaining } = this.tryRegistryCache(mappingResult.fallback);
+        if (remaining.length === 0) return [...mappingResult.agents, ...cachedAgents];
 
-        const mappingResult = this.mapSessionMappingMatches(remaining);
-        const { direct, fallback } = this.tryResumeMatching(mappingResult.fallback);
+        const { direct, fallback } = this.tryResumeMatching(remaining);
         const directResult = this.mapDirectMatches(direct);
         const { sessions, contentCache } = this.discoverSessions(fallback);
         if (sessions.length === 0) {
@@ -887,13 +887,12 @@ export class CodexAdapter implements AgentAdapter {
             const ts = this.parseTimestamp(entry.timestamp);
             if (ts) lastTimestamp = ts;
 
-            if (
-                !firstUserMessage &&
-                entry.payload?.type === 'user_message' &&
-                typeof entry.payload.message === 'string' &&
-                entry.payload.message.trim().length > 0
-            ) {
-                firstUserMessage = entry.payload.message.trim();
+            if (!firstUserMessage) {
+                const message = this.toConversationMessage(entry, false);
+                const content = message?.content.trim() ?? '';
+                if (message?.role === 'user' && content.length > 0 && !this.isSyntheticUserMessage(content)) {
+                    firstUserMessage = content;
+                }
             }
         }
 
@@ -917,4 +916,8 @@ export class CodexAdapter implements AgentAdapter {
             sessionFilePath: filePath,
         };
     }
+
+    private isSyntheticUserMessage(content: string): boolean {
+        return content.startsWith('<environment_context>') && content.includes('</environment_context>');
+    }
 }

package/src/database/connection.ts

@@ -1,5 +1,5 @@
 import Database from 'better-sqlite3';
-import { mkdirSync } from 'fs';
+import { existsSync, mkdirSync } from 'fs';
 import { dirname, join } from 'path';
 import { homedir } from 'os';
 import { initializeSchema } from './schema.js';
@@ -25,7 +25,10 @@ export class DatabaseConnection {
     constructor(options: DatabaseOptions = {}) {
         this.dbPath = options.dbPath ?? DEFAULT_AGENT_REGISTRY_DB_PATH;
         this.readonly = options.readonly ?? false;
-        mkdirSync(dirname(this.dbPath), { recursive: true });
+        if (this.readonly && !existsSync(this.dbPath)) {
+            throw new Error(`Cannot open readonly agent database because it does not exist: ${this.dbPath}`);
+        }
+        if (!this.readonly) mkdirSync(dirname(this.dbPath), { recursive: true });
 
         this.db = new Database(this.dbPath, {
             readonly: this.readonly,
@@ -34,16 +37,19 @@ export class DatabaseConnection {
                 : options.verbose ? console.log : undefined,
         });
 
-        this.configure();
-        if (!this.readonly) initializeSchema(this);
+        if (this.readonly) {
+            const version = this.db.pragma('user_version', { simple: true }) as number;
+            if (version < 3) {
+                this.db.close();
+                throw new Error(`Readonly agent database requires schema version 3 (found ${version}).`);
+            }
+        } else {
+            this.configure();
+            initializeSchema(this);
+        }
     }
 
     private configure(): void {
-        if (this.readonly) {
-            this.db.pragma('foreign_keys = ON');
-            this.db.pragma('busy_timeout = 5000');
-            return;
-        }
         this.db.pragma('journal_mode = WAL');
         this.db.pragma('foreign_keys = ON');
         this.db.pragma('synchronous = NORMAL');

package/src/database/migrations/003_durable_agents.sql

@@ -0,0 +1,43 @@
+CREATE TABLE durable_agents (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL COLLATE NOCASE UNIQUE,
+    provider TEXT NOT NULL,
+    mode TEXT NOT NULL DEFAULT 'durable',
+    cwd TEXT NOT NULL,
+    provider_session_id TEXT NOT NULL UNIQUE,
+    state TEXT NOT NULL CHECK (state IN ('ready','running','degraded')),
+    session_health TEXT NOT NULL CHECK (session_health IN ('uninitialized','healthy','unknown','mismatch')),
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    last_active_at TEXT NULL,
+    last_result_status TEXT NULL CHECK (last_result_status IS NULL OR last_result_status IN ('succeeded','failed','interrupted')),
+    last_result_completed_at TEXT NULL,
+    last_result_exit_code INTEGER NULL,
+    last_result_summary TEXT NULL,
+    active_run_token TEXT UNIQUE,
+    active_owner_pid INTEGER NULL,
+    active_owner_started_at TEXT NULL,
+    active_provider_pid INTEGER NULL,
+    active_provider_started_at TEXT NULL,
+    active_run_started_at TEXT NULL,
+    CHECK (
+        (state = 'running'
+            AND active_run_token IS NOT NULL
+            AND active_owner_pid IS NOT NULL
+            AND active_owner_started_at IS NOT NULL
+            AND active_run_started_at IS NOT NULL)
+        OR
+        (state <> 'running'
+            AND active_run_token IS NULL
+            AND active_owner_pid IS NULL
+            AND active_owner_started_at IS NULL
+            AND active_provider_pid IS NULL
+            AND active_provider_started_at IS NULL
+            AND active_run_started_at IS NULL)
+    ),
+    CHECK ((active_provider_pid IS NULL) = (active_provider_started_at IS NULL)),
+    CHECK ((last_result_status IS NULL) = (last_result_completed_at IS NULL))
+);
+
+CREATE INDEX idx_durable_agents_state ON durable_agents(state);
+CREATE INDEX idx_durable_agents_list ON durable_agents(updated_at DESC, name COLLATE NOCASE);

package/src/{print → durable}/ClaudeCliProbe.ts

@@ -1,6 +1,6 @@
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { ClaudePrintError } from './PrintAgent.js';
+import { ClaudePrintError } from './DurableAgent.js';
 
 type ExecResult = { stdout: string; stderr: string };
 type Exec = (file: string, args: string[]) => Promise<ExecResult>;

package/src/{print → durable}/ClaudePrintAgentService.ts

@@ -1,23 +1,23 @@
-import type { PrintAgent, ProcessIdentity } from './PrintAgent.js';
-import { ClaudePrintError, PrintAgentNotFoundError } from './PrintAgent.js';
+import type { DurableAgent, ProcessIdentity } from './DurableAgent.js';
+import { ClaudePrintError, DurableAgentNotFoundError } from './DurableAgent.js';
 import { ClaudeCliProbe } from './ClaudeCliProbe.js';
 import { ClaudePrintRunner, type ClaudePrintRunResult } from './ClaudePrintRunner.js';
-import { PrintAgentStore, type CreatePrintAgentInput, type PrintRunCompletion } from './PrintAgentStore.js';
+import { DurableAgentRepository, type CreateDurableAgentInput, type DurableRunCompletion } from './DurableAgentRepository.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 }>;
+interface RepositoryLike {
+    create(input: CreateDurableAgentInput): Promise<DurableAgent>;
+    list(): Promise<DurableAgent[]>;
+    resolve(reference: string): Promise<DurableAgent | DurableAgent[] | null>;
+    acquireRun(id: string): Promise<{ agent: DurableAgent; token: string }>;
     recordProviderProcess(id: string, token: string, identity: ProcessIdentity): Promise<void>;
-    completeRun(id: string, token: string, result: PrintRunCompletion): Promise<PrintAgent>;
+    completeRun(id: string, token: string, result: DurableRunCompletion): Promise<DurableAgent>;
 }
 
 interface ProbeLike { validate(): Promise<{ executable: string; version: string }> }
 interface RunnerLike { run(request: Parameters<ClaudePrintRunner['run']>[0]): Promise<ClaudePrintRunResult> }
 
 export interface ClaudePrintAgentServiceOptions {
-    store?: StoreLike;
+    repository?: RepositoryLike;
     probe?: ProbeLike;
     runner?: RunnerLike;
     executable?: string;
@@ -29,39 +29,39 @@ export interface ClaudePrintSendResult extends ClaudePrintRunResult {
 }
 
 export class ClaudePrintAgentService {
-    readonly store: StoreLike;
+    readonly repository: RepositoryLike;
     private readonly probe: ProbeLike;
     private readonly runner: RunnerLike;
     private readonly executable?: string;
 
     constructor(options: ClaudePrintAgentServiceOptions = {}) {
-        this.store = options.store ?? new PrintAgentStore();
+        this.repository = options.repository ?? new DurableAgentRepository();
         this.probe = options.probe ?? new ClaudeCliProbe();
         this.runner = options.runner ?? new ClaudePrintRunner();
         this.executable = options.executable;
     }
 
-    async create(input: CreatePrintAgentInput): Promise<PrintAgent> {
+    async create(input: CreateDurableAgentInput): Promise<DurableAgent> {
         await this.probe.validate();
-        return this.store.create(input);
+        return this.repository.create(input);
     }
 
     async send(reference: string, prompt: string): Promise<ClaudePrintSendResult> {
-        const resolved = await this.store.resolve(reference);
-        if (!resolved) throw new PrintAgentNotFoundError(reference);
+        const resolved = await this.repository.resolve(reference);
+        if (!resolved) throw new DurableAgentNotFoundError(reference);
         if (Array.isArray(resolved)) {
-            throw new ClaudePrintError(`Multiple print agents match "${reference}".`, 'PRINT_AGENT_AMBIGUOUS');
+            throw new ClaudePrintError(`Multiple durable agents match "${reference}".`, 'DURABLE_AGENT_AMBIGUOUS');
         }
-        const acquired = await this.store.acquireRun(resolved.id);
+        const acquired = await this.repository.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),
+                onSpawn: (identity) => this.repository.recordProviderProcess(resolved.id, acquired.token, identity),
             });
-            await this.store.completeRun(resolved.id, acquired.token, {
+            await this.repository.completeRun(resolved.id, acquired.token, {
                 status: 'succeeded',
                 exitCode: result.exitCode,
                 summary: sanitize(result.result, 4096),
@@ -73,7 +73,7 @@ export class ClaudePrintAgentService {
             const sessionHealth = error instanceof ClaudePrintError && error.code === 'CLAUDE_SESSION_MISMATCH'
                 ? 'mismatch' as const
                 : 'unknown' as const;
-            await this.store.completeRun(resolved.id, acquired.token, {
+            await this.repository.completeRun(resolved.id, acquired.token, {
                 status: 'failed',
                 exitCode: null,
                 summary: sanitize(failure.message, 4096),

package/src/{print → durable}/ClaudePrintRunner.ts

@@ -1,7 +1,7 @@
 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';
+import type { DurableAgent, ProcessIdentity } from './DurableAgent.js';
+import { ClaudePrintError } from './DurableAgent.js';
+import { LocalProcessInspector, type ProcessInspector } from './DurableAgentRepository.js';
 
 type Spawn = (
     command: string,
@@ -10,7 +10,7 @@ type Spawn = (
 ) => ChildProcessWithoutNullStreams;
 
 export interface ClaudePrintRunRequest {
-    agent: PrintAgent;
+    agent: DurableAgent;
     prompt: string;
     executable?: string;
     firstRun: boolean;

package/src/durable/DurableAgent.ts

@@ -0,0 +1,91 @@
+export type DurableAgentState = 'ready' | 'running' | 'degraded';
+export type DurableSessionHealth = 'uninitialized' | 'healthy' | 'unknown' | 'mismatch';
+export type DurableRunStatus = 'succeeded' | 'failed' | 'interrupted';
+
+export const AGENT_MODES = {
+    INTERACTIVE: 'interactive',
+    DURABLE: 'durable',
+} as const;
+
+export interface ProcessIdentity {
+    pid: number;
+    startedAt: string;
+}
+
+export interface DurableActiveRun {
+    token: string;
+    owner: ProcessIdentity;
+    provider: ProcessIdentity | null;
+    startedAt: string;
+}
+
+export interface DurableLastResult {
+    status: DurableRunStatus;
+    completedAt: string;
+    exitCode: number | null;
+    summary: string;
+}
+
+export interface DurableAgent {
+    id: string;
+    name: string;
+    provider: 'claude';
+    mode: typeof AGENT_MODES.DURABLE;
+    cwd: string;
+    providerSessionId: string;
+    state: DurableAgentState;
+    sessionHealth: DurableSessionHealth;
+    createdAt: string;
+    updatedAt: string;
+    lastActiveAt: string | null;
+    lastResult: DurableLastResult | null;
+    activeRun: DurableActiveRun | null;
+}
+
+export class DurableAgentError extends Error {
+    constructor(
+        message: string,
+        public readonly code: string,
+    ) {
+        super(message);
+        this.name = 'DurableAgentError';
+    }
+}
+
+export class DurableAgentBusyError extends DurableAgentError {
+    constructor(
+        public readonly agentId: string,
+        agentName: string,
+    ) {
+        super(`Durable agent "${agentName}" is busy.`, 'DURABLE_AGENT_BUSY');
+        this.name = 'DurableAgentBusyError';
+    }
+}
+
+export class DurableAgentNotFoundError extends DurableAgentError {
+    constructor(public readonly reference: string) {
+        super(`Durable agent "${reference}" was not found.`, 'DURABLE_AGENT_NOT_FOUND');
+        this.name = 'DurableAgentNotFoundError';
+    }
+}
+
+export class DurableAgentRepositoryError extends DurableAgentError {
+    constructor(message: string) {
+        super(message, 'DURABLE_AGENT_REPOSITORY');
+        this.name = 'DurableAgentRepositoryError';
+    }
+}
+
+export class DurableAgentNameConflictError extends DurableAgentError {
+    constructor(public readonly agentName: string) {
+        super(`Durable agent name "${agentName}" is already in use.`, 'DURABLE_AGENT_NAME_CONFLICT');
+        this.name = 'DurableAgentNameConflictError';
+    }
+}
+
+export class ClaudePrintError extends DurableAgentError {
+    constructor(message: string, code = 'CLAUDE_PRINT_FAILED') {
+        super(message, code);
+        this.name = 'ClaudePrintError';
+    }
+}