opencara 0.109.0 → 0.112.1

package/dist/bin.js

@@ -82,6 +82,12 @@ var AcpHistoryTurnSchema = z3.object({
   role: z3.enum(["user", "assistant"]),
   text: z3.string()
 });
+var AcpImageInputSchema = z3.object({
+  /** Base64-encoded image bytes, without the `data:<mime>;base64,` prefix. */
+  data: z3.string(),
+  /** IANA image MIME type, e.g. `image/png`, `image/jpeg`, `image/webp`. */
+  mimeType: z3.string()
+});
 var AcpPermissionModeSchema = z3.enum([
   "default",
   "acceptEdits",
@@ -94,7 +100,10 @@ var AcpSpecSchema = z3.object({
   history: z3.array(AcpHistoryTurnSchema).default([]),
   pageContextJson: z3.string().optional(),
   priorSessionId: z3.string().optional(),
-  permissionMode: AcpPermissionModeSchema.optional()
+  permissionMode: AcpPermissionModeSchema.optional(),
+  instructionsFile: z3.string().optional(),
+  images: z3.array(AcpImageInputSchema).default([]),
+  model: z3.string().optional()
 });
 var AgentSpecSchema = z3.object({
   kind: z3.string(),
@@ -143,6 +152,8 @@ var PairingStatusResponseSchema = z4.union([
 var PairingConfirmRequestSchema = z4.object({
   device_name: z4.string().min(1)
 });
+var HOST_PROTOCOL_VERSION = 1;
+var WS_CLOSE_PROTOCOL_TOO_OLD = 4400;
 var SystemInfoSchema = z4.object({
   os: z4.string(),
   // os.platform()
@@ -172,6 +183,12 @@ var HelloMessageSchema = z4.object({
   type: z4.literal("hello"),
   platform: z4.string(),
   version: z4.string(),
+  /**
+   * HOST_PROTOCOL_VERSION the device speaks. Absent from CLIs published
+   * before versioning existed — the server treats absent as 0 and gates
+   * on MIN_HOST_PROTOCOL_VERSION.
+   */
+  protocolVersion: z4.number().int().nonnegative().optional(),
   capabilities: z4.array(z4.string()).default([]),
   systemInfo: SystemInfoSchema.optional()
 });
@@ -203,12 +220,22 @@ var RunDoneSchema = z4.object({
 var HelloAckSchema = z4.object({
   type: z4.literal("hello-ack"),
   agentHostId: z4.string(),
-  deviceName: z4.string()
+  deviceName: z4.string(),
+  /**
+   * Server's HOST_PROTOCOL_VERSION. Optional so old servers (which don't
+   * send it) still satisfy new clients' parse; clients use it only to log
+   * a version-skew warning, never to gate.
+   */
+  protocolVersion: z4.number().int().nonnegative().optional()
 });
 var CancelJobSchema = z4.object({
   type: z4.literal("cancel"),
   runId: z4.string(),
-  reason: z4.enum(["user_stopped", "wave_cancelled"])
+  // `.catch()` — not a bare enum — so a future server that grows a new
+  // reason (e.g. "timeout") degrades on THIS client to "user_stopped"
+  // instead of failing the whole frame's parse and silently dropping the
+  // cancel, which left the job unkillable on pre-versioning CLIs.
+  reason: z4.enum(["user_stopped", "wave_cancelled"]).catch("user_stopped")
 });
 var PingSchema = z4.object({ type: z4.literal("ping") });
 var PongSchema = z4.object({ type: z4.literal("pong") });
@@ -309,6 +336,13 @@ var DeviceToServerMessageSchema = z4.union([
   PongSchema,
   AgentCallRequestSchema
 ]);
+var SERVER_TO_DEVICE_TYPES = /* @__PURE__ */ new Set([
+  "job",
+  "hello-ack",
+  "ping",
+  "agent-call-result",
+  "cancel"
+]);
 var HostRegisterRequestSchema = z4.object({
   hostId: z4.string(),
   hostName: z4.string(),
@@ -350,6 +384,9 @@ var IssueDetailSchema = IssueSummarySchema.extend({
   draftUpdatedAt: z5.string().datetime().nullable()
 });
 
+// ../shared/dist/cron.js
+var MAX_STEP_MINUTES = 366 * 24 * 60 + 24 * 60;
+
 // src/commands/register.ts
 var POLL_INTERVAL_MS = 2e3;
 async function register(opts = {}) {
@@ -422,6 +459,23 @@ function sleep(ms) {
 
 // src/transport/ws-client.ts
 import WebSocket from "ws";
+function classifyServerFrame(raw) {
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return { kind: "malformed", error: "not JSON" };
+  }
+  const type = typeof json === "object" && json !== null && "type" in json ? json.type : void 0;
+  if (typeof type === "string" && !SERVER_TO_DEVICE_TYPES.has(type)) {
+    return { kind: "unknown-type", type };
+  }
+  const parsed = ServerToDeviceMessageSchema.safeParse(json);
+  if (!parsed.success) {
+    return { kind: "malformed", error: parsed.error.message };
+  }
+  return { kind: "ok", msg: parsed.data };
+}
 var HEARTBEAT_MS = 3e4;
 var WsClient = class {
   constructor(opts) {
@@ -433,6 +487,8 @@ var WsClient = class {
   backoff;
   heartbeat = null;
   stopped = false;
+  /** Unknown frame types already warned about (once per type, not per frame). */
+  warnedUnknownTypes = /* @__PURE__ */ new Set();
   start() {
     this.connect();
   }
@@ -461,18 +517,28 @@ var WsClient = class {
       this.opts.onOpen?.();
     });
     ws.on("message", (raw) => {
-      let parsed;
-      try {
-        parsed = ServerToDeviceMessageSchema.parse(JSON.parse(raw.toString()));
-      } catch (err) {
-        console.error("[ws] invalid frame", err);
+      const frame = classifyServerFrame(raw.toString());
+      if (frame.kind === "unknown-type") {
+        if (!this.warnedUnknownTypes.has(frame.type)) {
+          this.warnedUnknownTypes.add(frame.type);
+          console.warn(
+            `[ws] ignoring unknown frame type "${frame.type}" \u2014 the server is likely newer than this CLI; consider \`npm i -g opencara\``
+          );
+        }
+        return;
+      }
+      if (frame.kind === "malformed") {
+        console.error("[ws] invalid frame:", frame.error);
         return;
       }
-      this.opts.onMessage(parsed);
+      this.opts.onMessage(frame.msg);
     });
     ws.on("close", (code, reasonBuf) => {
       const reason = reasonBuf.toString();
       if (this.heartbeat) clearInterval(this.heartbeat);
+      if (code === WS_CLOSE_PROTOCOL_TOO_OLD) {
+        this.stopped = true;
+      }
       this.opts.onClose?.(code, reason);
       if (!this.stopped) this.scheduleReconnect();
     });
@@ -546,6 +612,7 @@ var ACP_METHODS = {
   session_load: "session/load",
   session_prompt: "session/prompt",
   session_cancel: "session/cancel",
+  session_set_config_option: "session/set_config_option",
   // Client methods (agent → client) — handled minimally in this spike.
   session_update: "session/update",
   session_request_permission: "session/request_permission",
@@ -601,6 +668,15 @@ var AcpConnection = class {
   prompt(req) {
     return this.request(ACP_METHODS.session_prompt, req);
   }
+  /**
+   * Select a session config option (e.g. the model) advertised by the agent in
+   * the session/new response. pi-acp maps `configId: "model"` onto its model
+   * selector. Resolves on success; rejects with the agent's JSON-RPC error
+   * (e.g. "Model not found") — callers log and continue rather than fail the run.
+   */
+  setConfigOption(req) {
+    return this.request(ACP_METHODS.session_set_config_option, req);
+  }
   /** Notification (no reply). Used to cancel a turn mid-flight. */
   cancel(sessionId) {
     this.notify(ACP_METHODS.session_cancel, { sessionId });
@@ -765,6 +841,9 @@ var AcpClient = class {
   prompt(req) {
     return this.must().prompt(req);
   }
+  setConfigOption(req) {
+    return this.must().setConfigOption(req);
+  }
   cancel(sessionId) {
     this.must().cancel(sessionId);
   }
@@ -1152,21 +1231,35 @@ function runAcpJob(opts) {
       const cwd = spec.cwd ?? process.cwd();
       const mcpServers = [host.acpServerEntry()];
       const shimSupportsLoad = initResult.agentCapabilities?.loadSession === true;
+      const instructionsExtra = acpSpec.instructionsFile ? { instructionsFile: acpSpec.instructionsFile } : {};
       let sessionId;
       let resumed = false;
+      let configOptions;
       if (acpSpec.priorSessionId && shimSupportsLoad) {
-        await client.loadSession({
+        const loaded = await client.loadSession({
           sessionId: acpSpec.priorSessionId,
           cwd,
-          mcpServers
+          mcpServers,
+          ...instructionsExtra
         });
         sessionId = acpSpec.priorSessionId;
         resumed = true;
+        configOptions = loaded.configOptions;
       } else {
-        const session = await client.newSession({ cwd, mcpServers });
+        const session = await client.newSession({ cwd, mcpServers, ...instructionsExtra });
         sessionId = session.sessionId;
+        configOptions = session.configOptions;
       }
       activeSessionId = sessionId;
+      if (acpSpec.model) {
+        await selectAcpModel(
+          client,
+          sessionId,
+          acpSpec.model,
+          configOptions,
+          handlers.onLog
+        );
+      }
       if (cancelRequested) {
         try {
           client.cancel(sessionId);
@@ -1232,7 +1325,68 @@ ${turns}`);
   parts.push(`# Current message
 
 ${acp.userPromptMd}`);
-  return [{ type: "text", text: parts.join("\n\n---\n\n") }];
+  const blocks = [{ type: "text", text: parts.join("\n\n---\n\n") }];
+  for (const img of acp.images ?? []) {
+    blocks.push({ type: "image", data: img.data, mimeType: img.mimeType });
+  }
+  return blocks;
+}
+function matchModelValue(requested, values) {
+  const want = requested.trim();
+  if (!want) return void 0;
+  const exact = values.find((v) => v === want);
+  if (exact) return exact;
+  const ci = values.find((v) => v.toLowerCase() === want.toLowerCase());
+  if (ci) return ci;
+  const suffix = `/${want.toLowerCase()}`;
+  return values.find((v) => v.toLowerCase().endsWith(suffix));
+}
+async function selectAcpModel(client, sessionId, requested, configOptions, onLog) {
+  const modelOption = configOptions?.find(
+    (o) => o.id === "model" || o.category === "model"
+  );
+  if (!modelOption) {
+    onLog(
+      "stderr",
+      `[acp] model "${requested}" requested but the agent advertised no model option; using its default
+`
+    );
+    return;
+  }
+  const values = (modelOption.options ?? []).map((o) => o.value);
+  const target = matchModelValue(requested, values);
+  if (!target) {
+    try {
+      await client.setConfigOption({
+        sessionId,
+        configId: modelOption.id,
+        value: requested.trim()
+      });
+      onLog("stderr", `[acp] selected model ${requested.trim()} (freeform)
+`);
+    } catch {
+      onLog(
+        "stderr",
+        `[acp] model "${requested}" not among available models [${values.join(", ")}]; using the default
+`
+      );
+    }
+    return;
+  }
+  if (modelOption.currentValue === target) return;
+  try {
+    await client.setConfigOption({
+      sessionId,
+      configId: modelOption.id,
+      value: target
+    });
+    onLog("stderr", `[acp] selected model ${target}
+`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    onLog("stderr", `[acp] model selection failed (${msg}); using the default
+`);
+  }
 }
 function createUpdateTranslator(onLog) {
   let inThought = false;
@@ -1312,7 +1466,7 @@ function resolveLocalAcpAdapter(command, args) {
 }
 
 // src/commands/run.ts
-var PKG_VERSION = "0.109.0";
+var PKG_VERSION = "0.112.1";
 var LOG_FLUSH_MS = 800;
 var MAX_CHUNK_SIZE = 4 * 1024;
 async function run(opts = {}) {
@@ -1332,6 +1486,7 @@ async function run(opts = {}) {
         type: "hello",
         platform: platform(),
         version: PKG_VERSION,
+        protocolVersion: HOST_PROTOCOL_VERSION,
         // Advertise ACP transport support. Pre-v0.30 devices reported
         // "agent-call" (the fenced-stdout-block protocol); since the
         // legacy path was removed, this version reports "acp" so the
@@ -1342,6 +1497,14 @@ async function run(opts = {}) {
     },
     onMessage: (msg) => handleServerMessage(msg, client, cfg),
     onClose: (code, reason) => {
+      if (code === WS_CLOSE_PROTOCOL_TOO_OLD) {
+        console.error(
+          `[opencara] this CLI's protocol is too old for the orchestrator: ${reason}`
+        );
+        console.error("[opencara] upgrade with: npm i -g opencara");
+        process.exitCode = 1;
+        return;
+      }
       console.log(`[opencara] disconnected (code=${code} reason="${reason}")`);
     }
   });
@@ -1352,6 +1515,11 @@ var acpControllers = /* @__PURE__ */ new Map();
 function handleServerMessage(msg, client, _cfg) {
   if (msg.type === "hello-ack") {
     console.log(`[opencara] acked as ${msg.deviceName} (${msg.agentHostId})`);
+    if (msg.protocolVersion !== void 0 && msg.protocolVersion !== HOST_PROTOCOL_VERSION) {
+      console.warn(
+        `[opencara] protocol skew: server v${msg.protocolVersion}, CLI v${HOST_PROTOCOL_VERSION}` + (msg.protocolVersion > HOST_PROTOCOL_VERSION ? " \u2014 consider `npm i -g opencara`" : "")
+      );
+    }
     return;
   }
   if (msg.type === "ping") return;
@@ -1599,7 +1767,7 @@ import {
   symlinkSync
 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { join as join2, sep } from "node:path";
+import { dirname as dirname3, 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");
@@ -1662,17 +1830,24 @@ function worktreeCreate(args) {
   const cleanUrl = `https://github.com/${repo}.git`;
   mkdirSync2(sessionDir, { recursive: true });
   if (cacheDir) {
+    const cacheLockPath = `${cacheDir}.lock`;
+    mkdirSync2(dirname3(cacheLockPath), { recursive: true });
     if (existsSync4(join2(cacheDir, ".git"))) {
-      git(cacheDir, ["fetch", "--all", "--prune"], gitEnv);
+      gitLocked(cacheDir, ["fetch", "--all", "--prune"], cacheLockPath, gitEnv);
     } else {
       mkdirSync2(cacheDir, { recursive: true });
       try {
-        git(
+        gitLocked(
           cacheDir,
           ["-c", `credential.helper=${HELPER_SNIPPET}`, "clone", cleanUrl, "."],
+          cacheLockPath,
           gitEnv
         );
-        git(cacheDir, ["config", "credential.helper", HELPER_SNIPPET]);
+        gitLocked(
+          cacheDir,
+          ["config", "credential.helper", HELPER_SNIPPET],
+          cacheLockPath
+        );
       } catch (err) {
         try {
           if (!existsSync4(join2(cacheDir, ".git", "HEAD"))) {
@@ -1684,7 +1859,7 @@ function worktreeCreate(args) {
       }
     }
     if (useLfs) {
-      git(cacheDir, ["lfs", "fetch", "--all"], gitEnv);
+      gitLocked(cacheDir, ["lfs", "fetch", "--all"], cacheLockPath, gitEnv);
       mkdirSync2(join2(cacheDir, ".git", "lfs", "objects"), { recursive: true });
     }
   }
@@ -1831,6 +2006,17 @@ function git(cwd, args, env) {
     env: env ?? process.env
   });
 }
+function gitLocked(cwd, args, lockPath, env) {
+  execFileSync(
+    "flock",
+    ["--exclusive", lockPath, "git", ...args],
+    {
+      cwd,
+      stdio: ["ignore", "ignore", "inherit"],
+      env: env ?? process.env
+    }
+  );
+}
 function refExists(cwd, ref) {
   try {
     execFileSync("git", ["rev-parse", "--verify", "--quiet", ref], {

package/dist/claude-acp.js

@@ -3,6 +3,8 @@
 // src/bin/claude-acp.ts
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, normalize, resolve as pathResolve, sep } from "node:path";
 import { stdin, stdout, stderr, exit } from "node:process";
 
 // src/acp/framing.ts
@@ -99,7 +101,176 @@ function buildClaudeMcpConfig(servers) {
   return JSON.stringify({ mcpServers });
 }
 var sessions = /* @__PURE__ */ new Map();
-async function runClaudeTurn(sessionId, state, promptText, permissionMode) {
+var extraClaudeArgs = [];
+function _setExtraClaudeArgsForTest(args) {
+  extraClaudeArgs = args;
+}
+function parseModelFromArgs(args) {
+  let model;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    const eq = /^(?:--model|-m)=(.*)$/.exec(a);
+    if (eq && eq[1]) {
+      model = eq[1];
+      continue;
+    }
+    if ((a === "--model" || a === "-m") && args[i + 1] !== void 0) {
+      model = args[i + 1];
+      i++;
+    }
+  }
+  return model;
+}
+function modelConfigOptions(state) {
+  const effective = state.modelOverride ?? parseModelFromArgs(extraClaudeArgs);
+  if (!effective) return void 0;
+  return [
+    {
+      type: "select",
+      id: "model",
+      category: "model",
+      name: "Model",
+      currentValue: effective,
+      options: [{ value: effective }]
+    }
+  ];
+}
+function handleSetConfigOption(params) {
+  const sessionId = typeof params.sessionId === "string" ? params.sessionId : "";
+  const state = sessions.get(sessionId);
+  if (!state) {
+    throw new Error(`session/set_config_option: unknown session '${sessionId}'`);
+  }
+  if (params.configId !== "model") {
+    throw new Error(
+      `session/set_config_option: unknown configId '${String(params.configId)}'`
+    );
+  }
+  const value = typeof params.value === "string" ? params.value.trim() : "";
+  if (!value) {
+    throw new Error("session/set_config_option: value must be a non-empty string");
+  }
+  state.modelOverride = value;
+  return {};
+}
+var INSTRUCTIONS_FILE_MAX_BYTES = 64 * 1024;
+function resolveInstructionsFile(cwd, relative) {
+  if (!relative || typeof relative !== "string" || relative.length === 0) {
+    return null;
+  }
+  if (!isAbsolute(cwd)) {
+    stderr.write(
+      `[claude-acp] instructionsFile skipped: cwd '${cwd}' is not absolute
+`
+    );
+    return null;
+  }
+  if (isAbsolute(relative) || /^[A-Za-z]:[\\/]/.test(relative)) {
+    stderr.write(
+      `[claude-acp] instructionsFile skipped: '${relative}' must be repo-relative
+`
+    );
+    return null;
+  }
+  if (relative.split(/[\\/]/).includes("..")) {
+    stderr.write(
+      `[claude-acp] instructionsFile skipped: '${relative}' contains '..'
+`
+    );
+    return null;
+  }
+  const normalizedCwd = normalize(cwd);
+  const candidate = pathResolve(normalizedCwd, relative);
+  const cwdWithSep = normalizedCwd.endsWith(sep) ? normalizedCwd : `${normalizedCwd}${sep}`;
+  if (!candidate.startsWith(cwdWithSep) && candidate !== normalizedCwd) {
+    stderr.write(
+      `[claude-acp] instructionsFile skipped: '${candidate}' escapes cwd
+`
+    );
+    return null;
+  }
+  let realCwd;
+  let realCandidate;
+  try {
+    realCwd = realpathSync(normalizedCwd);
+  } catch (err) {
+    stderr.write(
+      `[claude-acp] instructionsFile skipped: cwd '${normalizedCwd}' realpath failed: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return null;
+  }
+  try {
+    realCandidate = realpathSync(candidate);
+  } catch (err) {
+    stderr.write(
+      `[claude-acp] instructionsFile skipped: '${relative}' not found in cwd (${err instanceof Error ? err.message : String(err)})
+`
+    );
+    return null;
+  }
+  const realCwdWithSep = realCwd.endsWith(sep) ? realCwd : `${realCwd}${sep}`;
+  if (!realCandidate.startsWith(realCwdWithSep) && realCandidate !== realCwd) {
+    stderr.write(
+      `[claude-acp] instructionsFile skipped: '${relative}' resolves to '${realCandidate}' which is outside cwd (symlink escape?)
+`
+    );
+    return null;
+  }
+  let stat;
+  try {
+    stat = statSync(realCandidate);
+  } catch (err) {
+    stderr.write(
+      `[claude-acp] instructionsFile skipped: '${relative}' stat failed: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return null;
+  }
+  if (!stat.isFile()) {
+    stderr.write(
+      `[claude-acp] instructionsFile skipped: '${relative}' is not a regular file
+`
+    );
+    return null;
+  }
+  if (stat.size > INSTRUCTIONS_FILE_MAX_BYTES) {
+    stderr.write(
+      `[claude-acp] instructionsFile skipped: '${relative}' is ${stat.size} bytes (> ${INSTRUCTIONS_FILE_MAX_BYTES} cap)
+`
+    );
+    return null;
+  }
+  let content;
+  try {
+    content = readFileSync(realCandidate, "utf8");
+  } catch (err) {
+    stderr.write(
+      `[claude-acp] instructionsFile skipped: read failed for '${relative}': ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return null;
+  }
+  return { path: realCandidate, content };
+}
+function buildStreamJsonInput(promptText, images) {
+  const content = [];
+  if (promptText.length > 0) {
+    content.push({ type: "text", text: promptText });
+  }
+  for (const img of images) {
+    content.push({
+      type: "image",
+      source: { type: "base64", media_type: img.mimeType, data: img.data }
+    });
+  }
+  return `${JSON.stringify({
+    type: "user",
+    message: { role: "user", content }
+  })}
+`;
+}
+async function runClaudeTurn(sessionId, state, promptText, images, permissionMode) {
   return new Promise((resolve, reject) => {
     const idFlag = state.resume ? "--resume" : "--session-id";
     const args = [
@@ -114,6 +285,10 @@ async function runClaudeTurn(sessionId, state, promptText, permissionMode) {
       idFlag,
       sessionId
     ];
+    const useStreamJsonInput = images.length > 0;
+    if (useStreamJsonInput) {
+      args.push("--input-format", "stream-json");
+    }
     if (permissionMode && permissionMode !== "default") {
       args.push("--permission-mode", permissionMode);
     } else {
@@ -126,6 +301,19 @@ async function runClaudeTurn(sessionId, state, promptText, permissionMode) {
         "--strict-mcp-config"
       );
     }
+    const resolvedInstructions = resolveInstructionsFile(
+      state.cwd,
+      state.instructionsFile
+    );
+    if (resolvedInstructions) {
+      args.push("--bare", "--append-system-prompt", resolvedInstructions.content);
+    }
+    if (extraClaudeArgs.length > 0) {
+      args.push(...extraClaudeArgs);
+    }
+    if (state.modelOverride) {
+      args.push("--model", state.modelOverride);
+    }
     const child = spawn("claude", args, {
       cwd: state.cwd,
       env: process.env,
@@ -134,7 +322,9 @@ async function runClaudeTurn(sessionId, state, promptText, permissionMode) {
     state.activeChild = child;
     child.stdin.on("error", () => {
     });
-    child.stdin.end(promptText);
+    child.stdin.end(
+      useStreamJsonInput ? buildStreamJsonInput(promptText, images) : promptText
+    );
     const decoder = new FrameDecoder();
     let resolved = false;
     let stopReason = "end_turn";
@@ -339,7 +529,9 @@ function handleInitialize(_params) {
       // on each turn (see SessionState.mcpServers / runClaudeTurn).
       loadSession: true,
       mcpCapabilities: {},
-      promptCapabilities: { embeddedContext: false, image: false, audio: false }
+      // image: true since #142 — image blocks are forwarded to claude via
+      // `--input-format stream-json`. embeddedContext / audio still unsupported.
+      promptCapabilities: { embeddedContext: false, image: true, audio: false }
     },
     authMethods: []
   };
@@ -347,24 +539,37 @@ function handleInitialize(_params) {
 function handleNewSession(params) {
   const sessionId = randomUUID();
   const mcpServers = normalizeMcpServers(params.mcpServers);
-  sessions.set(sessionId, {
+  const instructionsFile = normalizeInstructionsFile(params.instructionsFile);
+  const state = {
     cwd: params.cwd ?? process.cwd(),
     resume: false,
-    ...mcpServers.length > 0 ? { mcpServers } : {}
-  });
-  return { sessionId };
+    ...mcpServers.length > 0 ? { mcpServers } : {},
+    ...instructionsFile ? { instructionsFile } : {}
+  };
+  sessions.set(sessionId, state);
+  const configOptions = modelConfigOptions(state);
+  return { sessionId, ...configOptions ? { configOptions } : {} };
 }
 function handleLoadSession(params) {
   if (typeof params.sessionId !== "string" || params.sessionId.length === 0) {
     throw new Error("session/load: sessionId required");
   }
   const mcpServers = normalizeMcpServers(params.mcpServers);
-  sessions.set(params.sessionId, {
+  const instructionsFile = normalizeInstructionsFile(params.instructionsFile);
+  const state = {
     cwd: params.cwd ?? process.cwd(),
     resume: true,
-    ...mcpServers.length > 0 ? { mcpServers } : {}
-  });
-  return {};
+    ...mcpServers.length > 0 ? { mcpServers } : {},
+    ...instructionsFile ? { instructionsFile } : {}
+  };
+  sessions.set(params.sessionId, state);
+  const configOptions = modelConfigOptions(state);
+  return configOptions ? { configOptions } : {};
+}
+function normalizeInstructionsFile(raw) {
+  if (typeof raw !== "string") return void 0;
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
 }
 async function handlePrompt(params) {
   const state = sessions.get(params.sessionId);
@@ -372,13 +577,17 @@ async function handlePrompt(params) {
     throw new Error(`unknown sessionId: ${params.sessionId}`);
   }
   const promptText = params.prompt.filter((b) => b.type === "text").map((b) => typeof b.text === "string" ? b.text : "").join("\n\n");
-  if (promptText.length === 0) {
-    throw new Error("session/prompt: no text content blocks");
+  const images = params.prompt.filter(
+    (b) => b.type === "image" && typeof b.data === "string" && b.data.length > 0 && typeof b.mimeType === "string" && b.mimeType.length > 0
+  ).map((b) => ({ type: "image", data: b.data, mimeType: b.mimeType }));
+  if (promptText.length === 0 && images.length === 0) {
+    throw new Error("session/prompt: no text or image content blocks");
   }
   const result = await runClaudeTurn(
     params.sessionId,
     state,
     promptText,
+    images,
     params.permissionMode
   );
   state.resume = true;
@@ -400,6 +609,8 @@ function handleCancel(params) {
 }
 var isMainModule = import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("claude-acp.ts") === true || process.argv[1]?.endsWith("claude-acp.js") === true;
 if (isMainModule) {
+  extraClaudeArgs = process.argv.slice(2);
+  Object.freeze(extraClaudeArgs);
   const decoder = new FrameDecoder();
   stdin.setEncoding("utf8");
   stdin.on("data", (chunk) => {
@@ -438,6 +649,14 @@ async function dispatch(msg) {
       case "session/load":
         reply(req.id, handleLoadSession(req.params));
         return;
+      case "session/set_config_option":
+        reply(
+          req.id,
+          handleSetConfigOption(
+            req.params
+          )
+        );
+        return;
       case "session/prompt": {
         const result = await handlePrompt(req.params);
         reply(req.id, result);
@@ -452,7 +671,7 @@ async function dispatch(msg) {
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    const isParamsError = err instanceof Error && (message.startsWith("session/prompt:") || message.startsWith("session/load:"));
+    const isParamsError = err instanceof Error && (message.startsWith("session/prompt:") || message.startsWith("session/load:") || message.startsWith("session/set_config_option:"));
     replyError(
       req.id,
       isParamsError ? JSON_RPC_ERROR_INVALID_PARAMS : JSON_RPC_ERROR_INTERNAL,
@@ -461,9 +680,16 @@ async function dispatch(msg) {
   }
 }
 export {
+  _setExtraClaudeArgsForTest,
+  buildStreamJsonInput,
+  extraClaudeArgs,
   handleInitialize,
   handleLoadSession,
   handleNewSession,
+  handleSetConfigOption,
+  modelConfigOptions,
+  parseModelFromArgs,
+  resolveInstructionsFile,
   sessions,
   translateClaudeEvent
 };

package/dist/opencara-mcp.js

@@ -123,6 +123,12 @@ var AcpHistoryTurnSchema = z2.object({
   role: z2.enum(["user", "assistant"]),
   text: z2.string()
 });
+var AcpImageInputSchema = z2.object({
+  /** Base64-encoded image bytes, without the `data:<mime>;base64,` prefix. */
+  data: z2.string(),
+  /** IANA image MIME type, e.g. `image/png`, `image/jpeg`, `image/webp`. */
+  mimeType: z2.string()
+});
 var AcpPermissionModeSchema = z2.enum([
   "default",
   "acceptEdits",
@@ -135,7 +141,10 @@ var AcpSpecSchema = z2.object({
   history: z2.array(AcpHistoryTurnSchema).default([]),
   pageContextJson: z2.string().optional(),
   priorSessionId: z2.string().optional(),
-  permissionMode: AcpPermissionModeSchema.optional()
+  permissionMode: AcpPermissionModeSchema.optional(),
+  instructionsFile: z2.string().optional(),
+  images: z2.array(AcpImageInputSchema).default([]),
+  model: z2.string().optional()
 });
 var AgentSpecSchema = z2.object({
   kind: z2.string(),
@@ -213,6 +222,12 @@ var HelloMessageSchema = z3.object({
   type: z3.literal("hello"),
   platform: z3.string(),
   version: z3.string(),
+  /**
+   * HOST_PROTOCOL_VERSION the device speaks. Absent from CLIs published
+   * before versioning existed — the server treats absent as 0 and gates
+   * on MIN_HOST_PROTOCOL_VERSION.
+   */
+  protocolVersion: z3.number().int().nonnegative().optional(),
   capabilities: z3.array(z3.string()).default([]),
   systemInfo: SystemInfoSchema.optional()
 });
@@ -244,12 +259,22 @@ var RunDoneSchema = z3.object({
 var HelloAckSchema = z3.object({
   type: z3.literal("hello-ack"),
   agentHostId: z3.string(),
-  deviceName: z3.string()
+  deviceName: z3.string(),
+  /**
+   * Server's HOST_PROTOCOL_VERSION. Optional so old servers (which don't
+   * send it) still satisfy new clients' parse; clients use it only to log
+   * a version-skew warning, never to gate.
+   */
+  protocolVersion: z3.number().int().nonnegative().optional()
 });
 var CancelJobSchema = z3.object({
   type: z3.literal("cancel"),
   runId: z3.string(),
-  reason: z3.enum(["user_stopped", "wave_cancelled"])
+  // `.catch()` — not a bare enum — so a future server that grows a new
+  // reason (e.g. "timeout") degrades on THIS client to "user_stopped"
+  // instead of failing the whole frame's parse and silently dropping the
+  // cancel, which left the job unkillable on pre-versioning CLIs.
+  reason: z3.enum(["user_stopped", "wave_cancelled"]).catch("user_stopped")
 });
 var PingSchema = z3.object({ type: z3.literal("ping") });
 var PongSchema = z3.object({ type: z3.literal("pong") });
@@ -391,6 +416,9 @@ var IssueDetailSchema = IssueSummarySchema.extend({
   draftUpdatedAt: z4.string().datetime().nullable()
 });
 
+// ../shared/dist/cron.js
+var MAX_STEP_MINUTES = 366 * 24 * 60 + 24 * 60;
+
 // src/mcp/tools.ts
 var issueBodySetShape = IssueBodySetCallSchema.omit({
   type: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencara",
-  "version": "0.109.0",
+  "version": "0.112.1",
   "description": "OpenCara agent-host CLI: register a machine as an agent host and run dispatched agents.",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
     "dev": "tsx watch src/bin.ts",
     "start": "node dist/bin.js",
     "typecheck": "tsc -b",
-    "test": "node --import tsx --test --test-reporter=spec src/acp/__tests__/*.test.ts src/mcp/__tests__/*.test.ts src/runner/__tests__/*.test.ts src/bin/__tests__/*.test.ts src/commands/__tests__/*.test.ts",
+    "test": "node --import tsx --test --test-reporter=spec src/acp/__tests__/*.test.ts src/mcp/__tests__/*.test.ts src/runner/__tests__/*.test.ts src/bin/__tests__/*.test.ts src/commands/__tests__/*.test.ts src/transport/__tests__/*.test.ts",
     "acp:spike": "tsx src/acp/spike.ts",
     "mcp:smoke": "tsx src/mcp/smoke.ts",
     "clean": "rm -rf dist *.tsbuildinfo"