@ai-devkit/agent-manager 0.28.1 → 0.30.0

package/src/providers/claude/ClaudeCodeAdapter.ts

@@ -0,0 +1,160 @@
+import * as path from 'path';
+import type {
+    AgentAdapter,
+    AgentInfo,
+    ProcessInfo,
+    ConversationMessage,
+    SessionSummary,
+    ListSessionsOptions,
+    AgentDetectionContext,
+} from '../../adapters/AgentAdapter.js';
+import { captureProcessSnapshot, executableBasename, filterByProcessNames } from '../../utils/process.js';
+import { safeStat } from '../../utils/session.js';
+import { ClaudeSessionParser } from './ClaudeSessionParser.js';
+import { ClaudeAgentMapper } from './ClaudeAgentMapper.js';
+import { ClaudeSessionLocator } from './ClaudeSessionLocator.js';
+
+/**
+ * Claude Code Adapter
+ *
+ * Detects Claude Code agents by:
+ * 1. Filtering Claude processes from a shared asynchronous process snapshot
+ * 2. Using snapshot CWD and start-time enrichment
+ * 3. Attempting authoritative PID-file matching via ~/.claude/sessions/<pid>.json
+ * 4. Falling back to CWD+birthtime heuristic (matchProcessesToSessions) for processes without a PID file
+ * 5. Extracting summary from last user message in session JSONL
+ */
+export class ClaudeCodeAdapter implements AgentAdapter {
+    readonly type = 'claude' as const;
+    readonly processNames = ['claude'] as const;
+
+    private parser: ClaudeSessionParser;
+    private mapper: ClaudeAgentMapper;
+    private projectsDir: string;
+    private sessionsDir: string;
+
+    constructor() {
+        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+        this.projectsDir = path.join(homeDir, '.claude', 'projects');
+        this.sessionsDir = path.join(homeDir, '.claude', 'sessions');
+        this.parser = new ClaudeSessionParser();
+        this.mapper = new ClaudeAgentMapper(this.parser);
+    }
+
+    canHandle(processInfo: ProcessInfo): boolean {
+        return this.isClaudeExecutable(processInfo.command);
+    }
+
+    private isClaudeExecutable(command: string): boolean {
+        const base = executableBasename(command);
+        return base === 'claude' || base === 'claude.exe';
+    }
+
+    async detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+        const snapshot = context?.processes ?? await captureProcessSnapshot(this.processNames);
+        const relevant = filterByProcessNames(snapshot, this.processNames);
+        const processes = relevant.filter((process) => this.canHandle(process));
+        if (processes.length === 0) {
+            return [];
+        }
+
+        const { direct, legacyMatches } = this.createLocator().matchRunningProcesses(processes);
+
+        const matchedPids = new Set([
+            ...direct.map((d) => d.process.pid),
+            ...legacyMatches.map((m) => m.process.pid),
+        ]);
+
+        const agents: AgentInfo[] = [];
+
+        // Build agents from direct (resume + PID-file) matches
+        for (const match of direct) {
+            const { process: proc, sessionFile } = match;
+            const sessionData = this.parser.readSession(sessionFile.filePath, sessionFile.resolvedCwd);
+            if (sessionData) {
+                agents.push(this.mapper.mapSessionToAgent({
+                    session: sessionData,
+                    processInfo: proc,
+                    sessionFile,
+                    liveInfo: {
+                        pidStatus: match.pidStatus,
+                        waitingFor: match.waitingFor,
+                    },
+                }));
+            } else {
+                matchedPids.delete(proc.pid);
+            }
+        }
+
+        // Build agents from legacy matches
+        for (const match of legacyMatches) {
+            const sessionData = this.parser.readSession(
+                match.session.filePath,
+                match.session.resolvedCwd,
+            );
+            if (sessionData) {
+                agents.push(this.mapper.mapSessionToAgent({
+                    session: sessionData,
+                    processInfo: match.process,
+                    sessionFile: match.session,
+                }));
+            } else {
+                matchedPids.delete(match.process.pid);
+            }
+        }
+
+        // Any process with no match (direct or legacy) appears as IDLE
+        for (const proc of processes) {
+            if (!matchedPids.has(proc.pid)) {
+                agents.push(this.mapper.mapProcessOnlyAgent(proc));
+            }
+        }
+
+        return agents;
+    }
+
+    private createLocator(): ClaudeSessionLocator {
+        return new ClaudeSessionLocator({
+            projectsDir: this.projectsDir,
+            sessionsDir: this.sessionsDir,
+        });
+    }
+
+    getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+        return this.parser.getConversation(sessionFilePath, options);
+    }
+
+    async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+        const filterCwd = opts?.cwd;
+        const candidates = this.createLocator().discoverHistoricalSessionFiles();
+        const summaries: SessionSummary[] = [];
+
+        for (const { filePath, defaultCwd } of candidates) {
+            const session = this.parser.readSession(filePath, defaultCwd);
+            if (!session) continue;
+
+            // Drop sessions whose JSONL had no parseable conversation entries.
+            // readSession is permissive (returns a shell record even when every
+            // line fails to parse); listSessions needs at least one real entry
+            // so we don't surface garbage files.
+            if (!session.lastEntryType) continue;
+
+            const recordedCwd = session.lastCwd || defaultCwd;
+            if (filterCwd !== undefined && recordedCwd !== filterCwd) continue;
+
+            const stat = safeStat(filePath);
+
+            summaries.push({
+                type: 'claude',
+                sessionId: session.sessionId,
+                cwd: recordedCwd,
+                firstUserMessage: session.firstUserMessage || '',
+                lastActive: session.lastActive ?? stat?.mtime ?? new Date(),
+                startedAt: session.sessionStart ?? stat?.birthtime ?? stat?.mtime ?? new Date(),
+                sessionFilePath: filePath,
+            });
+        }
+
+        return summaries;
+    }
+}

