opencara 0.102.0 → 0.103.0

package/dist/bin.js

@@ -77,12 +77,28 @@ var AgentRunStatusSchema = z3.enum([
   "failed",
   "cancelled"
 ]);
+var AcpHistoryTurnSchema = z3.object({
+  role: z3.enum(["user", "assistant"]),
+  text: z3.string()
+});
+var AcpSpecSchema = z3.object({
+  systemPromptMd: z3.string(),
+  userPromptMd: z3.string(),
+  history: z3.array(AcpHistoryTurnSchema).default([]),
+  pageContextJson: z3.string().optional()
+});
 var AgentSpecSchema = z3.object({
   kind: z3.string(),
   command: z3.string(),
   args: z3.array(z3.string()).default([]),
   env: z3.record(z3.string()).default({}),
-  cwd: z3.string().optional()
+  cwd: z3.string().optional(),
+  /**
+   * Present iff this run goes through the ACP+MCP path. Mutually exclusive
+   * with the legacy stdin-JSON envelope — when set, `JobAssignment.stdinJson`
+   * is ignored by the device runner.
+   */
+  acp: AcpSpecSchema.optional()
 });
 var AgentRunSchema = z3.object({
   id: z3.string(),
@@ -207,17 +223,58 @@ var AgentCallSchema = z4.discriminatedUnion("kind", [
   FlowNodeConfigSetCallSchema,
   TemplateNodeConfigSetCallSchema
 ]);
+var AgentCallRequestEnvelope = {
+  type: z4.literal("agent-call-request"),
+  runId: z4.string(),
+  callId: z4.string()
+};
+var IssueBodySetCallRequestSchema = z4.object({
+  ...AgentCallRequestEnvelope,
+  kind: z4.literal("issue.body.set"),
+  issueNumber: z4.number().int(),
+  bodyMd: z4.string()
+});
+var FlowNodeConfigSetCallRequestSchema = z4.object({
+  ...AgentCallRequestEnvelope,
+  kind: z4.literal("flow.node.config.set"),
+  flowSlug: z4.string().min(1),
+  nodeId: z4.string().min(1),
+  config: z4.record(z4.string(), z4.unknown())
+});
+var TemplateNodeConfigSetCallRequestSchema = z4.object({
+  ...AgentCallRequestEnvelope,
+  kind: z4.literal("template.node.config.set"),
+  templateSlug: z4.string().min(1),
+  nodeId: z4.string().min(1),
+  config: z4.record(z4.string(), z4.unknown())
+});
+var AgentCallRequestSchema = z4.discriminatedUnion("kind", [
+  IssueBodySetCallRequestSchema,
+  FlowNodeConfigSetCallRequestSchema,
+  TemplateNodeConfigSetCallRequestSchema
+]);
+var AgentCallResultSchema = z4.object({
+  type: z4.literal("agent-call-result"),
+  runId: z4.string(),
+  callId: z4.string(),
+  result: z4.union([
+    z4.object({ ok: z4.literal(true) }),
+    z4.object({ ok: z4.literal(false), reason: z4.string() })
+  ])
+});
 var ServerToDeviceMessageSchema = z4.discriminatedUnion("type", [
   JobAssignmentSchema,
   HelloAckSchema,
-  PingSchema
+  PingSchema,
+  AgentCallResultSchema
 ]);
 var DeviceToServerMessageSchema = z4.union([
   HelloMessageSchema,
   LogFrameSchema,
   RunDoneSchema,
   PongSchema,
-  AgentCallSchema
+  AgentCallSchema,
+  AgentCallRequestSchema
 ]);
 var HostRegisterRequestSchema = z4.object({
   hostId: z4.string(),
@@ -399,10 +456,719 @@ var WsClient = class {
 };
 
 // src/runner/spawn.ts
+import { spawn as spawn3 } from "node:child_process";
+
+// src/acp/client.ts
 import { spawn as spawn2 } from "node:child_process";
+import { EventEmitter } from "node:events";
+
+// src/acp/framing.ts
+function encodeFrame(msg) {
+  return JSON.stringify(msg) + "\n";
+}
+var FrameDecoder = class {
+  buffer = "";
+  /** Feed a chunk. Returns parsed messages and any malformed lines. */
+  feed(chunk) {
+    this.buffer += chunk;
+    const messages = [];
+    const malformed = [];
+    const lines = this.buffer.split("\n");
+    this.buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (isPlainObject(parsed)) {
+          messages.push(parsed);
+        } else {
+          malformed.push(trimmed);
+        }
+      } catch {
+        malformed.push(trimmed);
+      }
+    }
+    return { messages, malformed };
+  }
+  /** Whatever's still buffered (a partial line awaiting more data). */
+  remainder() {
+    return this.buffer;
+  }
+};
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// src/acp/jsonrpc.ts
+var JSON_RPC_ERROR_METHOD_NOT_FOUND = -32601;
+
+// src/acp/types.ts
+var ACP_METHODS = {
+  // Agent methods (client → agent).
+  initialize: "initialize",
+  session_new: "session/new",
+  session_load: "session/load",
+  session_prompt: "session/prompt",
+  session_cancel: "session/cancel",
+  // Client methods (agent → client) — handled minimally in this spike.
+  session_update: "session/update",
+  session_request_permission: "session/request_permission",
+  fs_read_text_file: "fs/read_text_file",
+  fs_write_text_file: "fs/write_text_file"
+};
+var ACP_PROTOCOL_VERSION = 1;
+function isMessageChunk(u) {
+  return u.sessionUpdate === "user_message_chunk" || u.sessionUpdate === "agent_message_chunk" || u.sessionUpdate === "agent_thought_chunk";
+}
+function isToolCallStart(u) {
+  return u.sessionUpdate === "tool_call";
+}
+function isToolCallProgress(u) {
+  return u.sessionUpdate === "tool_call_update";
+}
+
+// src/acp/client.ts
+var AcpConnection = class {
+  constructor(out, trace) {
+    this.out = out;
+    this.trace = trace;
+  }
+  out;
+  trace;
+  decoder = new FrameDecoder();
+  pending = /* @__PURE__ */ new Map();
+  emitter = new EventEmitter();
+  nextId = 1;
+  closed = false;
+  // ─── public events ───────────────────────────────────────────────
+  onSessionUpdate(fn) {
+    this.emitter.on("sessionUpdate", fn);
+  }
+  /** Called for EVERY frame that crosses the wire — both directions. */
+  onFrame(fn) {
+    this.emitter.on("frame", fn);
+  }
+  /** Malformed lines (parse errors). The spike harness logs these. */
+  onMalformed(fn) {
+    this.emitter.on("malformed", fn);
+  }
+  // ─── public methods ──────────────────────────────────────────────
+  initialize(req) {
+    return this.request(ACP_METHODS.initialize, req);
+  }
+  newSession(req) {
+    return this.request(ACP_METHODS.session_new, req);
+  }
+  prompt(req) {
+    return this.request(ACP_METHODS.session_prompt, req);
+  }
+  /** Notification (no reply). Used to cancel a turn mid-flight. */
+  cancel(sessionId) {
+    this.notify(ACP_METHODS.session_cancel, { sessionId });
+  }
+  // ─── ingest path (public so the wrapper can pump bytes in) ───────
+  feed(chunk) {
+    if (this.closed) return;
+    const { messages, malformed } = this.decoder.feed(chunk);
+    for (const line of malformed) this.emitter.emit("malformed", line);
+    for (const msg of messages) this.dispatch(msg);
+  }
+  /**
+   * Reject all pending requests. Called when the underlying transport closes
+   * (child process exit, stream error, manual disposal). Safe to call twice.
+   *
+   * User listeners are deliberately NOT cleared. Diagnostic events (frame
+   * trace, malformed lines) can still fire during the close sequence, and
+   * GC reclaims them when the consumer drops the connection.
+   */
+  shutdown(reason) {
+    if (this.closed) return;
+    this.closed = true;
+    const err = new Error(`acp connection closed: ${reason}`);
+    for (const p of this.pending.values()) p.reject(err);
+    this.pending.clear();
+  }
+  // ─── internals ───────────────────────────────────────────────────
+  request(method, params) {
+    if (this.closed) return Promise.reject(new Error("acp connection is closed"));
+    const id = this.nextId++;
+    const msg = { jsonrpc: "2.0", id, method, params };
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject, method });
+      this.send(msg);
+    });
+  }
+  notify(method, params) {
+    if (this.closed) return;
+    this.send({ jsonrpc: "2.0", method, params });
+  }
+  send(msg) {
+    if (this.trace) this.emitter.emit("frame", "out", msg);
+    this.out.write(encodeFrame(msg));
+  }
+  dispatch(msg) {
+    if (this.trace) this.emitter.emit("frame", "in", msg);
+    if ("result" in msg || "error" in msg) {
+      if (msg.id == null) return;
+      const pending = this.pending.get(msg.id);
+      if (!pending) return;
+      this.pending.delete(msg.id);
+      if ("error" in msg) {
+        pending.reject(
+          new Error(`${pending.method}: ${msg.error.message} (${msg.error.code})`)
+        );
+      } else {
+        pending.resolve(msg.result);
+      }
+      return;
+    }
+    if (!("id" in msg) || msg.id == null) {
+      if ("method" in msg && msg.method === ACP_METHODS.session_update) {
+        this.emitter.emit("sessionUpdate", msg.params);
+      }
+      return;
+    }
+    if (msg.method === ACP_METHODS.session_request_permission) {
+      this.send(buildAutoAllowResponse(msg.id, msg.params));
+      return;
+    }
+    const reply = {
+      jsonrpc: "2.0",
+      id: msg.id,
+      error: {
+        code: JSON_RPC_ERROR_METHOD_NOT_FOUND,
+        message: `method not implemented in spike client: ${msg.method}`
+      }
+    };
+    this.send(reply);
+  }
+};
+function buildAutoAllowResponse(id, params) {
+  const options = params && typeof params === "object" && "options" in params ? params.options : [];
+  const allow = options.find((o) => o?.kind === "allow_once") ?? options.find((o) => o?.kind === "allow_always");
+  if (allow?.optionId) {
+    return {
+      jsonrpc: "2.0",
+      id,
+      result: { outcome: { outcome: "selected", optionId: allow.optionId } }
+    };
+  }
+  return {
+    jsonrpc: "2.0",
+    id,
+    result: { outcome: { outcome: "cancelled" } }
+  };
+}
+var AcpClient = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  child = null;
+  connection = null;
+  exitPromise = null;
+  stderrListeners = /* @__PURE__ */ new Set();
+  // Pre-start listener queues. Registering listeners before `start()` is the
+  // natural order in the spike (and any consumer that wants to capture the
+  // very first frame). We hold them here and attach to the live connection
+  // inside `start()`. Once started, registrations bypass the queue and go
+  // straight to the connection.
+  preStartSessionUpdate = [];
+  preStartFrame = [];
+  preStartMalformed = [];
+  start() {
+    if (this.child) return;
+    const env = { ...process.env, ...this.opts.env ?? {} };
+    const child = spawn2(this.opts.command, this.opts.args ?? [], {
+      env,
+      cwd: this.opts.cwd,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    const conn = new AcpConnection(
+      { write: (chunk) => child.stdin.write(chunk) },
+      this.opts.trace ?? false
+    );
+    for (const fn of this.preStartSessionUpdate) conn.onSessionUpdate(fn);
+    for (const fn of this.preStartFrame) conn.onFrame(fn);
+    for (const fn of this.preStartMalformed) conn.onMalformed(fn);
+    this.preStartSessionUpdate.length = 0;
+    this.preStartFrame.length = 0;
+    this.preStartMalformed.length = 0;
+    child.stdout.on("data", (chunk) => conn.feed(chunk));
+    child.stderr.on("data", (chunk) => {
+      for (const fn of this.stderrListeners) fn(chunk);
+    });
+    this.exitPromise = new Promise((resolve) => {
+      child.on("close", (code, signal) => {
+        conn.shutdown(`child exited code=${code} signal=${signal ?? "none"}`);
+        resolve({ code, signal });
+      });
+      child.on("error", (err) => {
+        conn.shutdown(`child error: ${err.message}`);
+        resolve({ code: null, signal: null });
+      });
+    });
+    this.child = child;
+    this.connection = conn;
+  }
+  // ─── delegations to the connection ───────────────────────────────
+  initialize(req = { protocolVersion: ACP_PROTOCOL_VERSION }) {
+    return this.must().initialize(req);
+  }
+  newSession(req) {
+    return this.must().newSession(req);
+  }
+  prompt(req) {
+    return this.must().prompt(req);
+  }
+  cancel(sessionId) {
+    this.must().cancel(sessionId);
+  }
+  onSessionUpdate(fn) {
+    if (this.connection) this.connection.onSessionUpdate(fn);
+    else this.preStartSessionUpdate.push(fn);
+  }
+  onFrame(fn) {
+    if (this.connection) this.connection.onFrame(fn);
+    else this.preStartFrame.push(fn);
+  }
+  onMalformed(fn) {
+    if (this.connection) this.connection.onMalformed(fn);
+    else this.preStartMalformed.push(fn);
+  }
+  onStderr(fn) {
+    this.stderrListeners.add(fn);
+  }
+  /**
+   * Close stdin and wait for the child to exit. If the child is still
+   * running after `graceMs`, send SIGTERM; if it's still alive after
+   * `2 * graceMs`, send SIGKILL. Always resolves.
+   */
+  async close(graceMs = 2e3) {
+    const child = this.child;
+    if (!child || !this.exitPromise) return { code: null, signal: null };
+    try {
+      child.stdin.end();
+    } catch {
+    }
+    const term = setTimeout(() => {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+      }
+    }, graceMs);
+    const kill = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+    }, graceMs * 2);
+    try {
+      return await this.exitPromise;
+    } finally {
+      clearTimeout(term);
+      clearTimeout(kill);
+    }
+  }
+  must() {
+    if (!this.connection) throw new Error("acp client not started \u2014 call start() first");
+    return this.connection;
+  }
+};
+
+// src/mcp/host.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve as pathResolve2 } from "node:path";
+
+// src/mcp/ipc.ts
+import { createServer, createConnection } from "node:net";
+import { unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve as pathResolve } from "node:path";
+var IPC_SOCKET_ENV = "OPENCARA_MCP_IPC_SOCKET";
+function defaultIpcSocketPath(runId) {
+  return pathResolve(tmpdir(), `opencara-mcp-${runId}.sock`);
+}
+function encode(frame) {
+  return JSON.stringify(frame) + "\n";
+}
+function decode(buffered, chunk) {
+  const buf = buffered + chunk;
+  const lines = buf.split("\n");
+  const remainder = lines.pop() ?? "";
+  const frames = [];
+  const malformed = [];
+  for (const line of lines) {
+    const t = line.trim();
+    if (t.length === 0) continue;
+    try {
+      const parsed = JSON.parse(t);
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && "type" in parsed && (parsed.type === "tool-call" || parsed.type === "tool-result")) {
+        frames.push(parsed);
+      } else {
+        malformed.push(t);
+      }
+    } catch {
+      malformed.push(t);
+    }
+  }
+  return { frames, malformed, buffered: remainder };
+}
+var IpcServer = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  server = null;
+  connection = null;
+  async start() {
+    await unlink(this.opts.socketPath).catch(() => void 0);
+    await new Promise((resolve, reject) => {
+      const server = createServer((socket) => {
+        if (this.connection) {
+          socket.destroy();
+          return;
+        }
+        this.connection = socket;
+        this.opts.onConnect?.();
+        let buffered = "";
+        socket.setEncoding("utf8");
+        socket.on("data", (chunk) => {
+          const d = decode(buffered, chunk);
+          buffered = d.buffered;
+          for (const frame of d.frames) {
+            if (frame.type === "tool-call") {
+              void this.handleCall(frame, socket);
+            }
+          }
+        });
+        socket.on("close", () => {
+          if (this.connection === socket) this.connection = null;
+          this.opts.onDisconnect?.();
+        });
+        socket.on("error", () => {
+        });
+      });
+      server.on("error", reject);
+      server.listen(this.opts.socketPath, () => {
+        this.server = server;
+        resolve();
+      });
+    });
+  }
+  async handleCall(call, socket) {
+    let result;
+    try {
+      result = await this.opts.handler(call);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      result = { ok: false, reason: `transport error: ${reason}` };
+    }
+    if (socket.writable) {
+      socket.write(encode({ type: "tool-result", callId: call.callId, result }));
+    }
+  }
+  async stop() {
+    if (this.connection) {
+      this.connection.destroy();
+      this.connection = null;
+    }
+    if (this.server) {
+      await new Promise((resolve) => this.server.close(() => resolve()));
+      this.server = null;
+    }
+    await unlink(this.opts.socketPath).catch(() => void 0);
+  }
+};
+
+// src/mcp/host.ts
+function defaultMcpInvocation() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const sourceBin = pathResolve2(here, "..", "bin", "opencara-mcp.ts");
+  if (existsSync2(sourceBin)) {
+    return { command: "tsx", args: [sourceBin] };
+  }
+  const distBin = pathResolve2(here, "opencara-mcp.js");
+  if (existsSync2(distBin)) {
+    return { command: "node", args: [distBin] };
+  }
+  return { command: "opencara-mcp", args: [] };
+}
+var McpHost = class {
+  server;
+  socketPath;
+  mcpCommand;
+  mcpArgs;
+  started = false;
+  constructor(opts) {
+    this.socketPath = opts.socketPath ?? defaultIpcSocketPath(opts.runId);
+    const inv = opts.mcpCommand ? { command: opts.mcpCommand, args: opts.mcpArgs ?? [] } : defaultMcpInvocation();
+    this.mcpCommand = inv.command;
+    this.mcpArgs = inv.args;
+    this.server = new IpcServer({
+      socketPath: this.socketPath,
+      handler: async (call) => {
+        return opts.router.call(call.kind, call.args);
+      }
+    });
+  }
+  async start() {
+    if (this.started) return;
+    await this.server.start();
+    this.started = true;
+  }
+  /**
+   * The shape the ACP client should put in `session/new`'s `mcpServers`
+   * array. Agent spawns this command; opencara-mcp reads
+   * `OPENCARA_MCP_IPC_SOCKET` and dials back to our IPC server.
+   */
+  acpServerEntry() {
+    return {
+      type: "stdio",
+      name: "opencara",
+      command: this.mcpCommand,
+      args: [...this.mcpArgs],
+      env: [{ name: IPC_SOCKET_ENV, value: this.socketPath }]
+    };
+  }
+  async stop() {
+    if (!this.started) return;
+    await this.server.stop();
+    this.started = false;
+  }
+};
+
+// src/mcp/wsBridge.ts
+var WsAgentCallBridge = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  pending = /* @__PURE__ */ new Map();
+  nextCallId = 1;
+  /**
+   * Pass to McpHost as the tool-call router. Each invocation mints a
+   * callId, sends an `agent-call-request`, and parks the resolver until
+   * `onResult` finds a match.
+   */
+  router = {
+    call: (kind, args) => this.dispatch(kind, args)
+  };
+  /**
+   * Forward an inbound `agent-call-result` frame from the WS layer.
+   * Resolves the matching pending call. Stale callIds (the run already
+   * ended, or someone replied twice) are dropped silently.
+   */
+  onResult(msg) {
+    if (msg.runId !== this.opts.runId) return;
+    const p = this.pending.get(msg.callId);
+    if (!p) return;
+    this.pending.delete(msg.callId);
+    p.resolve(msg.result);
+  }
+  /**
+   * Reject every in-flight tool call. Call when the run ends or the WS
+   * disconnects so opencara-mcp doesn't hang forever waiting on a result
+   * that will never arrive.
+   */
+  shutdown(reason) {
+    if (this.pending.size === 0) return;
+    const err = new Error(`bridge closed: ${reason}`);
+    for (const p of this.pending.values()) p.reject(err);
+    this.pending.clear();
+  }
+  dispatch(kind, args) {
+    const callId = `bc${this.nextCallId++}`;
+    const req = buildAgentCallRequest(this.opts.runId, callId, kind, args);
+    if (!req) {
+      return Promise.resolve({
+        ok: false,
+        reason: `unknown agent-call kind: ${kind}`
+      });
+    }
+    return new Promise((resolve, reject) => {
+      this.pending.set(callId, { resolve, reject });
+      try {
+        this.opts.sendRequest(req);
+      } catch (err) {
+        this.pending.delete(callId);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+  }
+};
+function buildAgentCallRequest(runId, callId, kind, args) {
+  switch (kind) {
+    case "issue.body.set":
+      return {
+        type: "agent-call-request",
+        runId,
+        callId,
+        kind: "issue.body.set",
+        issueNumber: Number(args["issueNumber"]),
+        bodyMd: String(args["bodyMd"] ?? "")
+      };
+    case "flow.node.config.set":
+      return {
+        type: "agent-call-request",
+        runId,
+        callId,
+        kind: "flow.node.config.set",
+        flowSlug: String(args["flowSlug"] ?? ""),
+        nodeId: String(args["nodeId"] ?? ""),
+        config: args["config"] ?? {}
+      };
+    case "template.node.config.set":
+      return {
+        type: "agent-call-request",
+        runId,
+        callId,
+        kind: "template.node.config.set",
+        templateSlug: String(args["templateSlug"] ?? ""),
+        nodeId: String(args["nodeId"] ?? ""),
+        config: args["config"] ?? {}
+      };
+    default:
+      return null;
+  }
+}
+
+// src/runner/acpRunner.ts
+function runAcpJob(opts) {
+  const { runId, spec, handlers } = opts;
+  if (!spec.acp) {
+    throw new Error("runAcpJob: spec.acp is required");
+  }
+  const acpSpec = spec.acp;
+  const bridge = new WsAgentCallBridge({
+    runId,
+    sendRequest: handlers.sendAgentCall
+  });
+  const host = new McpHost({ runId, router: bridge.router });
+  const client = new AcpClient({
+    command: spec.command,
+    args: spec.args,
+    env: spec.env,
+    cwd: spec.cwd
+  });
+  client.onSessionUpdate((p) => translateUpdate(p.update, handlers.onLog));
+  client.onStderr((chunk) => handlers.onLog("stderr", chunk));
+  const controller = {
+    onAgentCallResult(msg) {
+      bridge.onResult(msg);
+    }
+  };
+  const promise = (async () => {
+    let result = { exitCode: 1, stopReason: "uninitialized" };
+    try {
+      await host.start();
+      client.start();
+      await client.initialize({
+        protocolVersion: ACP_PROTOCOL_VERSION,
+        clientCapabilities: {}
+      });
+      const session = await client.newSession({
+        cwd: spec.cwd ?? process.cwd(),
+        mcpServers: [host.acpServerEntry()]
+      });
+      const prompt = buildPromptContent(acpSpec);
+      const promptResult = await client.prompt({
+        sessionId: session.sessionId,
+        prompt
+      });
+      result = {
+        exitCode: promptResult.stopReason === "end_turn" ? 0 : 1,
+        stopReason: promptResult.stopReason
+      };
+      return result;
+    } finally {
+      bridge.shutdown("acp run ended");
+      await Promise.race([
+        host.stop().catch(() => void 0),
+        new Promise((r) => setTimeout(r, 3e3))
+      ]);
+      await Promise.race([
+        client.close(
+          /* graceMs */
+          1e3
+        ).catch(() => void 0),
+        new Promise((r) => setTimeout(r, 5e3))
+      ]);
+    }
+  })();
+  return { promise, controller };
+}
+function buildPromptContent(acp) {
+  const parts = [];
+  if (acp.systemPromptMd.trim().length > 0) {
+    parts.push(`# System prompt
+
+${acp.systemPromptMd.trim()}`);
+  }
+  if (acp.pageContextJson && acp.pageContextJson.trim().length > 0) {
+    parts.push(`# Page context (JSON)
+
+\`\`\`json
+${acp.pageContextJson}
+\`\`\``);
+  }
+  const history = acp.history ?? [];
+  if (history.length > 0) {
+    const turns = history.map((t) => `**${t.role}**: ${t.text}`).join("\n\n");
+    parts.push(`# Conversation history
+
+${turns}`);
+  }
+  parts.push(`# Current message
+
+${acp.userPromptMd}`);
+  return [{ type: "text", text: parts.join("\n\n---\n\n") }];
+}
+function translateUpdate(update, onLog) {
+  if (isMessageChunk(update)) {
+    if (update.sessionUpdate === "user_message_chunk") {
+      return;
+    }
+    const text = textOfContent(update.content);
+    if (!text) return;
+    if (update.sessionUpdate === "agent_thought_chunk") {
+      onLog("stdout", `[think] ${text}`);
+      return;
+    }
+    onLog("stdout", text);
+    return;
+  }
+  if (isToolCallStart(update)) {
+    const status2 = update.status ?? "?";
+    onLog("stdout", `
+[tool] ${update.title} (${status2})
+`);
+    return;
+  }
+  if (isToolCallProgress(update)) {
+    const status2 = update.status ?? "?";
+    const title = update.title ?? "(tool)";
+    onLog("stdout", `
+[tool] ${title} \u2192 ${status2}
+`);
+    return;
+  }
+  onLog("stderr", `[acp] unmodeled update: ${update.sessionUpdate}
+`);
+}
+function textOfContent(content) {
+  if (content.type !== "text") return "";
+  return content.text ?? "";
+}
+
+// src/runner/spawn.ts
 function runJob(spec, stdinJson, handlers) {
   return new Promise((resolve, reject) => {
-    const child = spawn2(spec.command, spec.args ?? [], {
+    const child = spawn3(spec.command, spec.args ?? [], {
       env: { ...process.env, ...spec.env ?? {} },
       cwd: spec.cwd,
       stdio: ["pipe", "pipe", "pipe"]
@@ -492,7 +1258,7 @@ var AgentCallParser = class {
 };
 
 // src/commands/run.ts
-var PKG_VERSION = "0.102.0";
+var PKG_VERSION = "0.103.0";
 var LOG_FLUSH_MS = 800;
 var MAX_CHUNK_SIZE = 4 * 1024;
 async function run(opts = {}) {
@@ -529,6 +1295,7 @@ async function run(opts = {}) {
   console.log(`[opencara] starting as ${cfg.deviceName} (${hostname2()})`);
   client.start();
 }
+var acpControllers = /* @__PURE__ */ new Map();
 function handleServerMessage(msg, client, _cfg) {
   if (msg.type === "hello-ack") {
     console.log(`[opencara] acked as ${msg.deviceName} (${msg.agentHostId})`);
@@ -537,6 +1304,11 @@ function handleServerMessage(msg, client, _cfg) {
   if (msg.type === "ping") return;
   if (msg.type === "job") {
     void executeJob(msg, client);
+    return;
+  }
+  if (msg.type === "agent-call-result") {
+    acpControllers.get(msg.runId)?.onAgentCallResult(msg);
+    return;
   }
 }
 async function executeJob(job, client) {
@@ -563,6 +1335,41 @@ async function executeJob(job, client) {
     if (flushTimer) return;
     flushTimer = setTimeout(flush, LOG_FLUSH_MS);
   };
+  if (job.spec.acp) {
+    const handle = runAcpJob({
+      runId,
+      spec: job.spec,
+      handlers: {
+        onLog: (stream, chunk) => {
+          pending[stream] += chunk;
+          scheduleFlush();
+        },
+        sendAgentCall: (req) => client.send(req)
+      }
+    });
+    acpControllers.set(runId, handle.controller);
+    try {
+      const result = await handle.promise;
+      flush();
+      client.send({
+        type: "done",
+        runId,
+        status: result.exitCode === 0 ? "succeeded" : "failed",
+        exitCode: result.exitCode
+      });
+      console.log(
+        `[opencara] job ${runId.slice(-8)} (acp) \u2192 ${result.stopReason} exit=${result.exitCode}`
+      );
+    } catch (err) {
+      flush();
+      const message = err instanceof Error ? err.message : String(err);
+      client.send({ type: "done", runId, status: "failed", errorMessage: message });
+      console.error(`[opencara] job ${runId.slice(-8)} (acp) failed`, message);
+    } finally {
+      acpControllers.delete(runId);
+    }
+    return;
+  }
   const callParser = new AgentCallParser((call) => {
     switch (call.kind) {
       case "issue.body.set":
@@ -690,9 +1497,20 @@ async function logout() {
 
 // src/commands/internal.ts
 import { execFileSync } from "node:child_process";
-import { mkdtempSync, rmSync, existsSync as existsSync2, realpathSync } from "node:fs";
-import { tmpdir } from "node:os";
+import {
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  rmSync,
+  existsSync as existsSync3,
+  realpathSync,
+  writeFileSync as writeFileSync2,
+  renameSync
+} from "node:fs";
+import { homedir as homedir2 } from "node:os";
 import { join as join2, sep } from "node:path";
+var OPENCARA_ROOT = join2(homedir2(), ".opencara");
+var WORK_ROOT = join2(OPENCARA_ROOT, "work");
+var SESSION_ROOT = join2(OPENCARA_ROOT, "sessions");
 async function internal(argv) {
   const sub = argv[0];
   const rest = argv.slice(1);
@@ -701,18 +1519,26 @@ async function internal(argv) {
     const opArgs = rest.slice(1);
     if (op === "create") return worktreeCreate(opArgs);
     if (op === "remove") return worktreeRemove(opArgs);
+    if (op === "write-session") return worktreeWriteSession(opArgs);
     fail(`unknown worktree op: ${op ?? "(none)"}`);
   }
   fail(`unknown internal subcommand: ${sub ?? "(none)"}`);
 }
+function safeKey(rawKey) {
+  return rawKey.split("/").map((part) => part.replace(/[^A-Za-z0-9._-]/g, "_")).filter((s) => s.length > 0).join(sep);
+}
 function worktreeCreate(args) {
   const repo = pickFlag(args, "--repo");
   const branch = pickFlag(args, "--branch");
   const fromRaw = pickFlag(args, "--from-branch") ?? "";
   const fromBranch = fromRaw.length > 0 ? fromRaw : null;
+  const rawKey = pickFlag(args, "--key") ?? pickFlag(args, "--session-key");
   if (!repo || !branch) {
     fail("worktree create requires --repo OWNER/NAME and --branch <name>");
   }
+  if (!rawKey) {
+    fail("worktree create requires --key <slug>");
+  }
   if (!/^[\w.-]+\/[\w.-]+$/.test(repo)) {
     fail(`invalid --repo '${repo}' (expected OWNER/NAME)`);
   }
@@ -723,48 +1549,113 @@ function worktreeCreate(args) {
   if (!/^[\w-]+$/.test(token)) {
     fail("GH_TOKEN contains unexpected characters; refusing to use");
   }
-  const dir = mkdtempSync(join2(tmpdir(), "opencara-wt-"));
+  const key = safeKey(rawKey);
+  if (!key) fail(`invalid --key '${rawKey}'`);
+  const sessionDir = join2(SESSION_ROOT, key);
+  const checkoutDir = join2(WORK_ROOT, key, "checkout");
   const HELPER_SNIPPET = '!f() { echo username=x-access-token; echo "password=$GH_TOKEN"; }; f';
   const cleanUrl = `https://github.com/${repo}.git`;
-  const cloneArgs = ["-c", `credential.helper=${HELPER_SNIPPET}`, "clone", "--depth=1"];
-  if (fromBranch) {
-    cloneArgs.push("--branch", fromBranch);
+  mkdirSync2(sessionDir, { recursive: true });
+  if (existsSync3(join2(checkoutDir, ".git"))) {
+    git(checkoutDir, ["fetch", "origin"]);
+    git(checkoutDir, ["checkout", "-B", branch, `origin/${branch}`]);
+  } else {
+    mkdirSync2(checkoutDir, { recursive: true });
+    const cloneArgs = ["-c", `credential.helper=${HELPER_SNIPPET}`, "clone"];
+    if (fromBranch) {
+      cloneArgs.push("--branch", fromBranch);
+    }
+    cloneArgs.push(cleanUrl, ".");
+    try {
+      git(checkoutDir, cloneArgs);
+      if (fromBranch && branch === fromBranch) {
+        git(checkoutDir, ["checkout", branch]);
+      } else {
+        git(checkoutDir, ["checkout", "-b", branch]);
+      }
+      git(checkoutDir, ["config", "credential.helper", HELPER_SNIPPET]);
+    } catch (err) {
+      try {
+        rmSync(checkoutDir, { recursive: true, force: true });
+      } catch {
+      }
+      throw err;
+    }
   }
-  cloneArgs.push(cleanUrl, ".");
-  try {
-    git(dir, cloneArgs);
-    git(dir, ["checkout", "-b", branch]);
-    git(dir, ["config", "credential.helper", HELPER_SNIPPET]);
-  } catch (err) {
+  let priorSession = null;
+  const sessionFile = join2(sessionDir, "agent-session.json");
+  if (existsSync3(sessionFile)) {
     try {
-      rmSync(dir, { recursive: true, force: true });
+      const parsed = JSON.parse(readFileSync2(sessionFile, "utf8"));
+      if (typeof parsed.kind === "string" && typeof parsed.id === "string") {
+        priorSession = { kind: parsed.kind, id: parsed.id };
+      }
     } catch {
     }
-    throw err;
   }
-  process.stdout.write(`${JSON.stringify({ workdir: dir, branch })}
-`);
+  process.stdout.write(
+    `${JSON.stringify({
+      workdir: checkoutDir,
+      branch,
+      sessionDir,
+      priorSession
+    })}
+`
+  );
 }
-function worktreeRemove(args) {
-  const workdir = pickFlag(args, "--workdir");
-  if (!workdir) {
-    fail("worktree remove requires --workdir <path>");
+function worktreeWriteSession(args) {
+  const dir = pickFlag(args, "--session-dir");
+  const kind = pickFlag(args, "--kind");
+  const id = pickFlag(args, "--id");
+  if (!dir || !kind || !id) {
+    fail("worktree write-session requires --session-dir <path> --kind <k> --id <id>");
   }
-  if (!existsSync2(workdir)) {
-    return;
-  }
-  const tmp = realpathSync(tmpdir());
+  mkdirSync2(SESSION_ROOT, { recursive: true });
+  const root = realpathSync(SESSION_ROOT);
   let resolved;
   try {
-    resolved = realpathSync(workdir);
+    resolved = realpathSync(dir);
   } catch (err) {
-    if (err.code === "ENOENT") return;
-    fail(`worktree remove: cannot resolve ${workdir}: ${err.message}`);
+    fail(`worktree write-session: cannot resolve ${dir}: ${err.message}`);
+  }
+  if (resolved !== root && !resolved.startsWith(root + sep)) {
+    fail(`worktree write-session: refuses to write to ${resolved} (not under ${root})`);
+  }
+  if (!/^[\w-]+$/.test(kind)) {
+    fail(`worktree write-session: invalid --kind '${kind}'`);
   }
-  if (resolved !== tmp && !resolved.startsWith(tmp + sep)) {
-    fail(`worktree remove: refuses to remove ${resolved} (not under ${tmp})`);
+  if (id.length === 0 || id.length > 200) {
+    fail("worktree write-session: --id must be 1..200 chars");
+  }
+  const dst = join2(resolved, "agent-session.json");
+  const tmp = `${dst}.tmp`;
+  writeFileSync2(tmp, JSON.stringify({ kind, id }) + "\n", { encoding: "utf8" });
+  renameSync(tmp, dst);
+}
+function worktreeRemove(args) {
+  const rawKey = pickFlag(args, "--key");
+  if (!rawKey) {
+    fail("worktree remove requires --key <slug>");
+  }
+  const key = safeKey(rawKey);
+  if (!key) fail(`invalid --key '${rawKey}'`);
+  mkdirSync2(OPENCARA_ROOT, { recursive: true });
+  const opencaraRoot = realpathSync(OPENCARA_ROOT);
+  for (const subtreeRoot of [WORK_ROOT, SESSION_ROOT]) {
+    const target = join2(subtreeRoot, key);
+    if (!existsSync3(target)) continue;
+    let resolved;
+    try {
+      resolved = realpathSync(target);
+    } catch (err) {
+      if (err.code === "ENOENT") continue;
+      fail(`worktree remove: cannot resolve ${target}: ${err.message}`);
+    }
+    if (!resolved.startsWith(opencaraRoot + sep)) {
+      fail(`worktree remove: refuses to remove ${resolved} (not under ${opencaraRoot})`);
+    }
+    rmSync(resolved, { recursive: true, force: true });
   }
-  rmSync(resolved, { recursive: true, force: true });
 }
 function git(cwd, args) {
   execFileSync("git", args, { cwd, stdio: ["ignore", "ignore", "inherit"] });