opencara 0.109.0 → 0.110.0

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(),
@@ -350,6 +359,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 = {}) {
@@ -546,6 +558,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 +614,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 +787,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 +1177,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 +1271,58 @@ ${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) {
+    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 +1402,7 @@ function resolveLocalAcpAdapter(command, args) {
 }
 
 // src/commands/run.ts
-var PKG_VERSION = "0.109.0";
+var PKG_VERSION = "0.110.0";
 var LOG_FLUSH_MS = 800;
 var MAX_CHUNK_SIZE = 4 * 1024;
 async function run(opts = {}) {
@@ -1599,7 +1689,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 +1752,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 +1781,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 +1928,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,125 @@ function buildClaudeMcpConfig(servers) {
   return JSON.stringify({ mcpServers });
 }
 var sessions = /* @__PURE__ */ new Map();
-async function runClaudeTurn(sessionId, state, promptText, permissionMode) {
+var extraClaudeArgs = [];
+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 +234,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 +250,16 @@ 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);
+    }
     const child = spawn("claude", args, {
       cwd: state.cwd,
       env: process.env,
@@ -134,7 +268,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 +475,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,10 +485,12 @@ function handleInitialize(_params) {
 function handleNewSession(params) {
   const sessionId = randomUUID();
   const mcpServers = normalizeMcpServers(params.mcpServers);
+  const instructionsFile = normalizeInstructionsFile(params.instructionsFile);
   sessions.set(sessionId, {
     cwd: params.cwd ?? process.cwd(),
     resume: false,
-    ...mcpServers.length > 0 ? { mcpServers } : {}
+    ...mcpServers.length > 0 ? { mcpServers } : {},
+    ...instructionsFile ? { instructionsFile } : {}
   });
   return { sessionId };
 }
@@ -359,26 +499,37 @@ function handleLoadSession(params) {
     throw new Error("session/load: sessionId required");
   }
   const mcpServers = normalizeMcpServers(params.mcpServers);
+  const instructionsFile = normalizeInstructionsFile(params.instructionsFile);
   sessions.set(params.sessionId, {
     cwd: params.cwd ?? process.cwd(),
     resume: true,
-    ...mcpServers.length > 0 ? { mcpServers } : {}
+    ...mcpServers.length > 0 ? { mcpServers } : {},
+    ...instructionsFile ? { instructionsFile } : {}
   });
   return {};
 }
+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);
   if (!state) {
     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 +551,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) => {
@@ -461,9 +614,12 @@ async function dispatch(msg) {
   }
 }
 export {
+  buildStreamJsonInput,
+  extraClaudeArgs,
   handleInitialize,
   handleLoadSession,
   handleNewSession,
+  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(),
@@ -391,6 +400,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.110.0",
   "description": "OpenCara agent-host CLI: register a machine as an agent host and run dispatched agents.",
   "license": "MIT",
   "repository": {