package/src/{adapters/ClaudeCodeAdapter.ts → providers/claude/ClaudeSessionLocator.ts}

@@ -1,21 +1,16 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import type {
-    AgentAdapter,
-    AgentInfo,
-    ProcessInfo,
-    ConversationMessage,
-    SessionSummary,
-    ListSessionsOptions,
-    AgentDetectionContext,
-} from './AgentAdapter.js';
-import { AgentStatus } from './AgentAdapter.js';
-import { captureProcessSnapshot, executableBasename, filterByProcessNames } from '../utils/process.js';
-import { batchGetSessionFileBirthtimes, isDirectory, listJsonl, safeReaddir, safeStat } from '../utils/session.js';
-import type { SessionFile } from '../utils/session.js';
-import { matchProcessesToSessions, generateAgentName } from '../utils/matching.js';
-import { ClaudeSessionParser } from '../utils/ClaudeSessionParser.js';
-import type { ClaudeSession } from '../utils/ClaudeSessionParser.js';
+import type { ProcessInfo } from '../../adapters/AgentAdapter.js';
+import { AgentStatus } from '../../adapters/AgentAdapter.js';
+import { matchProcessesToSessions, type MatchResult } from '../../utils/matching.js';
+import {
+    batchGetSessionFileBirthtimes,
+    isDirectory,
+    listJsonl,
+    safeReaddir,
+    safeStat,
+    type SessionFile,
+} from '../../utils/session.js';
 
 /**
  * Entry in ~/.claude/sessions/<pid>.json written by Claude Code.
@@ -44,120 +39,113 @@ interface PidFileEntry {
  * A process directly matched to a session via PID file (authoritative path).
  *
  * When the matching PID file also exposes live status/waitingFor metadata,
- * those values are carried here so `mapSessionToAgent` can prefer them
- * over the JSONL-derived heuristic.
+ * those values are carried here so the agent mapper can prefer them over
+ * the JSONL-derived heuristic.
  */
