@ai-devkit/agent-manager 0.32.0 → 0.33.0

package/src/providers/claude/durable/ClaudeCliProbe.ts

@@ -1,52 +1,57 @@
-import { execFile } from 'child_process';
-import { promisify } from 'util';
-import { ClaudePrintError } from '../../../durable/DurableAgent.js';
-import { sanitizeText } from '../../../durable/utils.js';
+import { execFile } from "child_process";
+import { promisify } from "util";
+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>;
 
 const execFileAsync = promisify(execFile);
-const REQUIRED = ['--print', '--session-id', '--resume', '--output-format', 'stream-json'];
+const REQUIRED = ["--print", "--session-id", "--resume", "--output-format", "stream-json"];
 
 export interface ClaudeCliProbeOptions {
-    executable?: string;
-    exec?: Exec;
+  executable?: string;
+  exec?: Exec;
 }
 
 export class ClaudeCliProbe {
-    private readonly executable: string;
-    private readonly exec: Exec;
+  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 };
+  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: sanitizeText(versionResult.stdout, 256) || 'unknown',
-            };
-        } catch (error) {
-            if (error instanceof ClaudePrintError) throw error;
-            throw new ClaudePrintError(
-                `Claude CLI validation failed: ${sanitizeText((error as Error).message, 512)}`,
-                'CLAUDE_CLI_UNAVAILABLE',
-            );
-        }
+  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: sanitizeText(versionResult.stdout, 256) || "unknown",
+      };
+    } catch (error) {
+      if (error instanceof ClaudePrintError) throw error;
+      throw new ClaudePrintError(
+        `Claude CLI validation failed: ${sanitizeText((error as Error).message, 512)}`,
+        "CLAUDE_CLI_UNAVAILABLE",
+      );
     }
+  }
 }

package/src/providers/claude/durable/ClaudePrintAgentService.ts

@@ -1,66 +1,79 @@
-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';
+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>;
+  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> }
+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;
+  repository?: RepositoryLike;
+  probe?: ProbeLike;
+  runner?: RunnerLike;
+  executable?: string;
 }
 
 export interface ClaudePrintSendResult extends ClaudePrintRunResult {
-    agentId: string;
-    agentName: string;
+  agentId: string;
+  agentName: string;
 }
 
 export class ClaudePrintAgentService {
-    readonly repository: RepositoryLike;
-    private readonly probe: ProbeLike;
-    private readonly runner: RunnerLike;
-    private readonly executable?: string;
+  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;
-    }
+  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 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 };
-    }
+  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 };
+  }
 }

package/src/providers/claude/durable/ClaudePrintRunner.ts

