@ai-devkit/agent-manager 0.26.4 → 0.28.0

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

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import Database from 'better-sqlite3';
 import { AgentRegistry, RenameNotFoundError, RenameConflictError, type RegistryEntry } from '../../utils/AgentRegistry.js';
 
 function makeEntry(over: Partial<RegistryEntry> = {}): RegistryEntry {
@@ -13,6 +14,7 @@ function makeEntry(over: Partial<RegistryEntry> = {}): RegistryEntry {
         startedAt: '2026-05-30T00:00:00.000Z',
         sessionId: 'sid-1',
         sessionFilePath: '/tmp/session.jsonl',
+        pinned: false,
         ...over,
     };
 }
@@ -172,6 +174,72 @@ describe('AgentRegistry', () => {
         });
     });
 
+    describe('pinning', () => {
+        it('defaults new rows to unpinned and toggles the persisted state', () => {
+            registry.register(makeEntry());
+
+            expect(registry.lookup('agent1')?.pinned).toBe(false);
+            expect(registry.togglePin('claude', process.pid)).toBe(true);
+            expect(registry.lookup('agent1')?.pinned).toBe(true);
+            expect(registry.togglePin('claude', process.pid)).toBe(false);
+            expect(registry.lookup('agent1')?.pinned).toBe(false);
+        });
+
+        it('updates existing recency when toggled', () => {
+            let now = new Date('2026-08-16T10:00:00.000Z');
+            const clocked = new AgentRegistry(regPath, { now: () => now });
+            clocked.register(makeEntry());
+            now = new Date('2026-08-16T10:01:00.000Z');
+
+            clocked.togglePin('claude', process.pid);
+
+            expect(clocked.lookup('agent1')?.updatedAt).toBe(now.toISOString());
+            const db = new Database(regPath.replace(/\.json$/, '.db'), { readonly: true });
+            const row = db.prepare('SELECT updated_at FROM agents WHERE type = ? AND pid = ?')
+                .get('claude', process.pid) as { updated_at: string };
+            db.close();
+            expect(row.updated_at).toBe(now.toISOString());
+        });
+
+        it('returns null when the process row has disappeared', () => {
+            expect(registry.togglePin('claude', 999999)).toBeNull();
+        });
+
+        it('preserves a pin when poll registration updates the row', () => {
+            registry.register(makeEntry({ sessionId: 'before' }));
+            registry.togglePin('claude', process.pid);
+
+            registry.register(makeEntry({ sessionId: 'after' }));
+
+            expect(registry.lookup('agent1')).toMatchObject({ sessionId: 'after', pinned: true });
+        });
+
+        it('preserves a pin through rename', () => {
+            registry.register(makeEntry({ name: 'before' }));
+            registry.togglePin('claude', process.pid);
+
+            registry.rename('before', 'after');
+
+            expect(registry.lookup('after')?.pinned).toBe(true);
+        });
+
+        it('removes the pin with a pruned process row', () => {
+            registry.register(makeEntry({ pid: 999999 }));
+            registry.togglePin('claude', 999999);
+
+            registry.prune();
+
+            expect(registry.lookup('agent1')).toBeNull();
+        });
+
+        it('reports a clear error when a readonly registry toggles a pin', () => {
+            registry.register(makeEntry());
+            const readonlyRegistry = new AgentRegistry(regPath, { readonly: true });
+
+            expect(() => readonlyRegistry.togglePin('claude', process.pid)).toThrow(/readonly/i);
+        });
+    });
+
     describe('list', () => {
         it('returns empty array when database does not contain entries', () => {
             expect(registry.list()).toEqual([]);

package/src/adapters/AgentAdapter.ts

@@ -48,6 +48,9 @@ export interface AgentInfo {
     /** Timestamp of last activity */
     lastActive: Date;
 
+    /** Whether the live process is pinned in the agent console */
+    pinned?: boolean;
+
     /** Path to the session JSONL file on disk */
     sessionFilePath?: string;
 }

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';
@@ -20,20 +20,33 @@ export function resolveAgentRegistryDbPath(filePath?: string): string {
 export class DatabaseConnection {
     private db: Database.Database;
     private readonly dbPath: string;
+    private readonly readonly: boolean;
 
     constructor(options: DatabaseOptions = {}) {
         this.dbPath = options.dbPath ?? DEFAULT_AGENT_REGISTRY_DB_PATH;
-        mkdirSync(dirname(this.dbPath), { recursive: true });
+        this.readonly = options.readonly ?? false;
+        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: options.readonly ?? false,
+            readonly: this.readonly,
             verbose: typeof options.verbose === 'function'
                 ? options.verbose
                 : options.verbose ? console.log : undefined,
         });
 
-        this.configure();
-        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 {

package/src/database/migrations/002_pins.sql

@@ -0,0 +1 @@
+ALTER TABLE agents ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0;

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';
+    }
+}