-interface DirectMatch {
+export interface ClaudeDirectMatch {
     process: ProcessInfo;
     sessionFile: SessionFile;
     pidStatus?: AgentStatus;
     waitingFor?: string;
 }
 
+export interface ClaudeProcessSessionMatches {
+    direct: ClaudeDirectMatch[];
+    legacyMatches: MatchResult[];
+}
+
+export interface ClaudeSessionLocatorOptions {
+    projectsDir?: string;
+    sessionsDir?: string;
+}
+
 /** Maximum allowed delta (ms) between process start time and PID file startedAt. */
 const PID_FILE_STALENESS_MS = 60000;
 
-/**
- * Claude Code Adapter
- *
- * Detects Claude Code agents by:
- * 1. Filtering Claude processes from a shared asynchronous process snapshot
- * 2. Using snapshot CWD and start-time enrichment
- * 3. Attempting authoritative PID-file matching via ~/.claude/sessions/<pid>.json
- * 4. Falling back to CWD+birthtime heuristic (matchProcessesToSessions) for processes without a PID file
- * 5. Extracting summary from last user message in session JSONL
- */
-export class ClaudeCodeAdapter implements AgentAdapter {
-    readonly type = 'claude' as const;
-    readonly processNames = ['claude'] as const;
+export class ClaudeSessionLocator {
+    private readonly projectsDir: string;
+    private readonly sessionsDir: string;
 
-    private projectsDir: string;
-    private sessionsDir: string;
-    private parser: ClaudeSessionParser;
-
-    constructor() {
+    constructor(options: ClaudeSessionLocatorOptions = {}) {
         const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-        this.projectsDir = path.join(homeDir, '.claude', 'projects');
-        this.sessionsDir = path.join(homeDir, '.claude', 'sessions');
-        this.parser = new ClaudeSessionParser();
+        this.projectsDir = options.projectsDir ?? path.join(homeDir, '.claude', 'projects');
+        this.sessionsDir = options.sessionsDir ?? path.join(homeDir, '.claude', 'sessions');
     }
 
-    canHandle(processInfo: ProcessInfo): boolean {
-        return this.isClaudeExecutable(processInfo.command);
-    }
-
-    private isClaudeExecutable(command: string): boolean {
-        const base = executableBasename(command);
-        return base === 'claude' || base === 'claude.exe';
-    }
-
-    async detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
-        const snapshot = context?.processes ?? await captureProcessSnapshot(this.processNames);
-        const relevant = filterByProcessNames(snapshot, this.processNames);
-        const processes = relevant.filter((process) => this.canHandle(process));
-        if (processes.length === 0) {
-            return [];
-        }
-
-        // Step 1: extract `--resume <id>` from command line — authoritative for
-        // resumed sessions where the JSONL predates the process and PID-file/
-        // birthtime heuristics can't match it.
+    /**
+     * Pair live Claude processes with their session files.
+     *
+     * Runs three staged strategies, each handing its unmatched processes
+     * to the next:
+     * 1. `--resume <id>` on the command line — authoritative for resumed
+     *    sessions whose JSONL predates the process.
+     * 2. PID-file matching via ~/.claude/sessions/<pid>.json.
+     * 3. Legacy CWD+birthtime heuristic, for processes with no PID file.
+     */
+    matchRunningProcesses(processes: ProcessInfo[]): ClaudeProcessSessionMatches {
         const { direct: resumeDirect, fallback: noResume } = this.tryResumeMatching(processes);
-
-        // Step 2: try authoritative PID-file matching for the rest
         const { direct: pidDirect, fallback } = this.tryPidFileMatching(noResume);
-
-        const direct = [...resumeDirect, ...pidDirect];
-
-        // Step 3: run legacy CWD+birthtime matching only for processes without a PID file
-        const legacySessions = this.discoverSessions(fallback);
+        const legacySessions = this.discoverLiveSessions(fallback);
         const legacyMatches =
             fallback.length > 0 && legacySessions.length > 0
                 ? matchProcessesToSessions(fallback, legacySessions)
                 : [];
 
-        const matchedPids = new Set([
-            ...direct.map((d) => d.process.pid),
-            ...legacyMatches.map((m) => m.process.pid),
-        ]);
-
-        const agents: AgentInfo[] = [];
-
-        // Build agents from direct (resume + PID-file) matches
-        for (const match of direct) {
-            const { process: proc, sessionFile } = match;
-            const sessionData = this.parser.readSession(sessionFile.filePath, sessionFile.resolvedCwd);
-            if (sessionData) {
-                agents.push(this.mapSessionToAgent(sessionData, proc, sessionFile, {
-                    pidStatus: match.pidStatus,
-                    waitingFor: match.waitingFor,
-                }));
-            } else {
-                matchedPids.delete(proc.pid);
-            }
-        }
+        return {
+            direct: [...resumeDirect, ...pidDirect],
+            legacyMatches,
+        };
+    }
 
-        // Build agents from legacy matches
-        for (const match of legacyMatches) {
-            const sessionData = this.parser.readSession(
-                match.session.filePath,
-                match.session.resolvedCwd,
-            );
-            if (sessionData) {
-                agents.push(this.mapSessionToAgent(sessionData, match.process, match.session));
-            } else {
-                matchedPids.delete(match.process.pid);
-            }
-        }
+    /**
+     * Discover candidate session files for listing historical sessions.
+     *
+     * Always walks every subdirectory of `projectsDir`. We can't use the
+     * encoded-dir shortcut for the cwd-scoped path because Claude Code
+     * indexes session files by where the *process was launched*, not by
+     * the recorded `cwd` field inside the session — these diverge in
+     * worktrees and similar setups. The cwd filter is applied later
+     * against `session.lastCwd` so callers see exactly the sessions whose
+     * recorded cwd matches.
+     */
+    discoverHistoricalSessionFiles(): Array<{ filePath: string; defaultCwd: string }> {
+        const out: Array<{ filePath: string; defaultCwd: string }> = [];
 
-        // Any process with no match (direct or legacy) appears as IDLE
-        for (const proc of processes) {
-            if (!matchedPids.has(proc.pid)) {
-                agents.push(this.mapProcessOnlyAgent(proc));
+        if (!isDirectory(this.projectsDir)) return out;
+
+        for (const dirName of safeReaddir(this.projectsDir)) {
+            const projectDir = path.join(this.projectsDir, dirName);
+            if (!isDirectory(projectDir)) continue;
+
+            // Best-effort decode for the rare case session content has no
+            // recorded cwd: '-Users-foo-bar' → '/Users/foo/bar'. Lossy for
+            // paths containing '-'; session content's lastCwd overrides
+            // this when available.
+            const decoded = dirName.replace(/-/g, '/');
+            for (const name of listJsonl(projectDir)) {
+                out.push({ filePath: path.join(projectDir, name), defaultCwd: decoded });
             }
         }
 
-        return agents;
+        return out;
+    }
+
+    /**
+     * Derive the Claude Code project directory for a given CWD.
+     *
+     * Claude Code encodes paths by replacing every non-alphanumeric
+     * character with '-', so '/', '_', '.', spaces, etc. all collapse:
+     *   /Users/foo/bar          → -Users-foo-bar
+     *   /Users/foo/my_project   → -Users-foo-my-project
+     *   /Users/foo/.worktrees/x → -Users-foo--worktrees-x
+     *
+     * The encoding is lossy — multiple real paths can collide on the
+     * same encoded dir. Callers that need to disambiguate must read the
+     * `cwd` field inside each session JSONL.
+     */
+    private getProjectDir(cwd: string): string {
+        const encoded = cwd.replace(/[^a-zA-Z0-9]/g, '-');
+        return path.join(this.projectsDir, encoded);
     }
 
     /**
@@ -167,7 +155,7 @@ export class ClaudeCodeAdapter implements AgentAdapter {
      * ~/.claude/projects/<encoded>/ directory, then gets session file birthtimes
      * via a single batched stat call across all directories.
      */
-    private discoverSessions(processes: ProcessInfo[]): SessionFile[] {
+    discoverLiveSessions(processes: ProcessInfo[]): SessionFile[] {
         const dirToCwd = new Map<string, string>();
 
         for (const proc of processes) {
@@ -203,10 +191,10 @@ export class ClaudeCodeAdapter implements AgentAdapter {
      * matcher can't pair them) and the PID file may also be misaligned.
      */
     private tryResumeMatching(processes: ProcessInfo[]): {
-        direct: DirectMatch[];
+        direct: ClaudeDirectMatch[];
         fallback: ProcessInfo[];
     } {
-        const direct: DirectMatch[] = [];
+        const direct: ClaudeDirectMatch[] = [];
         const fallback: ProcessInfo[] = [];
 
         for (const proc of processes) {
@@ -312,10 +300,10 @@ export class ClaudeCodeAdapter implements AgentAdapter {
      * stale startedAt (>60s from proc.startTime), or missing JSONL.
      */
     private tryPidFileMatching(processes: ProcessInfo[]): {
-        direct: DirectMatch[];
+        direct: ClaudeDirectMatch[];
         fallback: ProcessInfo[];
     } {
-        const direct: DirectMatch[] = [];
+        const direct: ClaudeDirectMatch[] = [];
         const fallback: ProcessInfo[] = [];
 
         for (const proc of processes) {
@@ -349,134 +337,4 @@ export class ClaudeCodeAdapter implements AgentAdapter {
 
         return { direct, fallback };
     }
-
-    /**
-     * Derive the Claude Code project directory for a given CWD.
-     *
-     * Claude Code encodes paths by replacing every non-alphanumeric
-     * character with '-', so '/', '_', '.', spaces, etc. all collapse:
-     *   /Users/foo/bar          → -Users-foo-bar
-     *   /Users/foo/my_project   → -Users-foo-my-project
-     *   /Users/foo/.worktrees/x → -Users-foo--worktrees-x
-     *
-     * The encoding is lossy — multiple real paths can collide on the
-     * same encoded dir. Callers that need to disambiguate must read the
-     * `cwd` field inside each session JSONL.
-     */
-    private getProjectDir(cwd: string): string {
-        const encoded = cwd.replace(/[^a-zA-Z0-9]/g, '-');
-        return path.join(this.projectsDir, encoded);
-    }
-
-    private mapSessionToAgent(
-        session: ClaudeSession,
-        processInfo: ProcessInfo,
-        sessionFile: SessionFile,
-        liveInfo?: { pidStatus?: AgentStatus; waitingFor?: string },
-    ): AgentInfo {
-        // Live PID-file status is authoritative when present — JSONL-derived
-        // status mis-classifies sessions whose latest entry is a UI-state
-        // event like `permission-mode` or `ai-title`.
-        const status = liveInfo?.pidStatus ?? this.parser.determineStatus(session);
-        const baseSummary = session.lastUserMessage || 'Session started';
-        const summary = status === AgentStatus.WAITING && liveInfo?.waitingFor
-            ? `${baseSummary} — waiting for ${liveInfo.waitingFor}`
-            : baseSummary;
-
-        return {
-            name: generateAgentName(processInfo.cwd, processInfo.pid),
-            type: this.type,
-            status,
-            summary,
-            pid: processInfo.pid,
-            projectPath: sessionFile.resolvedCwd || processInfo.cwd || '',
-            sessionId: sessionFile.sessionId,
-            lastActive: session.lastActive,
-            sessionFilePath: sessionFile.filePath,
-        };
-    }
-
-    private mapProcessOnlyAgent(processInfo: ProcessInfo): AgentInfo {
-        return {
-            name: generateAgentName(processInfo.cwd || '', processInfo.pid),
-            type: this.type,
-            status: AgentStatus.IDLE,
-            summary: 'Unknown',
-            pid: processInfo.pid,
-            projectPath: processInfo.cwd || '',
-            sessionId: `pid-${processInfo.pid}`,
-            lastActive: new Date(),
-        };
-    }
-
-    getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
-        return this.parser.getConversation(sessionFilePath, options);
-    }
-
-    async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
-        const filterCwd = opts?.cwd;
-        const candidates = this.discoverSessionFiles();
-        const summaries: SessionSummary[] = [];
-
-        for (const { filePath, defaultCwd } of candidates) {
-            const session = this.parser.readSession(filePath, defaultCwd);
-            if (!session) continue;
-
-            // Drop sessions whose JSONL had no parseable conversation entries.
-            // readSession is permissive (returns a shell record even when every
-            // line fails to parse); listSessions needs at least one real entry
-            // so we don't surface garbage files.
-            if (!session.lastEntryType) continue;
-
-            const recordedCwd = session.lastCwd || defaultCwd;
-            if (filterCwd !== undefined && recordedCwd !== filterCwd) continue;
-
-            const stat = safeStat(filePath);
-
-            summaries.push({
-                type: 'claude',
-                sessionId: session.sessionId,
-                cwd: recordedCwd,
-                firstUserMessage: session.firstUserMessage || '',
-                lastActive: session.lastActive ?? stat?.mtime ?? new Date(),
-                startedAt: session.sessionStart ?? stat?.birthtime ?? stat?.mtime ?? new Date(),
-                sessionFilePath: filePath,
-            });
-        }
-
-        return summaries;
-    }
-
-    /**
-     * Discover candidate session files for {@link listSessions}.
-     *
-     * Always walks every subdirectory of `projectsDir`. We can't use the
-     * encoded-dir shortcut for the cwd-scoped path because Claude Code
-     * indexes session files by where the *process was launched*, not by
-     * the recorded `cwd` field inside the session — these diverge in
-     * worktrees and similar setups. The cwd filter is applied later
-     * against `session.lastCwd` so callers see exactly the sessions whose
-     * recorded cwd matches.
-     */
-    private discoverSessionFiles(): Array<{ filePath: string; defaultCwd: string }> {
-        const out: Array<{ filePath: string; defaultCwd: string }> = [];
-
-        if (!isDirectory(this.projectsDir)) return out;
-
-        for (const dirName of safeReaddir(this.projectsDir)) {
-            const projectDir = path.join(this.projectsDir, dirName);
-            if (!isDirectory(projectDir)) continue;
-
-            // Best-effort decode for the rare case session content has no
-            // recorded cwd: '-Users-foo-bar' → '/Users/foo/bar'. Lossy for
-            // paths containing '-'; session content's lastCwd overrides
-            // this when available.
-            const decoded = dirName.replace(/-/g, '/');
-            for (const name of listJsonl(projectDir)) {
-                out.push({ filePath: path.join(projectDir, name), defaultCwd: decoded });
-            }
-        }
-
-        return out;
-    }
 }

package/src/{utils → providers/claude}/ClaudeSessionParser.ts

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import type { ConversationMessage } from '../adapters/AgentAdapter.js';
-import { AgentStatus } from '../adapters/AgentAdapter.js';
+import type { ConversationMessage } from '../../adapters/AgentAdapter.js';
+import { AgentStatus } from '../../adapters/AgentAdapter.js';
 
 /**
  * Content block within a Claude Code JSONL message entry.

package/src/{durable → providers/claude/durable}/ClaudeCliProbe.ts

@@ -1,6 +1,7 @@
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { ClaudePrintError } from './DurableAgent.js';
+import { ClaudePrintError } from '../../../durable/DurableAgent.js';
+import { sanitizeText } from '../../../durable/utils.js';
 
 type ExecResult = { stdout: string; stderr: string };
 type Exec = (file: string, args: string[]) => Promise<ExecResult>;
@@ -38,21 +39,14 @@ export class ClaudeCliProbe {
             }
             return {
                 executable: this.executable,
-                version: sanitize(versionResult.stdout, 256) || 'unknown',
+                version: sanitizeText(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 validation failed: ${sanitizeText((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/providers/claude/durable/ClaudePrintAgentService.ts

@@ -0,0 +1,66 @@
+import type { DurableAgent, ProcessIdentity } from '../../../durable/DurableAgent.js';
+import { ClaudePrintError } from '../../../durable/DurableAgent.js';
+import { ClaudeCliProbe } from './ClaudeCliProbe.js';
+import { ClaudePrintRunner, type ClaudePrintRunResult } from './ClaudePrintRunner.js';
+import { DurableAgentRepository, type CreateDurableAgentInput } from '../../../durable/DurableAgentRepository.js';
+import { runDurableAgent, type DurableRunRepository } from '../../../durable/run.js';
+
+interface RepositoryLike extends DurableRunRepository {
+    create(input: CreateDurableAgentInput): Promise<DurableAgent>;
+    list(): Promise<DurableAgent[]>;
+    recordProviderProcess(id: string, token: string, identity: ProcessIdentity): Promise<void>;
+}
+
+interface ProbeLike { validate(): Promise<{ executable: string; version: string }> }
+interface RunnerLike { run(request: Parameters<ClaudePrintRunner['run']>[0]): Promise<ClaudePrintRunResult> }
+
+export interface ClaudePrintAgentServiceOptions {
+    repository?: RepositoryLike;
+    probe?: ProbeLike;
+    runner?: RunnerLike;
+    executable?: string;
+}
+
+export interface ClaudePrintSendResult extends ClaudePrintRunResult {
+    agentId: string;
+    agentName: string;
+}
+
+export class ClaudePrintAgentService {
+    readonly repository: RepositoryLike;
+    private readonly probe: ProbeLike;
+    private readonly runner: RunnerLike;
+    private readonly executable?: string;
+
+    constructor(options: ClaudePrintAgentServiceOptions = {}) {
+        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: CreateDurableAgentInput): Promise<DurableAgent> {
+        await this.probe.validate();
+        return this.repository.create(input);
+    }
+
+    async send(reference: string, prompt: string): Promise<ClaudePrintSendResult> {
+        const completed = await runDurableAgent({
+            reference, provider: 'claude', repository: this.repository,
+            ambiguousError: () => new ClaudePrintError(
+                `Multiple durable agents match "${reference}".`, 'DURABLE_AGENT_AMBIGUOUS'),
+            providerError: () => new ClaudePrintError(
+                'Durable agent provider is not Claude.', 'CLAUDE_PRINT_UNSUPPORTED'),
+            execute: (agent, token) => this.runner.run({
+                agent,
+                prompt,
+                executable: this.executable,
+                firstRun: agent.sessionHealth === 'uninitialized',
+                onSpawn: (identity) => this.repository.recordProviderProcess(agent.id, token, identity),
+            }),
+            isSessionMismatch: (error) => error instanceof ClaudePrintError
+                && error.code === 'CLAUDE_SESSION_MISMATCH',
+        });
+        return { ...completed.result, agentId: completed.agent.id, agentName: completed.agent.name };
+    }
+}