@@ -1,92 +1,102 @@
-import { spawn as nodeSpawn, type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from 'child_process';
-import type { ClaudeDurableAgent, ProcessIdentity } from '../../../durable/DurableAgent.js';
-import { ClaudePrintError } from '../../../durable/DurableAgent.js';
-import { LocalProcessInspector, type ProcessInspector } from '../../../durable/process.js';
-import { waitForChildClose } from '../../../durable/utils.js';
-import { ClaudeStreamParser } from './ClaudeStreamParser.js';
+import {
+  spawn as nodeSpawn,
+  type ChildProcessWithoutNullStreams,
+  type SpawnOptionsWithoutStdio,
+} from "child_process";
+import type { ClaudeDurableAgent, ProcessIdentity } from "../../../durable/DurableAgent.js";
+import { ClaudePrintError } from "../../../durable/DurableAgent.js";
+import { LocalProcessInspector, type ProcessInspector } from "../../../durable/process.js";
+import { waitForChildClose } from "../../../durable/utils.js";
+import { ClaudeStreamParser } from "./ClaudeStreamParser.js";
 
 type Spawn = (
-    command: string,
-    args: readonly string[],
-    options: SpawnOptionsWithoutStdio & { stdio: ['pipe', 'pipe', 'pipe'] },
+  command: string,
+  args: readonly string[],
+  options: SpawnOptionsWithoutStdio & { stdio: ["pipe", "pipe", "pipe"] },
 ) => ChildProcessWithoutNullStreams;
 
 export interface ClaudePrintRunRequest {
-    agent: ClaudeDurableAgent;
-    prompt: string;
-    executable?: string;
-    firstRun: boolean;
-    onSpawn(identity: ProcessIdentity): Promise<void>;
+  agent: ClaudeDurableAgent;
+  prompt: string;
+  executable?: string;
+  firstRun: boolean;
+  onSpawn(identity: ProcessIdentity): Promise<void>;
 }
 
 export interface ClaudePrintRunResult {
-    sessionId: string;
-    result: string;
-    exitCode: number;
+  sessionId: string;
+  result: string;
+  exitCode: number;
 }
 
 export interface ClaudePrintRunnerOptions {
-    spawn?: Spawn;
-    processInspector?: ProcessInspector;
-    maxLineBytes?: number;
+  spawn?: Spawn;
+  processInspector?: ProcessInspector;
+  maxLineBytes?: number;
 }
 
 export class ClaudePrintRunner {
-    private readonly spawn: Spawn;
-    private readonly processInspector: ProcessInspector;
-    private readonly maxLineBytes: number;
+  private readonly spawn: Spawn;
+  private readonly processInspector: ProcessInspector;
+  private readonly maxLineBytes: number;
 
-    constructor(options: ClaudePrintRunnerOptions = {}) {
-        this.spawn = options.spawn ?? (nodeSpawn as Spawn);
-        this.processInspector = options.processInspector ?? new LocalProcessInspector();
-        this.maxLineBytes = options.maxLineBytes ?? 1024 * 1024;
-    }
+  constructor(options: ClaudePrintRunnerOptions = {}) {
+    this.spawn = options.spawn ?? (nodeSpawn as Spawn);
+    this.processInspector = options.processInspector ?? new LocalProcessInspector();
+    this.maxLineBytes = options.maxLineBytes ?? 1024 * 1024;
+  }
 
-    async run(request: ClaudePrintRunRequest): Promise<ClaudePrintRunResult> {
-        const sessionArgs = request.firstRun
-            ? ['--session-id', request.agent.providerSessionId]
-            : ['--resume', request.agent.providerSessionId];
-        const args = ['-p', ...sessionArgs, '--output-format', 'stream-json', '--verbose'];
-        const child = this.spawn(request.executable ?? 'claude', args, {
-            cwd: request.agent.cwd,
-            shell: false,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        if (!child.pid) {
-            child.kill();
-            throw new ClaudePrintError('Claude process did not provide a PID.', 'CLAUDE_PROCESS_IDENTITY');
-        }
-        const identity = this.processInspector.getIdentity(child.pid);
-        if (!identity) {
-            child.kill();
-            throw new ClaudePrintError('Cannot verify Claude process identity.', 'CLAUDE_PROCESS_IDENTITY');
-        }
+  async run(request: ClaudePrintRunRequest): Promise<ClaudePrintRunResult> {
+    const sessionArgs = request.firstRun
+      ? ["--session-id", request.agent.providerSessionId]
+      : ["--resume", request.agent.providerSessionId];
+    const args = ["-p", ...sessionArgs, "--output-format", "stream-json", "--verbose"];
+    const child = this.spawn(request.executable ?? "claude", args, {
+      cwd: request.agent.cwd,
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    if (!child.pid) {
+      child.kill();
+      throw new ClaudePrintError(
+        "Claude process did not provide a PID.",
+        "CLAUDE_PROCESS_IDENTITY",
+      );
+    }
+    const identity = this.processInspector.getIdentity(child.pid);
+    if (!identity) {
+      child.kill();
+      throw new ClaudePrintError(
+        "Cannot verify Claude process identity.",
+        "CLAUDE_PROCESS_IDENTITY",
+      );
+    }
 
-        const parser = new ClaudeStreamParser(request.agent.providerSessionId, this.maxLineBytes);
+    const parser = new ClaudeStreamParser(request.agent.providerSessionId, this.maxLineBytes);
 
-        child.stdout.on('data', (chunk: Buffer | string) => {
-            if (parser.hasFailed()) return;
-            try {
-                parser.accept(chunk);
-            } catch (error) {
-                parser.fail(error);
-            }
-        });
-        // Drain provider diagnostics without reflecting potentially sensitive prompt/tool data.
-        child.stderr.resume();
+    child.stdout.on("data", (chunk: Buffer | string) => {
+      if (parser.hasFailed()) return;
+      try {
+        parser.accept(chunk);
+      } catch (error) {
+        parser.fail(error);
+      }
+    });
+    // Drain provider diagnostics without reflecting potentially sensitive prompt/tool data.
+    child.stderr.resume();
 
-        const closed = waitForChildClose(child);
+    const closed = waitForChildClose(child);
 
-        try {
-            await request.onSpawn(identity);
-        } catch (error) {
-            child.kill();
-            throw error;
-        }
+    try {
+      await request.onSpawn(identity);
+    } catch (error) {
+      child.kill();
+      throw error;
+    }
 
-        child.stdin.end(request.prompt);
-        const { code, signal } = await closed;
+    child.stdin.end(request.prompt);
+    const { code, signal } = await closed;
 
-        return parser.result({ code, signal });
-    }
+    return parser.result({ code, signal });
+  }
 }

package/src/providers/claude/durable/ClaudeStreamParser.ts

@@ -1,79 +1,108 @@
-import { ClaudePrintError } from '../../../durable/DurableAgent.js';
-import { LineBuffer, type ChildCloseResult } from '../../../durable/utils.js';
-import type { ClaudePrintRunResult } from './ClaudePrintRunner.js';
+import { ClaudePrintError } from "../../../durable/DurableAgent.js";
+import { LineBuffer, type ChildCloseResult } from "../../../durable/utils.js";
+import type { ClaudePrintRunResult } from "./ClaudePrintRunner.js";
 
 export class ClaudeStreamParser {
-    private readonly lines: LineBuffer;
-    private terminal: ClaudePrintRunResult | null = null;
-    private protocolError: ClaudePrintError | null = null;
+  private readonly lines: LineBuffer;
+  private terminal: ClaudePrintRunResult | null = null;
+  private protocolError: ClaudePrintError | null = null;
 
-    constructor(
-        private readonly expectedSessionId: string,
-        maxLineBytes: number,
-    ) {
-        this.lines = new LineBuffer(
-            maxLineBytes,
-            () => new ClaudePrintError('Claude stream line exceeded the safety limit.', 'CLAUDE_STREAM_OVERSIZED'),
-        );
-    }
+  constructor(
+    private readonly expectedSessionId: string,
+    maxLineBytes: number,
+  ) {
+    this.lines = new LineBuffer(
+      maxLineBytes,
+      () =>
+        new ClaudePrintError(
+          "Claude stream line exceeded the safety limit.",
+          "CLAUDE_STREAM_OVERSIZED",
+        ),
+    );
+  }
 
-    hasFailed(): boolean {
-        return this.protocolError !== null;
-    }
+  hasFailed(): boolean {
+    return this.protocolError !== null;
+  }
 
-    accept(chunk: Buffer | string): void {
-        for (const line of this.lines.accept(chunk)) {
-            this.processLine(line);
-        }
+  accept(chunk: Buffer | string): void {
+    for (const line of this.lines.accept(chunk)) {
+      this.processLine(line);
     }
+  }
 
-    fail(error: unknown): void {
-        this.protocolError = error instanceof ClaudePrintError
-            ? error
-            : new ClaudePrintError('Claude stream processing failed.', 'CLAUDE_STREAM_INVALID');
-    }
+  fail(error: unknown): void {
+    this.protocolError =
+      error instanceof ClaudePrintError
+        ? error
+        : new ClaudePrintError("Claude stream processing failed.", "CLAUDE_STREAM_INVALID");
+  }
 
-    result(close: ChildCloseResult): ClaudePrintRunResult {
-        if (this.protocolError) throw this.protocolError;
-        this.lines.assertComplete(() => new ClaudePrintError('Claude stream ended with incomplete JSON.', 'CLAUDE_STREAM_INVALID'));
-        if (close.code !== 0) {
-            throw new ClaudePrintError(
-                `Claude print run failed${close.signal ? ` (${close.signal})` : '.'}`,
-                'CLAUDE_PROCESS_FAILED',
-            );
-        }
-        if (!this.terminal) throw new ClaudePrintError('Claude stream ended without a terminal result.', 'CLAUDE_RESULT_MISSING');
-        return { sessionId: this.terminal.sessionId, result: this.terminal.result, exitCode: close.code };
+  result(close: ChildCloseResult): ClaudePrintRunResult {
+    if (this.protocolError) throw this.protocolError;
+    this.lines.assertComplete(
+      () =>
+        new ClaudePrintError("Claude stream ended with incomplete JSON.", "CLAUDE_STREAM_INVALID"),
+    );
+    if (close.code !== 0) {
+      throw new ClaudePrintError(
+        `Claude print run failed${close.signal ? ` (${close.signal})` : "."}`,
+        "CLAUDE_PROCESS_FAILED",
+      );
     }
+    if (!this.terminal)
+      throw new ClaudePrintError(
+        "Claude stream ended without a terminal result.",
+        "CLAUDE_RESULT_MISSING",
+      );
+    return {
+      sessionId: this.terminal.sessionId,
+      result: this.terminal.result,
+      exitCode: close.code,
+    };
+  }
 
-    private processLine(line: Buffer): void {
-        if (line.length === 0) return;
+  private processLine(line: Buffer): void {
+    if (line.length === 0) return;
 
-        const event = this.parseEvent(line);
-        if (typeof event.session_id === 'string' && event.session_id !== this.expectedSessionId) {
-            throw new ClaudePrintError('Claude returned a different session identity.', 'CLAUDE_SESSION_MISMATCH');
-        }
-        if (event.type === 'result') this.recordTerminalResult(event);
+    const event = this.parseEvent(line);
+    if (typeof event.session_id === "string" && event.session_id !== this.expectedSessionId) {
+      throw new ClaudePrintError(
+        "Claude returned a different session identity.",
+        "CLAUDE_SESSION_MISMATCH",
+      );
     }
+    if (event.type === "result") this.recordTerminalResult(event);
+  }
 
-    private parseEvent(line: Buffer): Record<string, unknown> {
-        let value: unknown;
-        try {
-            value = JSON.parse(line.toString('utf8'));
-        } catch {
-            throw new ClaudePrintError('Claude emitted malformed stream JSON.', 'CLAUDE_STREAM_INVALID');
-        }
-        if (!value || typeof value !== 'object' || Array.isArray(value)) {
-            throw new ClaudePrintError('Claude emitted a non-object stream message.', 'CLAUDE_STREAM_INVALID');
-        }
-        return value as Record<string, unknown>;
+  private parseEvent(line: Buffer): Record<string, unknown> {
+    let value: unknown;
+    try {
+      value = JSON.parse(line.toString("utf8"));
+    } catch {
+      throw new ClaudePrintError("Claude emitted malformed stream JSON.", "CLAUDE_STREAM_INVALID");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new ClaudePrintError(
+        "Claude emitted a non-object stream message.",
+        "CLAUDE_STREAM_INVALID",
+      );
     }
+    return value as Record<string, unknown>;
+  }
 
-    private recordTerminalResult(event: Record<string, unknown>): void {
-        if (this.terminal) throw new ClaudePrintError('Claude emitted more than one terminal result.', 'CLAUDE_STREAM_INVALID');
-        if (typeof event.session_id !== 'string' || typeof event.result !== 'string') {
-            throw new ClaudePrintError('Claude emitted an invalid terminal result.', 'CLAUDE_STREAM_INVALID');
-        }
-        this.terminal = { sessionId: event.session_id, result: event.result, exitCode: 0 };
+  private recordTerminalResult(event: Record<string, unknown>): void {
+    if (this.terminal)
+      throw new ClaudePrintError(
+        "Claude emitted more than one terminal result.",
+        "CLAUDE_STREAM_INVALID",
+      );
+    if (typeof event.session_id !== "string" || typeof event.result !== "string") {
+      throw new ClaudePrintError(
+        "Claude emitted an invalid terminal result.",
+        "CLAUDE_STREAM_INVALID",
+      );
     }
+    this.terminal = { sessionId: event.session_id, result: event.result, exitCode: 0 };
+  }
 }