@nathapp/nax 0.40.1 → 0.41.0

package/src/agents/acp/cost.ts

@@ -0,0 +1,79 @@
+/**
+ * ACP cost estimation from token usage.
+ *
+ * Stub — implementation in ACP-006.
+ */
+
+/**
+ * Token usage data from an ACP session's cumulative_token_usage field.
+ */
+export interface SessionTokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+  /** Cache read tokens — billed at a reduced rate */
+  cache_read_input_tokens?: number;
+  /** Cache creation tokens — billed at a higher creation rate */
+  cache_creation_input_tokens?: number;
+}
+
+/**
+ * Per-model pricing in $/1M tokens: { input, output }
+ */
+const MODEL_PRICING: Record<string, { input: number; output: number; cacheRead?: number; cacheCreation?: number }> = {
+  // Anthropic Claude models
+  "claude-sonnet-4": { input: 3, output: 15 },
+  "claude-sonnet-4-5": { input: 3, output: 15 },
+  "claude-haiku": { input: 0.8, output: 4.0, cacheRead: 0.1, cacheCreation: 1.0 },
+  "claude-haiku-4-5": { input: 0.8, output: 4.0, cacheRead: 0.1, cacheCreation: 1.0 },
+  "claude-opus": { input: 15, output: 75 },
+  "claude-opus-4": { input: 15, output: 75 },
+
+  // OpenAI models
+  "gpt-4.1": { input: 10, output: 30 },
+  "gpt-4": { input: 30, output: 60 },
+  "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
+
+  // Google Gemini
+  "gemini-2.5-pro": { input: 0.075, output: 0.3 },
+  "gemini-2-pro": { input: 0.075, output: 0.3 },
+
+  // OpenAI Codex
+  codex: { input: 0.02, output: 0.06 },
+  "code-davinci-002": { input: 0.02, output: 0.06 },
+};
+
+/**
+ * Calculate USD cost from ACP session token counts using per-model pricing.
+ *
+ * @param usage - Token counts from cumulative_token_usage
+ * @param model - Model identifier (e.g., 'claude-sonnet-4', 'claude-haiku-4-5')
+ * @returns Estimated cost in USD
+ */
+export function estimateCostFromTokenUsage(usage: SessionTokenUsage, model: string): number {
+  const pricing = MODEL_PRICING[model];
+
+  if (!pricing) {
+    // Fallback: use average rate for unknown models
+    // Average of known rates: ~$5/1M tokens combined
+    const fallbackInputRate = 3 / 1_000_000;
+    const fallbackOutputRate = 15 / 1_000_000;
+    const inputCost = (usage.input_tokens ?? 0) * fallbackInputRate;
+    const outputCost = (usage.output_tokens ?? 0) * fallbackOutputRate;
+    const cacheReadCost = (usage.cache_read_input_tokens ?? 0) * (0.5 / 1_000_000);
+    const cacheCreationCost = (usage.cache_creation_input_tokens ?? 0) * (2 / 1_000_000);
+    return inputCost + outputCost + cacheReadCost + cacheCreationCost;
+  }
+
+  // Convert $/1M rates to $/token
+  const inputRate = pricing.input / 1_000_000;
+  const outputRate = pricing.output / 1_000_000;
+  const cacheReadRate = (pricing.cacheRead ?? pricing.input * 0.1) / 1_000_000;
+  const cacheCreationRate = (pricing.cacheCreation ?? pricing.input * 0.33) / 1_000_000;
+
+  const inputCost = (usage.input_tokens ?? 0) * inputRate;
+  const outputCost = (usage.output_tokens ?? 0) * outputRate;
+  const cacheReadCost = (usage.cache_read_input_tokens ?? 0) * cacheReadRate;
+  const cacheCreationCost = (usage.cache_creation_input_tokens ?? 0) * cacheCreationRate;
+
+  return inputCost + outputCost + cacheReadCost + cacheCreationCost;
+}

package/src/agents/acp/index.ts

@@ -0,0 +1,9 @@
+/**
+ * ACP Agent Adapter — barrel exports
+ */
+
+export { AcpAgentAdapter, _acpAdapterDeps } from "./adapter";
+export { createSpawnAcpClient } from "./spawn-client";
+export { estimateCostFromTokenUsage } from "./cost";
+export type { SessionTokenUsage } from "./cost";
+export type { AgentRegistryEntry } from "./types";

package/src/agents/acp/interaction-bridge.ts

