@cabane/companion 0.6.142 → 0.6.144

package/dist/runtime.js

@@ -17,14 +17,14 @@ import { z as z2 } from "zod";
 
 // src/errors.ts
 var CompanionError = class extends Error {
-  constructor(message) {
-    super(message);
+  constructor(message2) {
+    super(message2);
     this.name = "CompanionError";
   }
 };
 var ApiError = class extends CompanionError {
-  constructor(status, message, body) {
-    super(message);
+  constructor(status, message2, body) {
+    super(message2);
     this.status = status;
     this.body = body;
     this.name = "ApiError";
@@ -33,14 +33,14 @@ var ApiError = class extends CompanionError {
   body;
 };
 var ConfigError = class extends CompanionError {
-  constructor(message) {
-    super(message);
+  constructor(message2) {
+    super(message2);
     this.name = "ConfigError";
   }
 };
 var PrepareHookError = class extends CompanionError {
-  constructor(message) {
-    super(message);
+  constructor(message2) {
+    super(message2);
     this.name = "PrepareHookError";
   }
 };
@@ -1202,8 +1202,8 @@ function formatHumanLine(record) {
   let line = `${time}  ${word ? `${word}  ` : ""}${context ? `${context}  ` : ""}${humanText(record.msg)}`;
   const err = record.err;
   const errorRecord = err !== null && typeof err === "object" ? err : null;
-  const message = humanText(errorRecord && "message" in errorRecord ? errorRecord.message : err);
-  const detail = typeof record.status === "number" ? `HTTP ${record.status}: ${humanText(record.responseBody) || message}` : message;
+  const message2 = humanText(errorRecord && "message" in errorRecord ? errorRecord.message : err);
+  const detail = typeof record.status === "number" ? `HTTP ${record.status}: ${humanText(record.responseBody) || message2}` : message2;
   if (detail && !line.includes(detail)) line += ` (${detail})`;
   if (level < 30) {
     const hidden = /* @__PURE__ */ new Set([
@@ -1337,9 +1337,9 @@ var CompanionStateHub = class {
     if (info.deviceLabel !== void 0) this.deviceLabel = info.deviceLabel;
     this.emitStatus();
   }
-  setDeviceError(message) {
-    if (this.deviceError === message) return;
-    this.deviceError = message;
+  setDeviceError(message2) {
+    if (this.deviceError === message2) return;
+    this.deviceError = message2;
     this.emitStatus();
   }
   clearDeviceError() {
@@ -1960,7 +1960,7 @@ async function warnAboutHarnessReadiness(cfg, deps = {}) {
   const probeClaude = deps.probeClaude ?? claudeOnPath;
   const probeCodex = deps.probeCodex ?? codexOnPath;
   const resolveBundled = deps.resolveBundled ?? ((runtime) => resolveBundledBinary(runtime));
-  const warn = deps.warn ?? ((message) => process.stderr.write(`${message}
+  const warn = deps.warn ?? ((message2) => process.stderr.write(`${message2}
 `));
   const connected = [
     ...isClaudeCodeConnected(cfg) ? ["Claude Code"] : [],
@@ -2305,8 +2305,8 @@ function apiErrorCode(err) {
 function apiErrorMessage(err) {
   const body = err instanceof ApiError ? err.body : void 0;
   if (body !== null && typeof body === "object") {
-    const message = body.message;
-    if (typeof message === "string" && message.length > 0) return message;
+    const message2 = body.message;
+    if (typeof message2 === "string" && message2.length > 0) return message2;
   }
   return err instanceof Error ? err.message : String(err);
 }
@@ -2341,9 +2341,9 @@ function describeErrorBody(body) {
 }
 var CAUSE_TEXT_CAP = 200;
 function describeError(err) {
-  const message = err instanceof Error ? err.message : String(err);
+  const message2 = err instanceof Error ? err.message : String(err);
   const cause = describeCause(err);
-  return cause === void 0 ? message : `${message}: ${cause}`;
+  return cause === void 0 ? message2 : `${message2}: ${cause}`;
 }
 function describeCause(err) {
   if (!(err instanceof Error)) return void 0;
@@ -3309,14 +3309,11 @@ var turnEventSchema = z6.discriminatedUnion("type", [
   // claude-code/codex it's the runtime's CUMULATIVE total summed across every model
   // request in the agentic turn, so it grows with the tool-call count and is NOT
   // "how full is the window." `contextTokens` is the distinct CONTEXT-OCCUPANCY
-  // read: the input the model saw on its FINAL request of the turn (uncached +
-  // cache, since cached tokens still occupy the window) — the number the composer
-  // gauge wants. `contextWindow` is the model's true window in tokens when the
-  // runtime reports it (claude-code's SDK does, per model) — a real denominator so
-  // the gauge can show a fraction. Both optional: a runtime that can't source a
-  // clean final-request figure (codex's cumulative-only usage) omits `contextTokens`
-  // and the gauge falls back to the raw count; `contextWindow` falls back to the
-  // model catalog.
+  // read and `contextWindow` the window it is measured against, both as the
+  // harness reported them (claude-code's `getContextUsage`, or its final
+  // request's input and `modelUsage` window when that call gives nothing). A
+  // runtime that can't source them (codex's cumulative-only usage) omits both,
+  // and no surface shows a reading for that turn.
   //
   // CT601: two more optional carry-homes on the terminal result, alongside
   // `usage`. `resolvedModel` is the CONCRETE model the runtime actually ran —
@@ -3339,7 +3336,25 @@ var turnEventSchema = z6.discriminatedUnion("type", [
       cacheReadTokens: z6.number().optional(),
       cacheCreationTokens: z6.number().optional(),
       contextTokens: z6.number().optional(),
-      contextWindow: z6.number().optional()
+      contextWindow: z6.number().optional(),
+      // CT1751: the rest of the harness's own context reading, when it gave
+      // one: where it will compact, its `/context` breakdown, and every
+      // compaction it reported during the turn. Claude Code only.
+      contextCompactAt: z6.number().optional(),
+      contextCategories: z6.array(
+        z6.object({
+          name: z6.string(),
+          tokens: z6.number(),
+          kind: z6.enum(["used", "free", "buffer", "deferred"])
+        })
+      ).optional(),
+      contextCompactions: z6.array(
+        z6.object({
+          trigger: z6.enum(["manual", "auto"]),
+          preTokens: z6.number(),
+          postTokens: z6.number().optional()
+        })
+      ).optional()
     }).optional(),
     resolvedModel: z6.string().optional(),
     resolvedConfig: z6.object({
@@ -4294,6 +4309,7 @@ async function* decodeSdkStream(iter, ctx) {
   let resultReason;
   let sawResult = false;
   let usage;
+  const compactions = [];
   let lastRequestContextTokens;
   let resolvedModel;
   const signals = { sawRejectedLimit: false };
@@ -4319,6 +4335,9 @@ async function* decodeSdkStream(iter, ctx) {
             ...ctx.degraded ? { degraded: true } : {}
           };
         }
+      } else if (msg.type === "system" && msg.subtype === "compact_boundary") {
+        const compaction = readCompaction(msg);
+        if (compaction) compactions.push(compaction);
       } else if (!workspaceProven && (msg.type === "assistant" || msg.type === "user" || msg.type === "result")) {
         if (preInitToolActivity(msg) && ctx.startEvidence) ctx.startEvidence.toolActivity = true;
         const failure = classifyPreInitFrame(msg, signals);
@@ -4363,6 +4382,9 @@ async function* decodeSdkStream(iter, ctx) {
             usage.contextTokens = lastRequestContextTokens;
           const window = readContextWindow(msg, resolvedModel);
           if (window !== void 0) usage.contextWindow = window;
+          if (compactions.length > 0) usage.contextCompactions = compactions;
+          const reading = await readHarnessContext(ctx.readContextUsage);
+          if (reading) Object.assign(usage, reading);
         }
         const isError = msg.is_error === true;
         if (msg.subtype === "success" && !isError) {
@@ -4378,15 +4400,15 @@ async function* decodeSdkStream(iter, ctx) {
     }
   } catch (err) {
     if (ctx.signal.aborted) throw err;
-    const message = err instanceof Error ? err.message : String(err);
-    const failure = mcpInventory.initReceived ? classifyErrorText(message) : classifyFailure(signals, { text: message });
+    const message2 = err instanceof Error ? err.message : String(err);
+    const failure = mcpInventory.initReceived ? classifyErrorText(message2) : classifyFailure(signals, { text: message2 });
     if (!failure && (mcpInventory.initReceived || ctx.resumedSessionId === null)) throw err;
     ok = false;
     if (failure) {
       resultReason = encodeFailureReason(failure);
     } else {
       resultReason = "session_start_failed";
-      if (ctx.startEvidence) ctx.startEvidence.thrown = message.slice(0, 200);
+      if (ctx.startEvidence) ctx.startEvidence.thrown = message2.slice(0, 200);
     }
     sawResult = true;
   }
@@ -4514,6 +4536,58 @@ function readRequestContextTokens(msg) {
   const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : 0;
   return num(usage.input_tokens) + num(usage.cache_read_input_tokens) + num(usage.cache_creation_input_tokens);
 }
+var CONTEXT_READING_TIMEOUT_MS = 2e3;
+async function readHarnessContext(read) {
+  if (!read) return void 0;
+  let timer;
+  const timeout = new Promise((resolve2) => {
+    timer = setTimeout(() => resolve2(void 0), CONTEXT_READING_TIMEOUT_MS);
+  });
+  try {
+    return parseContextUsage(await Promise.race([read(), timeout]));
+  } catch {
+    return void 0;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var CATEGORY_KINDS = /* @__PURE__ */ new Set(["used", "free", "buffer", "deferred"]);
+function parseContextUsage(response) {
+  const r = response;
+  if (!r || typeof r !== "object") return void 0;
+  const count = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.round(v) : void 0;
+  const total = count(r.totalTokens);
+  const window = count(r.maxTokens);
+  if (total === void 0 || window === void 0 || window === 0) return void 0;
+  const categories = [];
+  for (const c of Array.isArray(r.categories) ? r.categories : []) {
+    const row = c;
+    const tokens = count(row?.tokens);
+    if (typeof row?.name === "string" && tokens !== void 0 && typeof row.kind === "string" && CATEGORY_KINDS.has(row.kind)) {
+      categories.push({ name: row.name, tokens, kind: row.kind });
+    }
+  }
+  const buffer = categories.filter((c) => c.kind === "buffer").reduce((sum, c) => sum + c.tokens, 0);
+  return {
+    contextTokens: total,
+    contextWindow: window,
+    ...buffer > 0 && buffer < window ? { contextCompactAt: window - buffer } : {},
+    ...categories.length > 0 ? { contextCategories: categories } : {}
+  };
+}
+function readCompaction(msg) {
+  const meta = msg.compact_metadata;
+  const count = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.round(v) : void 0;
+  const preTokens = count(meta?.pre_tokens);
+  if (!meta || preTokens === void 0) return void 0;
+  if (meta.trigger !== "manual" && meta.trigger !== "auto") return void 0;
+  const postTokens = count(meta.post_tokens);
+  return {
+    trigger: meta.trigger,
+    preTokens,
+    ...postTokens !== void 0 ? { postTokens } : {}
+  };
+}
 function readContextWindow(msg, resolvedModel) {
   const modelUsage = msg.modelUsage;
   if (!modelUsage || typeof modelUsage !== "object") return void 0;
@@ -4531,7 +4605,7 @@ function readContextWindow(msg, resolvedModel) {
 }
 
 // packages/agent-runtime/src/claude-code/prompt-input.ts
-function buildQueryPrompt(req) {
+function buildQueryPrompt(req, openUntil) {
   const content = req.content;
   return (async function* () {
     yield {
@@ -4540,6 +4614,7 @@ function buildQueryPrompt(req) {
       message: { role: "user", content },
       parent_tool_use_id: null
     };
+    if (openUntil) await openUntil;
   })();
 }
 
@@ -4551,19 +4626,34 @@ function attachAbortController(options, signal) {
   else signal.addEventListener("abort", () => sdkAbort.abort(), { once: true });
   options.abortController = sdkAbort;
 }
-function sdkEvents(queryFn, req, signal, built, degraded, startEvidence) {
+async function* sdkEvents(queryFn, req, signal, built, degraded, startEvidence) {
   attachAbortController(built.options, signal);
-  const prompt = buildQueryPrompt(req);
-  const iter = {
-    [Symbol.asyncIterator]: () => queryFn({ prompt, options: built.options })[Symbol.asyncIterator]()
+  let release = () => {
   };
-  return decodeSdkStream(iter, {
-    signal,
-    cwd: req.local.cwd,
-    resumedSessionId: built.resume,
-    degraded,
-    ...startEvidence ? { startEvidence } : {}
+  const held = new Promise((resolve2) => {
+    release = resolve2;
   });
+  const prompt = buildQueryPrompt(req, held);
+  let active;
+  const iter = {
+    [Symbol.asyncIterator]: () => {
+      const q = queryFn({ prompt, options: built.options });
+      active = q;
+      return q[Symbol.asyncIterator]();
+    }
+  };
+  try {
+    yield* decodeSdkStream(iter, {
+      signal,
+      readContextUsage: async () => typeof active?.getContextUsage === "function" ? active.getContextUsage({ detail: "summary" }) : void 0,
+      cwd: req.local.cwd,
+      resumedSessionId: built.resume,
+      degraded,
+      ...startEvidence ? { startEvidence } : {}
+    });
+  } finally {
+    release();
+  }
 }
 async function freshRequest(req, reason, hooks) {
   const recomposed = hooks?.fresh ? await hooks.fresh(reason) : null;
@@ -5315,9 +5405,9 @@ function readSessionError(properties) {
   if (typeof err === "string") return err;
   const rec = asRecord(err);
   if (!rec) return "unknown";
-  const { name, message } = deepestError(rec);
-  if (message && name && !isGenericErrorName(name)) return `${name}: ${message}`;
-  if (message) return message;
+  const { name, message: message2 } = deepestError(rec);
+  if (message2 && name && !isGenericErrorName(name)) return `${name}: ${message2}`;
+  if (message2) return message2;
   if (name) return name;
   if (typeof rec.name === "string") return rec.name;
   return "unknown";
@@ -5330,10 +5420,10 @@ function deepestError(node) {
   const best = {};
   let current = node;
   for (let depth = 0; current && depth < 8; depth++) {
-    const message = typeof current.message === "string" ? current.message : void 0;
+    const message2 = typeof current.message === "string" ? current.message : void 0;
     const name = typeof current.name === "string" && !isGenericErrorName(current.name) ? current.name : void 0;
-    if (message) {
-      best.message = message;
+    if (message2) {
+      best.message = message2;
       if (name) best.name = name;
     } else if (name && !best.name) {
       best.name = name;
@@ -5924,9 +6014,9 @@ var echoedUserPart = (partId, messageID, text) => ({
   properties: { part: { type: "text", id: partId, messageID, text } }
 });
 var idle = () => ({ type: "session.idle", properties: {} });
-var errored = (message) => ({
+var errored = (message2) => ({
   type: "session.error",
-  properties: { error: { message } }
+  properties: { error: { message: message2 } }
 });
 var sessionEvent2 = (sessionId, directory = DIR, degraded = false) => ({
   type: "session",
@@ -6361,8 +6451,8 @@ function readItemText(item) {
 function readItemMessage(item) {
   return str(item.message) ?? "";
 }
-function isModelMetadataError(message) {
-  return message.includes("Defaulting to fallback metadata");
+function isModelMetadataError(message2) {
+  return message2.includes("Defaulting to fallback metadata");
 }
 function readToolItem(item, eventType) {
   const type = str(item.type);
@@ -6597,11 +6687,11 @@ async function* decodeCodexStream(events, ctx) {
       if (!item) continue;
       const itemType = readItemType(item);
       if (itemType === "error") {
-        const message = readItemMessage(item);
-        if (isModelMetadataError(message)) {
+        const message2 = readItemMessage(item);
+        if (isModelMetadataError(message2)) {
           yield* flushInterim();
           ok = false;
-          reason = `model_unavailable:${message.slice(0, 200)}`;
+          reason = `model_unavailable:${message2.slice(0, 200)}`;
           settled = true;
           break;
         }
@@ -6758,7 +6848,7 @@ var ENV_ENVELOPE_KEYS = [
   "CABANE_CONVERSATION_TITLE",
   "CABANE_HOST_ACCESS"
 ];
-function buildRunSpec2(req, resumeThreadId, instructionsFile = null, threadPromptFingerprint = null) {
+function buildRunSpec2(req, resumeThreadId, instructionsFile = null, threadPromptFingerprint = null, imagePaths = []) {
   const { policy, config } = req;
   const directory = req.local.cwd ?? "";
   const dialect = readCodexDialect(config.runtimeOptions);
@@ -6775,7 +6865,7 @@ function buildRunSpec2(req, resumeThreadId, instructionsFile = null, threadPromp
     skipGitRepoCheck: true,
     ...dialect.modelReasoningEffort ? { modelReasoningEffort: dialect.modelReasoningEffort } : {},
     baseInstructionsFile,
-    input: buildInput(req, promptRidesInput),
+    input: withImages(buildInput(req, promptRidesInput), imagePaths),
     promptRidesInput,
     promptFingerprint,
     config: buildConfig(req, baseInstructionsFile),
@@ -6791,6 +6881,13 @@ function buildInput(req, promptRidesInput) {
 
 ${body}` : body;
 }
+function withImages(text, imagePaths) {
+  if (imagePaths.length === 0) return text;
+  return [
+    { type: "text", text },
+    ...imagePaths.map((path) => ({ type: "local_image", path }))
+  ];
+}
 function buildConfig(req, baseInstructionsFile) {
   const mcp_servers = {};
   for (const [name, server] of Object.entries(req.local.mcpServers ?? {})) {
@@ -7032,12 +7129,35 @@ function createCodexAdapter(deps = {}) {
           }
         }
       }
+      let images = null;
       try {
+        const imageUrls = req.content.flatMap((b) => b.type === "image" ? [b.source.url] : []);
+        if (imageUrls.length > 0) {
+          if (!deps.prepareImages) {
+            deps.onWarn?.(
+              "codex adapter: no image preparer wired on this host \u2014 the turn runs without its images (CT1757)",
+              { images: imageUrls.length }
+            );
+          } else {
+            try {
+              images = await deps.prepareImages(imageUrls, signal);
+            } catch (err) {
+              if (!signal.aborted) {
+                deps.onWarn?.(
+                  "codex adapter: preparing the images failed \u2014 the turn runs without them (CT1757)",
+                  { err: err instanceof Error ? err.message : String(err) }
+                );
+              }
+            }
+          }
+          if (signal.aborted) return;
+        }
         const spec = buildRunSpec2(
           req,
           resumeThreadId,
           instructions?.path ?? null,
-          threadPromptFingerprint
+          threadPromptFingerprint,
+          images?.paths ?? []
         );
         if (spec.model === null) {
           deps.onWarn?.("Codex is using its default model because no model was resolved", {
@@ -7066,6 +7186,15 @@ function createCodexAdapter(deps = {}) {
           resolvedReasoningEffort: spec.modelReasoningEffort ?? null
         });
       } finally {
+        if (images) {
+          try {
+            await images.cleanup();
+          } catch (err) {
+            deps.onWarn?.("codex adapter: image cleanup failed (CT1757)", {
+              err: err instanceof Error ? err.message : String(err)
+            });
+          }
+        }
         if (instructions) {
           try {
             await instructions.cleanup();
@@ -7132,14 +7261,14 @@ var turnCompleted = (usage) => ({
   type: "turn.completed",
   ...usage ? { usage } : {}
 });
-var turnFailed = (message) => ({
+var turnFailed = (message2) => ({
   type: "turn.failed",
-  error: { message }
+  error: { message: message2 }
 });
-var fatalError = (message) => ({ type: "error", message });
-var errorItem = (id, message) => ({
+var fatalError = (message2) => ({ type: "error", message: message2 });
+var errorItem = (id, message2) => ({
   type: "item.completed",
-  item: { id, type: "error", message }
+  item: { id, type: "error", message: message2 }
 });
 var OP_SUCCESS = { ok: true, result: { source: "native" } };
 var OP_FAILURE = {
@@ -8058,7 +8187,7 @@ var ConnectorHealthStore = class {
 // src/dispatcher.ts
 import { randomUUID as randomUUID4 } from "crypto";
 import { existsSync as existsSync10, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 
 // src/runner/launch.ts
 import { createInterface } from "readline";
@@ -8124,8 +8253,8 @@ function unenforceable(policy) {
         deniedDomains: as === "deniedDomains" ? [host] : []
       });
       if (!check.success) {
-        const message = check.error.issues[0]?.message ?? "not a host pattern the sandbox accepts";
-        return `runners.policy.${field}.${i}: ${message}`;
+        const message2 = check.error.issues[0]?.message ?? "not a host pattern the sandbox accepts";
+        return `runners.policy.${field}.${i}: ${message2}`;
       }
     }
   }
@@ -8139,8 +8268,8 @@ function unenforceable(policy) {
       try {
         new RegExp(globToRegex(path));
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return `runners.policy.${field}.${i}: not a pattern the sandbox can match (${message})`;
+        const message2 = err instanceof Error ? err.message : String(err);
+        return `runners.policy.${field}.${i}: not a pattern the sandbox can match (${message2})`;
       }
     }
   }
@@ -8259,8 +8388,8 @@ async function reapTurnScopes(turnId) {
     });
     return { failures: [] };
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return classifyStopError(message) === "absent" ? { failures: [] } : { failures: [message.slice(0, 200)] };
+    const message2 = err instanceof Error ? err.message : String(err);
+    return classifyStopError(message2) === "absent" ? { failures: [] } : { failures: [message2.slice(0, 200)] };
   }
 }
 function scopeCapabilityUsable(env, timeoutMs = CAPABILITY_PROBE_TIMEOUT_MS) {
@@ -8276,13 +8405,13 @@ function scopeCapabilityUsable(env, timeoutMs = CAPABILITY_PROBE_TIMEOUT_MS) {
     return false;
   }
 }
-function classifyStopError(message) {
+function classifyStopError(message2) {
   if (/failed to connect to bus|failed to get d-?bus connection|connection refused|refusing to operate|spawn systemctl|systemctl.*ENOENT|ENOENT.*systemctl/i.test(
-    message
+    message2
   )) {
     return "failure";
   }
-  if (/not loaded|could not be found|no such unit|unit .* not found/i.test(message))
+  if (/not loaded|could not be found|no such unit|unit .* not found/i.test(message2))
     return "absent";
   return "failure";
 }
@@ -8394,9 +8523,9 @@ function createTurnContainment(turnId, deps = {}) {
           timeout: (CONTAINMENT_STOP_GRACE_SEC + 10) * 1e3
         });
       } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (classifyStopError(message) === "failure") {
-          result.failures.push({ target: unit, error: message.slice(0, 200) });
+        const message2 = err instanceof Error ? err.message : String(err);
+        if (classifyStopError(message2) === "failure") {
+          result.failures.push({ target: unit, error: message2.slice(0, 200) });
           continue;
         }
         result.reaped.push(unit);
@@ -8801,8 +8930,8 @@ function runnerStdin(input) {
   })}
 `;
 }
-function encodeLauncherMessage(message) {
-  return `${JSON.stringify(message)}
+function encodeLauncherMessage(message2) {
+  return `${JSON.stringify(message2)}
 `;
 }
 function decodeRunnerEvent(line) {
@@ -9534,6 +9663,68 @@ async function writeCodexInstructionsFile(contents) {
   };
 }
 
+// src/codex-images.ts
+import { mkdtemp as mkdtemp2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join12 } from "path";
+var FETCH_TIMEOUT_MS = 3e4;
+var EXTENSIONS = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp"
+};
+function createCodexImagePreparer(opts) {
+  const doFetch = opts.fetch ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? FETCH_TIMEOUT_MS;
+  return async (urls, signal) => {
+    signal.throwIfAborted();
+    const dir2 = await mkdtemp2(join12(tmpdir2(), `cabane-codex-images-${opts.turnId}-`));
+    const cleanup = async () => {
+      try {
+        await rm2(dir2, { recursive: true, force: true });
+      } catch (err) {
+        opts.warn(
+          { dir: dir2, err: message(err) },
+          "codex images: could not remove the scratch directory"
+        );
+      }
+    };
+    const prepareOne = async (url, index) => {
+      try {
+        const res = await doFetch(url, {
+          signal: AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])
+        });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const type = (res.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+        const ext = EXTENSIONS[type];
+        if (!ext) throw new Error(`not a vision image type: ${type || "none"}`);
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        const path = join12(dir2, `image-${index + 1}.${ext}`);
+        await writeFile2(path, bytes, { mode: 384 });
+        return path;
+      } catch (err) {
+        if (!signal.aborted) {
+          opts.warn(
+            { image: index + 1, of: urls.length, err: message(err) },
+            "codex images: an image could not be prepared; the turn runs without it"
+          );
+        }
+        return null;
+      }
+    };
+    const paths = await Promise.all(urls.map(prepareOne));
+    if (signal.aborted) {
+      await cleanup();
+      signal.throwIfAborted();
+    }
+    return { paths: paths.filter((p) => p !== null), cleanup };
+  };
+}
+function message(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
 // src/turn-seq-floor.ts
 var SeqFloorUnavailable = class extends Error {
   constructor(detail) {
@@ -9571,15 +9762,15 @@ function readOutboxFloor(read, turnId, log) {
 import { spawn as spawn5 } from "child_process";
 import { hostname } from "os";
 function prepareFailureCause(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  if (/timed out/i.test(message)) return "prepare hook timed out";
-  if (/MODULE_NOT_FOUND|Cannot find (?:module|package)/.test(message))
+  const message2 = error instanceof Error ? error.message : String(error);
+  if (/timed out/i.test(message2)) return "prepare hook timed out";
+  if (/MODULE_NOT_FOUND|Cannot find (?:module|package)/.test(message2))
     return "prepare hook module missing; check the configured command and its installation for this device";
-  if (/not valid JSON|JSON must carry|produced no output/.test(message))
+  if (/not valid JSON|JSON must carry|produced no output/.test(message2))
     return "prepare hook returned malformed output; expected a cwd path or JSON with a non-empty cwd";
-  if (/ENOENT/.test(message)) return "prepare hook executable missing (ENOENT)";
-  if (/EACCES/.test(message)) return "prepare hook executable is not accessible (EACCES)";
-  const exit = message.match(/exited with code (\d+)/)?.[1];
+  if (/ENOENT/.test(message2)) return "prepare hook executable missing (ENOENT)";
+  if (/EACCES/.test(message2)) return "prepare hook executable is not accessible (EACCES)";
+  const exit = message2.match(/exited with code (\d+)/)?.[1];
   return exit ? `prepare hook exited with code ${exit}` : "prepare hook failed; inspect the device-local hook log";
 }
 async function runPrepareWithReporting(runner, hook, input, context, reportError) {
@@ -9631,15 +9822,15 @@ function reportFailure(config, body) {
 
 // src/prepared.ts
 import { mkdirSync as mkdirSync7, readFileSync as readFileSync7, rmSync as rmSync5, writeFileSync as writeFileSync5, existsSync as existsSync8 } from "fs";
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 function dirFor(workspaceId) {
-  return join12(cabaneDir(), "prepared", encodeURIComponent(workspaceId));
+  return join13(cabaneDir(), "prepared", encodeURIComponent(workspaceId));
 }
 function conversationDir(workspaceId, conversationId) {
-  return join12(dirFor(workspaceId), encodeURIComponent(conversationId));
+  return join13(dirFor(workspaceId), encodeURIComponent(conversationId));
 }
 function pathFor2(workspaceId, conversationId, agentId) {
-  return join12(conversationDir(workspaceId, conversationId), `${encodeURIComponent(agentId)}.json`);
+  return join13(conversationDir(workspaceId, conversationId), `${encodeURIComponent(agentId)}.json`);
 }
 function readPrepared(workspaceId, conversationId, agentId) {
   const path = pathFor2(workspaceId, conversationId, agentId);
@@ -9671,9 +9862,9 @@ function clearPrepared(workspaceId, conversationId, agentId) {
 
 // src/transcript-writer.ts
 import { appendFileSync, chmodSync as chmodSync4, copyFileSync, mkdirSync as mkdirSync8, readdirSync, rmSync as rmSync6 } from "fs";
-import { basename, dirname as dirname6, join as join13 } from "path";
+import { basename, dirname as dirname6, join as join14 } from "path";
 function transcriptsDir() {
-  return join13(runnerStateDir(), "transcripts");
+  return join14(runnerStateDir(), "transcripts");
 }
 var RETAIN = 200;
 var ANOMALY_RETAIN = 50;
@@ -9683,7 +9874,7 @@ var TranscriptWriter = class {
   onWarn;
   constructor(dir2, meta, onWarn) {
     this.onWarn = onWarn;
-    this.path = join13(dir2, fileName(meta));
+    this.path = join14(dir2, fileName(meta));
     try {
       mkdirSync8(dir2, { recursive: true });
       try {
@@ -9712,10 +9903,10 @@ var TranscriptWriter = class {
   preserveAnomaly() {
     if (this.broken) return;
     try {
-      const dir2 = join13(dirname6(this.path), "anomalies");
+      const dir2 = join14(dirname6(this.path), "anomalies");
       mkdirSync8(dir2, { recursive: true, mode: 448 });
       chmodSync4(dir2, 448);
-      const target = join13(dir2, basename(this.path));
+      const target = join14(dir2, basename(this.path));
       copyFileSync(this.path, target);
       chmodSync4(target, 384);
       pruneOld(dir2, ANOMALY_RETAIN);
@@ -9761,7 +9952,7 @@ function pruneOld(dir2, retain) {
   const drop = files.sort().slice(0, files.length - retain);
   for (const f of drop) {
     try {
-      rmSync6(join13(dir2, f), { force: true });
+      rmSync6(join14(dir2, f), { force: true });
     } catch {
     }
   }
@@ -10332,16 +10523,16 @@ var TurnExecution = class {
   }
   gateTrigger() {
     const { payload, turnLog } = this;
-    const message = this.turnContext.message;
-    const isDispatchableTrigger = message.role === "user" || message.role === "agent" || message.role === "system";
+    const message2 = this.turnContext.message;
+    const isDispatchableTrigger = message2.role === "user" || message2.role === "agent" || message2.role === "system";
     if (!isDispatchableTrigger) {
-      turnLog.debug({ role: message.role }, "dispatcher: trigger role not dispatchable \u2014 skipping");
+      turnLog.debug({ role: message2.role }, "dispatcher: trigger role not dispatchable \u2014 skipping");
       throw this.concluded("unexpected_role", UNEXPECTED_ROLE_REASON);
     }
     this.supervisor.notifyStart({
       id: this.dispatchId,
       conversationId: payload.conversationId,
-      message: message.body
+      message: message2.body
     });
   }
   async resolveSecrets() {
@@ -10692,6 +10883,10 @@ var TurnExecution = class {
           enabled: true,
           onWarn,
           writeInstructionsFile: writeCodexInstructionsFile,
+          prepareImages: createCodexImagePreparer({
+            turnId: this.turnId,
+            warn: (meta, msg) => turnLog.warn(meta, msg)
+          }),
           ...codexPath ? { transport: createSdkCodexTransport({ codexPathOverride: codexPath }) } : {}
         })
       );
@@ -11171,7 +11366,7 @@ function checkoutState(cwd) {
   if (entries.length === 0) {
     return { ok: false, reason: `${cwd} is empty \u2014 a recreated shell, not a prepared directory` };
   }
-  const gitPath = join14(cwd, ".git");
+  const gitPath = join15(cwd, ".git");
   if (!existsSync10(gitPath)) return { ok: true, reason: "usable" };
   let stat;
   try {
@@ -11179,7 +11374,7 @@ function checkoutState(cwd) {
   } catch (error) {
     return { ok: false, reason: `${gitPath} is unreadable (${error.message})` };
   }
-  if (stat.isDirectory() && !existsSync10(join14(gitPath, "HEAD")))
+  if (stat.isDirectory() && !existsSync10(join15(gitPath, "HEAD")))
     return { ok: false, reason: `${gitPath} has no HEAD \u2014 an empty shell, not a checkout` };
   return { ok: true, reason: "usable" };
 }
@@ -11372,7 +11567,7 @@ function createLocalProcessProvider(opts = {}) {
 
 // src/providers/docker.ts
 import { createHash as createHash4, randomUUID as randomUUID5 } from "crypto";
-import { constants as constants2, tmpdir as tmpdir2 } from "os";
+import { constants as constants2, tmpdir as tmpdir3 } from "os";
 import {
   createReadStream,
   createWriteStream as createWriteStream2,
@@ -11385,7 +11580,7 @@ import {
   statSync as statSync3,
   writeFileSync as writeFileSync6
 } from "fs";
-import { join as join17 } from "path";
+import { join as join18 } from "path";
 import { Writable } from "stream";
 
 // src/providers/docker-cli.ts
@@ -11579,7 +11774,7 @@ import {
   renameSync as renameSync4,
   rmSync as rmSync8
 } from "fs";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 function routes(t) {
   const conv = `/api/workspaces/${t.workspaceId}/conversations/${t.conversationId}`;
   const agent = `${conv}/participants/agents/${t.agentId}`;
@@ -11625,7 +11820,7 @@ function publishStaged(from, to, move = atomicMove) {
   const staged = readdirSync3(from).filter((n) => n.endsWith(".json")).map((name) => {
     let entry = {};
     try {
-      entry = JSON.parse(readFileSync8(join15(from, name), "utf8"));
+      entry = JSON.parse(readFileSync8(join16(from, name), "utf8"));
     } catch {
     }
     return { name, entry };
@@ -11638,7 +11833,7 @@ function publishStaged(from, to, move = atomicMove) {
   let published = 0;
   for (const { name } of staged) {
     try {
-      move(join15(from, name), join15(to, name));
+      move(join16(from, name), join16(to, name));
     } catch {
       return { published, complete: false };
     }
@@ -11651,7 +11846,7 @@ function publishStaged(from, to, move = atomicMove) {
 // src/providers/runner-base.ts
 import { createHash as createHash3 } from "crypto";
 import { existsSync as existsSync12, realpathSync as realpathSync2 } from "fs";
-import { dirname as dirname7, join as join16, sep } from "path";
+import { dirname as dirname7, join as join17, sep } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var COMPANION_MOUNT = "/opt/cabane/companion";
 var BASE_DOCKERFILE = `FROM node:22-slim
@@ -11699,11 +11894,11 @@ async function ensureBaseImage(docker, image, log) {
 function ownInstall(moduleFile = fileURLToPath3(import.meta.url)) {
   let dir2 = dirname7(moduleFile);
   for (let i = 0; i < 4; i++) {
-    if (existsSync12(join16(dir2, "dist", "cli.js")) && existsSync12(join16(dir2, "package.json"))) break;
+    if (existsSync12(join17(dir2, "dist", "cli.js")) && existsSync12(join17(dir2, "package.json"))) break;
     dir2 = dirname7(dir2);
   }
-  if (!existsSync12(join16(dir2, "dist", "cli.js"))) return null;
-  const sdk = join16(dir2, "node_modules", "@anthropic-ai", "claude-agent-sdk");
+  if (!existsSync12(join17(dir2, "dist", "cli.js"))) return null;
+  const sdk = join17(dir2, "node_modules", "@anthropic-ai", "claude-agent-sdk");
   if (!existsSync12(sdk)) return null;
   const root = realpathSync2(dir2);
   return realpathSync2(sdk).startsWith(root + sep) ? root : null;
@@ -11842,21 +12037,21 @@ function networkCreateError(stderr) {
 }
 function sessionArchivePath(deviceDir, attemptId) {
   if (!UUID_RE.test(attemptId)) throw new Error(`docker: not an attempt id: ${attemptId}`);
-  return join17(deviceDir, "attempts", attemptId, "session.tar");
+  return join18(deviceDir, "attempts", attemptId, "session.tar");
 }
 function pruneOtherAttempts(deviceDir, pair, keep) {
-  const root = join17(deviceDir, "attempts");
+  const root = join18(deviceDir, "attempts");
   if (!existsSync13(root)) return;
   for (const id of readdirSync4(root)) {
     if (id === keep || !UUID_RE.test(id)) continue;
     let pairOf = "";
     try {
-      pairOf = readFileSync9(join17(root, id, "pair"), "utf8");
+      pairOf = readFileSync9(join18(root, id, "pair"), "utf8");
     } catch {
       continue;
     }
     if (pairOf === `${pair.conversationId}/${pair.agentId}`) {
-      rmSync9(join17(root, id), { recursive: true, force: true });
+      rmSync9(join18(root, id), { recursive: true, force: true });
     }
   }
 }
@@ -12056,11 +12251,11 @@ function createDockerProvider(opts) {
       await must(["network", "disconnect", "-f", other, name], "moving the container");
     if (others.includes(sharedNetwork)) await retireSharedNetwork();
   };
-  const socketRoot = opts.socketRoot ?? join17(
-    process.env.XDG_RUNTIME_DIR && existsSync13(process.env.XDG_RUNTIME_DIR) ? process.env.XDG_RUNTIME_DIR : tmpdir2(),
+  const socketRoot = opts.socketRoot ?? join18(
+    process.env.XDG_RUNTIME_DIR && existsSync13(process.env.XDG_RUNTIME_DIR) ? process.env.XDG_RUNTIME_DIR : tmpdir3(),
     `cabane-runners-${opts.deviceKey}`
   );
-  const socketDir = (name) => join17(socketRoot, createHash4("sha256").update(name).digest("hex").slice(0, 12));
+  const socketDir = (name) => join18(socketRoot, createHash4("sha256").update(name).digest("hex").slice(0, 12));
   const create = async (name, attempt) => {
     mkdirSync10(socketRoot, { recursive: true, mode: 448 });
     mkdirSync10(socketDir(name), { recursive: true, mode: 457 });
@@ -12202,7 +12397,7 @@ function createDockerProvider(opts) {
     }
   };
   const removeIn = (name, from, names) => names.length ? execIn(name, ["sh", "-c", 'cd "$1" && shift && rm -f -- "$@"', "sh", from, ...names]) : Promise.resolve(null);
-  const pendingPath = (name) => join17(opts.deviceDir, "runners-pending", `${name}.json`);
+  const pendingPath = (name) => join18(opts.deviceDir, "runners-pending", `${name}.json`);
   const readPending = (name) => {
     try {
       const ids = JSON.parse(readFileSync9(pendingPath(name), "utf8"));
@@ -12216,12 +12411,12 @@ function createDockerProvider(opts) {
       rmSync9(pendingPath(name), { force: true });
       return;
     }
-    mkdirSync10(join17(opts.deviceDir, "runners-pending"), { recursive: true });
+    mkdirSync10(join18(opts.deviceDir, "runners-pending"), { recursive: true });
     writeFileSync6(pendingPath(name), JSON.stringify([...new Set(ids)]));
   };
   const keepSession = async (name, attempt, attemptId) => {
     const archive = sessionArchivePath(opts.deviceDir, attemptId);
-    mkdirSync10(join17(archive, ".."), { recursive: true });
+    mkdirSync10(join18(archive, ".."), { recursive: true });
     const partial = `${archive}.${process.pid}.partial`;
     const file = new CappedFile(partial, sessionCap);
     const r = await execIn(
@@ -12238,7 +12433,7 @@ function createDockerProvider(opts) {
     );
     if (r.code === 0 && !file.over) {
       renameSync5(partial, archive);
-      writeFileSync6(join17(archive, "..", "pair"), `${attempt.conversationId}/${attempt.agentId}`);
+      writeFileSync6(join18(archive, "..", "pair"), `${attempt.conversationId}/${attempt.agentId}`);
       pruneOtherAttempts(opts.deviceDir, attempt, attemptId);
       await writeMarker(name, attemptId);
       log.debug({ container: name, attemptId, bytes: file.bytes }, "runners: session files kept");
@@ -12252,7 +12447,7 @@ function createDockerProvider(opts) {
       file.over ? "runners: the session files are over the size cap and weren't kept; the next new container starts the session over" : "runners: couldn't keep the session files; the next new container starts the session over"
     );
   };
-  const stagingDir = (name) => join17(opts.deviceDir, "runners-pending", `${name}.outbox`);
+  const stagingDir = (name) => join18(opts.deviceDir, "runners-pending", `${name}.outbox`);
   const ensureRunning = async (name) => {
     const seen = await docker.run(["inspect", "-f", "{{.State.Running}}", name]);
     if (seen.code !== 0) return false;
@@ -12260,7 +12455,7 @@ function createDockerProvider(opts) {
     return (await docker.run(["start", name])).code === 0;
   };
   const dropArchive = (attemptId) => {
-    rmSync9(join17(sessionArchivePath(opts.deviceDir, attemptId), ".."), {
+    rmSync9(join18(sessionArchivePath(opts.deviceDir, attemptId), ".."), {
       recursive: true,
       force: true
     });
@@ -12329,7 +12524,7 @@ function createDockerProvider(opts) {
         if (seen.stdout.trim().split(" ")[0] !== "true")
           await must(["start", name], "starting the container");
         const git = await serveGitCredentials({
-          socketPath: join17(socketDir(name), "git.sock"),
+          socketPath: join18(socketDir(name), "git.sock"),
           hosts: opts.gitHosts,
           fill: opts.gitFill,
           log
@@ -12478,15 +12673,15 @@ function createDockerProvider(opts) {
       const transcripts = await readDir(name, `${CONTAINER_STATE}/transcripts`);
       if (transcripts) {
         const kept = transcripts.files.filter((f) => SAFE_NAME_RE.test(f.name));
-        if (kept.length) mkdirSync10(join17(opts.hostStateDir, "transcripts"), { recursive: true });
-        for (const f of kept) writeFileSync6(join17(opts.hostStateDir, "transcripts", f.name), f.data);
+        if (kept.length) mkdirSync10(join18(opts.hostStateDir, "transcripts"), { recursive: true });
+        for (const f of kept) writeFileSync6(join18(opts.hostStateDir, "transcripts", f.name), f.data);
         await removeIn(
           name,
           `${CONTAINER_STATE}/transcripts`,
           kept.map((f) => f.name)
         );
       }
-      const outboxRel = join17("outbox", encodeURIComponent(attempt.agentId));
+      const outboxRel = join18("outbox", encodeURIComponent(attempt.agentId));
       const outbox = await readDir(name, `${CONTAINER_STATE}/${outboxRel}`);
       let unpublished = false;
       if (outbox) {
@@ -12512,7 +12707,7 @@ function createDockerProvider(opts) {
           const staged = stagingDir(name);
           mkdirSync10(staged, { recursive: true });
           writeFileSync6(
-            join17(staged, `${encodeURIComponent(entry.turnId)}__${entry.seq}.json`),
+            join18(staged, `${encodeURIComponent(entry.turnId)}__${entry.seq}.json`),
             `${JSON.stringify(entry)}
 `
           );
@@ -12525,7 +12720,7 @@ function createDockerProvider(opts) {
         if (outbox.complete) {
           const published = publishStaged(
             stagingDir(name),
-            join17(opts.hostStateDir, outboxRel),
+            join18(opts.hostStateDir, outboxRel),
             opts.moveFile
           );
           queued = published.published;
@@ -12740,8 +12935,8 @@ import {
 } from "fs";
 import { createRequire as createRequire2 } from "module";
 import { isIP } from "net";
-import { homedir as homedir3, networkInterfaces, tmpdir as tmpdir3, userInfo as userInfo2 } from "os";
-import { dirname as dirname8, join as join18, sep as sep2 } from "path";
+import { homedir as homedir3, networkInterfaces, tmpdir as tmpdir4, userInfo as userInfo2 } from "os";
+import { dirname as dirname8, join as join19, sep as sep2 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { SandboxManager } from "@anthropic-ai/sandbox-runtime";
 function accountHome() {
@@ -12951,7 +13146,7 @@ import {
   rmSync as rmSync11,
   writeFileSync as writeFileSync8
 } from "fs";
-import { join as join19 } from "path";
+import { join as join20 } from "path";
 var MAX_ENTRIES = 2e3;
 var MAX_AGE_MS = 24 * 60 * 60 * 1e3;
 var Outbox = class {
@@ -12964,10 +13159,10 @@ var Outbox = class {
   // Resolved lazily (per call, like cursor.ts) so tests that swap HOME between
   // cases route writes at the right tmpdir.
   dir() {
-    return join19(runnerStateDir(), "outbox", encodeURIComponent(this.workspaceId));
+    return join20(runnerStateDir(), "outbox", encodeURIComponent(this.workspaceId));
   }
   fileFor(turnId, seq) {
-    return join19(this.dir(), `${encodeURIComponent(turnId)}__${seq}.json`);
+    return join20(this.dir(), `${encodeURIComponent(turnId)}__${seq}.json`);
   }
   // Persist a commit for later draining. Atomic (temp file + rename) so a
   // concurrent `list()` never reads a half-written entry, then enforces the
@@ -13009,7 +13204,7 @@ var Outbox = class {
     const entries = [];
     for (const name of names) {
       if (!name.endsWith(".json")) continue;
-      const full = join19(dir2, name);
+      const full = join20(dir2, name);
       try {
         const parsed = JSON.parse(readFileSync11(full, "utf8"));
         if (parsed && typeof parsed.turnId === "string" && typeof parsed.seq === "number" && typeof parsed.path === "string") {
@@ -14650,8 +14845,8 @@ function errorCode(err) {
 function isRecoverableSocketError(err) {
   const code = errorCode(err);
   if (code && RECOVERABLE_CODES.has(code)) return true;
-  const message = err instanceof Error ? err.message : String(err);
-  return /\bEPIPE\b|\bECONNRESET\b/.test(message);
+  const message2 = err instanceof Error ? err.message : String(err);
+  return /\bEPIPE\b|\bECONNRESET\b/.test(message2);
 }
 function installProcessSafetyNet(log, opts = {}) {
   const proc = opts.proc ?? process;
@@ -14666,26 +14861,26 @@ function installProcessSafetyNet(log, opts = {}) {
   );
 }
 function handleUncaught(log, err, origin) {
-  const message = err instanceof Error ? err.message : String(err);
+  const message2 = err instanceof Error ? err.message : String(err);
   const code = errorCode(err);
   if (isRecoverableSocketError(err)) {
     log.debug(
-      { origin, code, err: message },
+      { origin, code, err: message2 },
       "companion: recovered from a socket error (kept running \u2014 a broken pipe never kills the companion)"
     );
     return;
   }
   log.error(
-    { origin, code, err: message, stack: err instanceof Error ? err.stack : void 0 },
+    { origin, code, err: message2, stack: err instanceof Error ? err.stack : void 0 },
     "An unexpected error occurred; the companion is still running."
   );
 }
 
 // src/crash-marker.ts
 import { existsSync as existsSync15, mkdirSync as mkdirSync13, readFileSync as readFileSync12, rmSync as rmSync12, writeFileSync as writeFileSync9 } from "fs";
-import { join as join20 } from "path";
+import { join as join21 } from "path";
 function crashMarkerPath() {
-  return join20(cabaneDir(), "last-error.json");
+  return join21(cabaneDir(), "last-error.json");
 }
 function recordCrash(rec) {
   try {