@@ -0,0 +1,126 @@
+/**
+ * AcpInteractionBridge — connects ACP sessionUpdate notifications to nax interaction chain
+ *
+ * Detects question patterns in agent messages and routes them to the interaction plugin,
+ * enabling mid-session agent ↔ human communication.
+ */
+
+import type { InteractionPlugin, InteractionRequest, InteractionResponse } from "../../interaction/types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SessionNotification {
+  sessionId: string;
+  role: string;
+  content: string;
+  timestamp: number;
+}
+
+export interface BridgeConfig {
+  featureName: string;
+  storyId: string;
+  responseTimeoutMs: number;
+  fallbackPrompt: string;
+}
+
+type BridgeEvent = "question-detected" | "response-received";
+type BridgeEventHandler = (event: unknown) => void;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Question pattern detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+const QUESTION_PATTERNS = [/\?/, /\bwhich\b/i, /\bshould i\b/i, /\bunclear\b/i, /\bplease clarify\b/i];
+
+function containsQuestionPattern(content: string): boolean {
+  return QUESTION_PATTERNS.some((pattern) => pattern.test(content));
+}
+
+function generateRequestId(): string {
+  return `ix-acp-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AcpInteractionBridge
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class AcpInteractionBridge {
+  private readonly plugin: InteractionPlugin;
+  private readonly config: BridgeConfig;
+  private destroyed = false;
+  private readonly listeners = new Map<BridgeEvent, BridgeEventHandler[]>();
+
+  constructor(plugin: InteractionPlugin, config: BridgeConfig) {
+    this.plugin = plugin;
+    this.config = config;
+  }
+
+  isQuestion(notification: SessionNotification): boolean {
+    if (notification.role !== "assistant") return false;
+    return containsQuestionPattern(notification.content);
+  }
+
+  async onSessionUpdate(notification: SessionNotification): Promise<void> {
+    if (this.destroyed) return;
+    if (!this.isQuestion(notification)) return;
+
+    const request: InteractionRequest = {
+      id: generateRequestId(),
+      type: "input",
+      featureName: this.config.featureName,
+      storyId: this.config.storyId,
+      stage: "execution",
+      summary: notification.content,
+      fallback: "continue",
+      createdAt: Date.now(),
+    };
+
+    this.emit("question-detected", { requestId: request.id, sessionId: notification.sessionId });
+
+    await this.plugin.send(request);
+  }
+
+  async waitForResponse(requestId: string, timeout: number): Promise<InteractionResponse> {
+    try {
+      const response = await this.plugin.receive(requestId, timeout);
+      this.emit("response-received", { requestId, respondedBy: response.respondedBy });
+      return response;
+    } catch {
+      const fallback: InteractionResponse = {
+        requestId,
+        action: "input",
+        value: "continue",
+        respondedBy: "timeout",
+        respondedAt: Date.now(),
+      };
+      this.emit("response-received", { requestId, respondedBy: "timeout" });
+      return fallback;
+    }
+  }
+
+  getFollowUpPrompt(response: InteractionResponse): string {
+    if (!response.value) {
+      return this.config.fallbackPrompt;
+    }
+    return response.value;
+  }
+
+  async destroy(): Promise<void> {
+    this.destroyed = true;
+  }
+
+  on(event: BridgeEvent, handler: BridgeEventHandler): void {
+    const handlers = this.listeners.get(event) ?? [];
+    handlers.push(handler);
+    this.listeners.set(event, handlers);
+  }
+
+  private emit(event: BridgeEvent, data: unknown): void {
+    const handlers = this.listeners.get(event) ?? [];
+    for (const handler of handlers) {
+      handler(data);
+    }
+  }
+}

package/src/agents/acp/parser.ts

@@ -0,0 +1,166 @@
+/**
+ * ACP adapter — NDJSON and JSON-RPC output parsing helpers.
+ *
+ * Extracted from adapter.ts to keep that file within the 800-line limit.
+ * Used only by _runOnce() (the spawn-based legacy path).
+ */
+
+import type { AgentRunOptions } from "../types";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Token usage from acpx NDJSON events */
+export interface AcpxTokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+}
+
+/** JSON-RPC message from acpx --format json --json-strict */
+interface JsonRpcMessage {
+  jsonrpc: "2.0";
+  method?: string;
+  params?: {
+    sessionId: string;
+    update?: {
+      sessionUpdate: string;
+      content?: { type: string; text?: string };
+      used?: number;
+      size?: number;
+      cost?: { amount: number; currency: string };
+    };
+  };
+  id?: number | string;
+  result?: unknown;
+  error?: { code: number; message: string };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// streamJsonRpcEvents
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Stream stdout line-by-line, parse JSON-RPC, detect questions, call bridge.
+ */
+export async function streamJsonRpcEvents(
+  stdout: ReadableStream<Uint8Array>,
+  bridge: AgentRunOptions["interactionBridge"],
+  _sessionId: string,
+): Promise<{ text: string; tokenUsage?: AcpxTokenUsage }> {
+  let accumulatedText = "";
+  let tokenUsage: AcpxTokenUsage | undefined;
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  const reader = stdout.getReader();
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+
+        let msg: JsonRpcMessage;
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          continue;
+        }
+
+        if (msg.method === "session/update" && msg.params?.update) {
+          const update = msg.params.update;
+
+          if (
+            update.sessionUpdate === "agent_message_chunk" &&
+            update.content?.type === "text" &&
+            update.content.text
+          ) {
+            accumulatedText += update.content.text;
+
+            if (bridge?.detectQuestion && bridge.onQuestionDetected) {
+              const isQuestion = await bridge.detectQuestion(accumulatedText);
+              if (isQuestion) {
+                const response = await bridge.onQuestionDetected(accumulatedText);
+                accumulatedText += `\n\n[Human response: ${response}]`;
+              }
+            }
+          }
+
+          if (update.sessionUpdate === "usage_update" && update.used !== undefined) {
+            const total = update.used;
+            tokenUsage = {
+              input_tokens: Math.floor(total * 0.3),
+              output_tokens: Math.floor(total * 0.7),
+            };
+          }
+        }
+
+        if (msg.result) {
+          const result = msg.result as Record<string, unknown>;
+          if (typeof result === "string") {
+            accumulatedText += result;
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return { text: accumulatedText.trim(), tokenUsage };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// parseAcpxJsonOutput
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse acpx NDJSON output for assistant text and token usage.
+ */
+export function parseAcpxJsonOutput(rawOutput: string): {
+  text: string;
+  tokenUsage?: AcpxTokenUsage;
+  stopReason?: string;
+  error?: string;
+} {
+  const lines = rawOutput.split("\n").filter((l) => l.trim());
+  let text = "";
+  let tokenUsage: AcpxTokenUsage | undefined;
+  let stopReason: string | undefined;
+  let error: string | undefined;
+
+  for (const line of lines) {
+    try {
+      const event = JSON.parse(line);
+
+      if (event.content && typeof event.content === "string") text += event.content;
+      if (event.text && typeof event.text === "string") text += event.text;
+      if (event.result && typeof event.result === "string") text = event.result;
+
+      if (event.cumulative_token_usage) tokenUsage = event.cumulative_token_usage;
+      if (event.usage) {
+        tokenUsage = {
+          input_tokens: event.usage.input_tokens ?? event.usage.prompt_tokens ?? 0,
+          output_tokens: event.usage.output_tokens ?? event.usage.completion_tokens ?? 0,
+        };
+      }
+
+      if (event.stopReason) stopReason = event.stopReason;
+      if (event.stop_reason) stopReason = event.stop_reason;
+      if (event.error) {
+        error = typeof event.error === "string" ? event.error : (event.error.message ?? JSON.stringify(event.error));
+      }
+    } catch {
+      if (!text) text = line;
+    }
+  }
+
+  return { text: text.trim(), tokenUsage, stopReason, error };
+}

package/src/agents/acp/spawn-client.ts

@@ -0,0 +1,309 @@
+/**
+ * Spawn-based ACP Client — default production implementation.
+ *
+ * Implements AcpClient/AcpSession interfaces by shelling out to acpx CLI.
+ * This is the real transport; createClient injectable defaults to this.
+ * Tests override createClient with mock implementations.
+ *
+ * CLI commands used:
+ *   acpx <agent> sessions ensure --name <name>      → ensureSession
+ *   acpx --cwd <dir> ... <agent> prompt -s <name>   → session.prompt()
+ *   acpx <agent> sessions close <name>              → session.close()
+ *   acpx <agent> cancel                             → session.cancelActivePrompt()
+ */
+
+import { getSafeLogger } from "../../logger";
+import type { AcpClient, AcpSession, AcpSessionResponse } from "./adapter";
+import { parseAcpxJsonOutput } from "./parser";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ACPX_WATCHDOG_BUFFER_MS = 30_000;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Spawn helper (injectable for future testing if needed)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const _spawnClientDeps = {
+  spawn(
+    cmd: string[],
+    opts: {
+      cwd?: string;
+      stdin?: "pipe" | "inherit";
+      stdout: "pipe";
+      stderr: "pipe";
+      env?: Record<string, string | undefined>;
+    },
+  ): {
+    stdout: ReadableStream<Uint8Array>;
+    stderr: ReadableStream<Uint8Array>;
+    stdin: { write(data: string | Uint8Array): number; end(): void; flush(): void };
+    exited: Promise<number>;
+    pid: number;
+    kill(signal?: number): void;
+  } {
+    return Bun.spawn(cmd, opts) as unknown as ReturnType<typeof _spawnClientDeps.spawn>;
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Env builder
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build allowed environment variables for spawned acpx processes.
+ * SEC-4: Only pass essential env vars to prevent leaking sensitive data.
+ */
+function buildAllowedEnv(extraEnv?: Record<string, string | undefined>): Record<string, string | undefined> {
+  const allowed: Record<string, string | undefined> = {};
+
+  const essentialVars = ["PATH", "HOME", "TMPDIR", "NODE_ENV", "USER", "LOGNAME"];
+  for (const varName of essentialVars) {
+    if (process.env[varName]) allowed[varName] = process.env[varName];
+  }
+
+  const apiKeyVars = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY", "CLAUDE_API_KEY"];
+  for (const varName of apiKeyVars) {
+    if (process.env[varName]) allowed[varName] = process.env[varName];
+  }
+
+  const allowedPrefixes = ["CLAUDE_", "NAX_", "CLAW_", "TURBO_", "ACPX_", "CODEX_", "GEMINI_"];
+  for (const [key, value] of Object.entries(process.env)) {
+    if (allowedPrefixes.some((prefix) => key.startsWith(prefix))) {
+      allowed[key] = value;
+    }
+  }
+
+  if (extraEnv) Object.assign(allowed, extraEnv);
+  return allowed;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SpawnAcpSession
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * An ACP session backed by acpx CLI spawn.
+ * Each prompt() call spawns: acpx --cwd ... <agent> prompt -s <name> --file -
+ */
+class SpawnAcpSession implements AcpSession {
+  private readonly agentName: string;
+  private readonly sessionName: string;
+  private readonly cwd: string;
+  private readonly model: string;
+  private readonly timeoutSeconds: number;
+  private readonly permissionMode: string;
+  private readonly env: Record<string, string | undefined>;
+
+  constructor(opts: {
+    agentName: string;
+    sessionName: string;
+    cwd: string;
+    model: string;
+    timeoutSeconds: number;
+    permissionMode: string;
+    env: Record<string, string | undefined>;
+  }) {
+    this.agentName = opts.agentName;
+    this.sessionName = opts.sessionName;
+    this.cwd = opts.cwd;
+    this.model = opts.model;
+    this.timeoutSeconds = opts.timeoutSeconds;
+    this.permissionMode = opts.permissionMode;
+    this.env = opts.env;
+  }
+
+  async prompt(text: string): Promise<AcpSessionResponse> {
+    const cmd = [
+      "acpx",
+      "--cwd",
+      this.cwd,
+      ...(this.permissionMode === "approve-all" ? ["--approve-all"] : []),
+      "--format",
+      "json",
+      "--model",
+      this.model,
+      "--timeout",
+      String(this.timeoutSeconds),
+      this.agentName,
+      "prompt",
+      "-s",
+      this.sessionName,
+      "--file",
+      "-",
+    ];
+
+    getSafeLogger()?.debug("acp-adapter", `Sending prompt to session: ${this.sessionName}`);
+
+    const proc = _spawnClientDeps.spawn(cmd, {
+      cwd: this.cwd,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+      env: this.env,
+    });
+
+    proc.stdin.write(text);
+    proc.stdin.end();
+
+    const exitCode = await proc.exited;
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+
+    if (exitCode !== 0) {
+      getSafeLogger()?.warn("acp-adapter", `Session prompt exited with code ${exitCode}`, {
+        stderr: stderr.slice(0, 200),
+      });
+      // Return error response so the adapter can handle it
+      return {
+        messages: [{ role: "assistant", content: stderr || `Exit code ${exitCode}` }],
+        stopReason: "error",
+      };
+    }
+
+    try {
+      const parsed = parseAcpxJsonOutput(stdout);
+      return {
+        messages: [{ role: "assistant", content: parsed.text || "" }],
+        stopReason: "end_turn",
+        cumulative_token_usage: parsed.tokenUsage,
+      };
+    } catch (err) {
+      getSafeLogger()?.warn("acp-adapter", "Failed to parse session prompt response", {
+        stderr: stderr.slice(0, 200),
+      });
+      throw err;
+    }
+  }
+
+  async close(): Promise<void> {
+    const cmd = ["acpx", this.agentName, "sessions", "close", this.sessionName];
+    getSafeLogger()?.debug("acp-adapter", `Closing session: ${this.sessionName}`);
+
+    const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+    const exitCode = await proc.exited;
+
+    if (exitCode !== 0) {
+      const stderr = await new Response(proc.stderr).text();
+      getSafeLogger()?.warn("acp-adapter", "Failed to close session", {
+        sessionName: this.sessionName,
+        stderr: stderr.slice(0, 200),
+      });
+    }
+  }
+
+  async cancelActivePrompt(): Promise<void> {
+    const cmd = ["acpx", this.agentName, "cancel"];
+    getSafeLogger()?.debug("acp-adapter", `Cancelling active prompt: ${this.sessionName}`);
+
+    const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+    await proc.exited;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SpawnAcpClient
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * ACP client backed by acpx CLI.
+ *
+ * The cmdStr is parsed to extract --model and agent name:
+ *   "acpx --model claude-sonnet-4-5 claude" → model=claude-sonnet-4-5, agent=claude
+ *
+ * createSession() spawns: acpx <agent> sessions ensure --name <name>
+ * loadSession() tries to resume an existing named session.
+ */
+export class SpawnAcpClient implements AcpClient {
+  private readonly agentName: string;
+  private readonly model: string;
+  private readonly cwd: string;
+  private readonly timeoutSeconds: number;
+  private readonly env: Record<string, string | undefined>;
+
+  constructor(cmdStr: string, cwd?: string, timeoutSeconds?: number) {
+    // Parse: "acpx --model <model> <agentName>"
+    const parts = cmdStr.split(/\s+/);
+    const modelIdx = parts.indexOf("--model");
+    this.model = modelIdx >= 0 && parts[modelIdx + 1] ? parts[modelIdx + 1] : "default";
+    // Agent name is the last non-flag token
+    this.agentName = parts[parts.length - 1] || "claude";
+    this.cwd = cwd || process.cwd();
+    this.timeoutSeconds = timeoutSeconds || 1800;
+    this.env = buildAllowedEnv();
+  }
+
+  async start(): Promise<void> {
+    // No-op — spawn-based client doesn't need upfront initialization
+  }
+
+  async createSession(opts: {
+    agentName: string;
+    permissionMode: string;
+    sessionName?: string;
+  }): Promise<AcpSession> {
+    const sessionName = opts.sessionName || `nax-${Date.now()}`;
+
+    // Ensure session exists via CLI
+    const cmd = ["acpx", opts.agentName, "sessions", "ensure", "--name", sessionName];
+    getSafeLogger()?.debug("acp-adapter", `Ensuring session: ${sessionName}`);
+
+    const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+    const exitCode = await proc.exited;
+
+    if (exitCode !== 0) {
+      const stderr = await new Response(proc.stderr).text();
+      throw new Error(`[acp-adapter] Failed to create session: ${stderr || `exit code ${exitCode}`}`);
+    }
+
+    return new SpawnAcpSession({
+      agentName: opts.agentName,
+      sessionName,
+      cwd: this.cwd,
+      model: this.model,
+      timeoutSeconds: this.timeoutSeconds,
+      permissionMode: opts.permissionMode,
+      env: this.env,
+    });
+  }
+
+  async loadSession(sessionName: string): Promise<AcpSession | null> {
+    // Try to ensure session exists — if it does, acpx returns success
+    const cmd = ["acpx", this.agentName, "sessions", "ensure", "--name", sessionName];
+
+    const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+    const exitCode = await proc.exited;
+
+    if (exitCode !== 0) {
+      return null; // Session doesn't exist or can't be resumed
+    }
+
+    return new SpawnAcpSession({
+      agentName: this.agentName,
+      sessionName,
+      cwd: this.cwd,
+      model: this.model,
+      timeoutSeconds: this.timeoutSeconds,
+      permissionMode: "approve-all", // Default for resumed sessions
+      env: this.env,
+    });
+  }
+
+  async close(): Promise<void> {
+    // No-op — spawn-based client has no persistent connection
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory function
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create a spawn-based ACP client. This is the default production factory.
+ * The cmdStr format is: "acpx --model <model> <agentName>"
+ */
+export function createSpawnAcpClient(cmdStr: string, cwd?: string, timeoutSeconds?: number): AcpClient {
+  return new SpawnAcpClient(cmdStr, cwd, timeoutSeconds);
+}