@inetafrica/open-claudia 3.5.14 → 3.5.17

package/core/turn-journal.js

@@ -0,0 +1,506 @@
+// Turn journal: interrupted turns resume after a restart.
+//
+// The project transcript writes a turn's lines when the turn ENDS, messages
+// queued behind a running turn live in memory, and Claude Code only resumes a
+// cut session when the next message happens to arrive. So a restart (planned
+// or a crash) silently lost the turn in flight and everything queued behind
+// it. Now:
+//   - "lock": when a foreground chat turn starts, <config>/turns/<conversation>.json
+//     records what is needed to run it again (conversation, provider, session,
+//     prompt, media, message id), refreshed by a 60 s heartbeat; messages
+//     queued behind it are listed in queued[] until they start. "Unlock" is
+//     deleting the turn on a clean end, a /stop cancel or a reported failure.
+//     While the bot shuts down nothing is unlocked: the kill that ends a turn
+//     then is not the turn's failure.
+//   - boot (after the adapters connect, never in safe mode, RESUME_INTERRUPTED
+//     on by default): a turn cut within RESUME_MAX_AGE_MIN (120) is resumed
+//     once in the conversation's session with a "you were cut off" prompt
+//     (also when the session is lost: the work may be half done); an
+//     older one is offered back with Continue / Drop buttons (kept 24 h); a
+//     turn already resumed twice is not run again (it may be what kills the
+//     bot) and the owner is told. Queued messages are restored in order.
+//   - planned restarts drain: new turns are not admitted (they are journaled
+//     as queued and run after the restart), running turns get DRAIN_TIMEOUT_S
+//     (60) to finish on /restart, /upgrade, /downgrade, and DRAIN_SIGTERM_S
+//     (6) on SIGTERM, whose sender kills soon after; whatever is still
+//     running stays journaled.
+//   - /stop offers each dropped queued message back with a "Run it" button.
+// Scheduled runs (wake-ups, crons, watches) are not journaled: jobs.json keeps
+// their own retry, so they are never resumed twice.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const CONFIG_DIR = require("../config-dir");
+
+const DIR = () => process.env.OC_TURNS_DIR || path.join(CONFIG_DIR, "turns");
+const HEARTBEAT_MS = 60000;
+const ASK_KEEP_MS = 24 * 3600000;
+const DROPPED_KEEP_MS = 24 * 3600000;
+const MAX_ATTEMPTS = 2;
+
+function resumeEnabled() {
+  return !/^(off|false|0|no)$/i.test(String(process.env.RESUME_INTERRUPTED ?? require("./config").config.RESUME_INTERRUPTED ?? "on").trim());
+}
+function maxAgeMs() {
+  const n = Number(process.env.RESUME_MAX_AGE_MIN ?? require("./config").config.RESUME_MAX_AGE_MIN);
+  return (Number.isFinite(n) && n > 0 ? n : 120) * 60000;
+}
+function drainTimeoutMs() {
+  const n = Number(process.env.DRAIN_TIMEOUT_S ?? require("./config").config.DRAIN_TIMEOUT_S);
+  return (Number.isFinite(n) && n >= 0 ? n : 60) * 1000;
+}
+// SIGTERM comes from a supervisor that kills soon after (Agent Space bot pods:
+// terminationGracePeriodSeconds 15; launchd: 20 s). This drain plus the 5 s
+// memory drain after it must fit inside that window.
+function sigtermDrainTimeoutMs() {
+  const n = Number(process.env.DRAIN_SIGTERM_S ?? require("./config").config.DRAIN_SIGTERM_S);
+  return (Number.isFinite(n) && n >= 0 ? n : 6) * 1000;
+}
+
+function idFor(laneKey) {
+  return crypto.createHash("sha1").update(String(laneKey)).digest("hex").slice(0, 12);
+}
+function fileFor(laneKey) {
+  const safe = String(laneKey).replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80);
+  return path.join(DIR(), `${safe}-${idFor(laneKey)}.json`);
+}
+function read(file) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch (_) { return null; }
+}
+function write(file, record) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(record, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+function remove(file) { try { fs.unlinkSync(file); } catch (_) {} }
+
+// Persist the record, or drop the file when nothing is left in it.
+function store(file, record) {
+  if (!record.turn && !(record.queued || []).length) return remove(file);
+  write(file, record);
+}
+
+// A test run that did not point the config dir somewhere else must never
+// leave a turn in the live journal for the real bot to resume at boot.
+function journalOn() {
+  return !(process.env.OPEN_CLAUDIA_TEST === "1" && !process.env.OPEN_CLAUDIA_CONFIG_DIR && !process.env.OC_TURNS_DIR);
+}
+
+// Only a foreground chat turn with a chat to answer in.
+function journalable(runContext) {
+  return journalOn()
+    && !!runContext
+    && runContext.purpose === "foreground"
+    && !runContext.liveCall
+    && !!runContext.origin?.adapterId
+    && !!runContext.channelId;
+}
+
+function conversationOf(runContext) {
+  const origin = runContext.origin || {};
+  return {
+    laneKey: runContext.laneKey,
+    adapterId: origin.adapterId || null,
+    transport: origin.transport || null,
+    channelId: String(runContext.channelId || origin.channelId || ""),
+    threadId: runContext.threadId || null,
+    userId: origin.userId || null,
+    canonicalUserId: runContext.canonicalUserId || origin.canonicalUserId || null,
+  };
+}
+
+function inboundOf(runContext) {
+  return {
+    runId: runContext.runId,
+    prompt: String(runContext.userPrompt || ""),
+    imagePaths: runContext.imagePaths || [],
+    attachments: runContext.attachments || [],
+    replyToMsgId: runContext.replyToMsgId || null,
+  };
+}
+
+let shuttingDown = false;
+let draining = false;
+const active = new Map(); // laneKey -> file of a journaled running turn
+let heartbeat = null;
+
+function ensureHeartbeat(now = Date.now) {
+  if (heartbeat) return;
+  heartbeat = setInterval(() => beat(now()), HEARTBEAT_MS);
+  heartbeat.unref?.();
+}
+
+function beat(at = Date.now()) {
+  for (const file of active.values()) {
+    const record = read(file);
+    if (!record?.turn) continue;
+    record.turn.heartbeatAt = at;
+    try { write(file, record); } catch (_) {}
+  }
+}
+
+// "Lock": a journalable turn starts. A turn re-started by the boot resume
+// keeps its attempt count and its original message.
+function begin(runContext, opts = {}) {
+  if (!journalable(runContext)) return false;
+  const at = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const file = fileFor(runContext.laneKey);
+  const existing = read(file) || {};
+  const carried = existing.turn && existing.turn.resuming ? existing.turn : null;
+  const record = {
+    v: 1,
+    conversation: conversationOf(runContext),
+    turn: {
+      ...inboundOf(runContext),
+      provider: runContext.provider,
+      sessionId: runContext.sessionId || null,
+      project: runContext.project ? { name: runContext.project.name || null, dir: runContext.project.dir || null } : null,
+      originalPrompt: carried ? (carried.originalPrompt || carried.prompt) : String(runContext.userPrompt || ""),
+      startedAt: carried ? carried.startedAt : at,
+      heartbeatAt: at,
+      attempts: carried ? (carried.attempts || 0) : 0,
+    },
+    queued: (existing.queued || []).filter((q) => q.runId !== runContext.runId),
+  };
+  try { write(file, record); } catch (error) { console.warn(`[turn-journal] could not journal ${runContext.laneKey}: ${error.message}`); return false; }
+  active.set(runContext.laneKey, file);
+  ensureHeartbeat();
+  return true;
+}
+
+// "Unlock": the turn ended (cleanly, cancelled or failed). Never while the
+// bot shuts down: that kill is not the turn's end.
+function end(runContext) {
+  if (!journalable(runContext) || shuttingDown) return false;
+  const file = fileFor(runContext.laneKey);
+  const record = read(file);
+  if (!record?.turn || record.turn.runId !== runContext.runId) return false;
+  active.delete(runContext.laneKey);
+  record.turn = null;
+  store(file, record);
+  return true;
+}
+
+// A message waiting behind the running turn (or for a slot).
+function enqueue(runContext, opts = {}) {
+  if (!journalable(runContext)) return false;
+  const file = fileFor(runContext.laneKey);
+  const record = read(file) || { v: 1, conversation: conversationOf(runContext), turn: null, queued: [] };
+  record.conversation = record.conversation || conversationOf(runContext);
+  record.queued = (record.queued || []).filter((q) => q.runId !== runContext.runId);
+  record.queued.push({ ...inboundOf(runContext), provider: runContext.provider, queuedAt: Number.isFinite(opts.now) ? opts.now : Date.now() });
+  try { write(file, record); } catch (_) { return false; }
+  return true;
+}
+
+// Queued messages that will not start (/stop, /new, a project change).
+function dropQueued(laneKey, runIds) {
+  const file = fileFor(laneKey);
+  const record = read(file);
+  if (!record) return;
+  const ids = new Set(runIds);
+  record.queued = (record.queued || []).filter((q) => !ids.has(q.runId));
+  store(file, record);
+}
+
+function list() {
+  if (!journalOn()) return [];
+  let names = [];
+  try { names = fs.readdirSync(DIR()); } catch (_) { return []; }
+  return names.filter((n) => n.endsWith(".json") && n !== "dropped.json")
+    .map((n) => ({ file: path.join(DIR(), n), record: read(path.join(DIR(), n)) }))
+    .filter((x) => x.record && x.record.conversation);
+}
+
+// ── boot resume ─────────────────────────────────────────────────────────
+
+const RESUME_PROMPT = (at, original, { sessionLost = false } = {}) => `You were cut off by a restart at ${at} while working on: ${original}\n\n${sessionLost ? "Your earlier session was lost, so you have no memory of that work: some of it may already be done. " : ""}Check what you already did (your history, git, files, tool state, the chat) before acting; never repeat a send, push, deploy or write that already happened; then finish.`;
+
+function hhmm(ms) {
+  return new Date(ms).toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit", hour12: false });
+}
+function clip(text, n = 80) {
+  const s = String(text || "").replace(/\s+/g, " ").trim();
+  return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+
+function defaultDeps() {
+  const stateApi = require("./state");
+  const { canonicalForChannel, conversationKeyFor } = require("./identity");
+  return {
+    now: Date.now,
+    isSafeMode: () => { try { return require("./safe-mode").isSafeMode(); } catch (_) { return false; } },
+    runInChat: (ctx, fn) => require("./context").runInChat(ctx, fn),
+    runAgent: (...args) => require("./runner").runAgent(...args),
+    send: (...args) => require("./io").send(...args),
+    getUserState: (id) => stateApi.getUserState(id),
+    getProviderSession: (state, provider, project) => stateApi.getProviderSession(state, provider, project),
+    ownerTarget: () => require("./relationship").ownerTarget(),
+    canonicalForChannel, conversationKeyFor,
+  };
+}
+
+function chatScope(conversation, adapter, deps) {
+  const canonical = conversation.canonicalUserId || deps.canonicalForChannel(adapter.type, conversation.channelId);
+  return {
+    adapter,
+    channelId: String(conversation.channelId),
+    canonicalUserId: canonical,
+    userId: String(conversation.userId || (adapter.type === "telegram" ? conversation.channelId : canonical || "")),
+    transport: adapter.type,
+    raw: null,
+    conversationKey: conversation.laneKey,
+    threadId: conversation.threadId || null,
+    roomKey: deps.conversationKeyFor(adapter.type, conversation.channelId),
+  };
+}
+
+function findAdapter(adapters, conversation) {
+  return adapters.find((a) => a.id === conversation.adapterId)
+    || adapters.find((a) => a.type === conversation.transport) || null;
+}
+
+function runQueued(record, adapter, deps) {
+  const queued = record.queued || [];
+  if (!queued.length) return [];
+  const scope = chatScope(record.conversation, adapter, deps);
+  return deps.runInChat(scope, () => queued.map((q) => {
+    const dir = record.turn?.project?.dir || null;
+    return Promise.resolve(deps.runAgent(q.prompt, dir, q.replyToMsgId, {
+      purpose: "foreground", provider: q.provider || undefined,
+      imagePaths: q.imagePaths || [], attachments: q.attachments || [],
+    })).catch((error) => console.warn(`[turn-journal] queued message failed: ${error?.message || error}`));
+  }));
+}
+
+// Run the cut turn again, always with the cut-off prompt: the work may be half
+// done whatever the session, so it is never replayed as a plain message.
+async function runResume(file, record, adapter, deps, { cutAt }) {
+  const turn = record.turn;
+  const scope = chatScope(record.conversation, adapter, deps);
+  turn.attempts = (turn.attempts || 0) + 1;
+  turn.resuming = true;
+  delete turn.askedAt;
+  delete turn.askId;
+  const queued = record.queued || [];
+  record.queued = [];
+  write(file, record);
+  return deps.runInChat(scope, async () => {
+    let state = null;
+    try { state = deps.getUserState(scope.canonicalUserId); } catch (_) { state = null; }
+    const current = state ? deps.getProviderSession(state, turn.provider, turn.project?.name || record.conversation.laneKey) : null;
+    // The conversation's session now holds the cut turn's progress: the one it
+    // resumed, or the one it started (a first turn or a thread fork journals
+    // no id; the provider reports it mid-turn) or moved to (compaction).
+    const sessionId = current || turn.sessionId || null;
+    const sessionLost = !sessionId;
+    const original = turn.originalPrompt || turn.prompt;
+    await Promise.resolve(deps.send(sessionLost
+      ? `Picking up where I was cut off (restart at ${hhmm(cutAt)}). The earlier session is gone, so I'm checking what I already did before carrying on.`
+      : `Picking up where I was cut off (restart at ${hhmm(cutAt)}).`)).catch(() => {});
+    const prompt = RESUME_PROMPT(hhmm(cutAt), original, { sessionLost });
+    const opts = {
+      purpose: "foreground", provider: turn.provider,
+      imagePaths: turn.imagePaths || [], attachments: turn.attachments || [],
+      ...(sessionId ? { resumeSessionId: sessionId } : {}),
+    };
+    const running = Promise.resolve(deps.runAgent(prompt, turn.project?.dir || null, turn.replyToMsgId, opts));
+    // Queued messages follow the resumed turn, in order, in the same lane.
+    runQueued({ ...record, queued }, adapter, deps);
+    return running;
+  });
+}
+
+async function tellOwner(text, adapters, deps) {
+  try {
+    const target = await deps.ownerTarget();
+    const adapter = target && (adapters.find((a) => a.id === target.adapter) || adapters.find((a) => a.type === target.adapter));
+    if (adapter) { await adapter.send(target.channelId, text); return true; }
+  } catch (_) { /* logged below */ }
+  console.warn(`[turn-journal] ${text}`);
+  return false;
+}
+
+async function resumeInterrupted(adapters, overrides = {}) {
+  const deps = { ...defaultDeps(), ...overrides };
+  const out = { resumed: [], asked: [], refused: [], restored: 0 };
+  if (!resumeEnabled()) { console.log("[turn-journal] resume off (RESUME_INTERRUPTED=off)"); return out; }
+  if (deps.isSafeMode()) { console.log("[turn-journal] safe mode: interrupted turns left for later"); return out; }
+  const now = deps.now();
+  const runs = [];
+  for (const { file, record } of list()) {
+    const adapter = findAdapter(adapters || [], record.conversation);
+    if (!adapter) { console.warn(`[turn-journal] ${record.conversation.laneKey}: its channel is not loaded; left for later`); continue; }
+    const turn = record.turn;
+    if (!turn) {
+      const queued = record.queued || [];
+      record.queued = [];
+      remove(file);
+      runQueued({ ...record, queued }, adapter, deps);
+      out.restored += queued.length;
+      continue;
+    }
+    const cutAt = turn.heartbeatAt || turn.startedAt || now;
+    if (turn.askedAt) {
+      // Offered already: the buttons work for 24 h, then it is dropped.
+      if (now - turn.askedAt > ASK_KEEP_MS) { record.turn = null; store(file, record); }
+      continue;
+    }
+    if ((turn.attempts || 0) >= MAX_ATTEMPTS) {
+      const where = record.conversation.threadId ? `a thread of ${record.conversation.transport}:${record.conversation.channelId}` : `${record.conversation.transport}:${record.conversation.channelId}`;
+      await tellOwner(`⚠️ I did not resume a turn in ${where} that was cut off ${turn.attempts} times (it may be what stops me): "${clip(turn.originalPrompt || turn.prompt)}". Send it again if you still want it.`, adapters, deps);
+      const queued = record.queued || [];
+      record.turn = null;
+      record.queued = [];
+      remove(file);
+      runQueued({ ...record, queued }, adapter, deps);
+      out.refused.push(record.conversation.laneKey);
+      out.restored += queued.length;
+      continue;
+    }
+    if (now - cutAt > maxAgeMs()) {
+      const askId = idFor(`${record.conversation.laneKey}:${turn.runId}`);
+      turn.askedAt = now;
+      turn.askId = askId;
+      const queued = record.queued || [];
+      record.queued = [];
+      write(file, record);
+      const scope = chatScope(record.conversation, adapter, deps);
+      await deps.runInChat(scope, () => Promise.resolve(deps.send(
+        `I was cut off at ${hhmm(cutAt)} doing: ${clip(turn.originalPrompt || turn.prompt)}. Continue?`,
+        { keyboard: { inline_keyboard: [[{ text: "Continue", callback_data: `rsm:go:${askId}` }, { text: "Drop", callback_data: `rsm:drop:${askId}` }]] } },
+      )).catch(() => {}));
+      runQueued({ ...record, queued }, adapter, deps);
+      out.asked.push(record.conversation.laneKey);
+      out.restored += queued.length;
+      continue;
+    }
+    out.resumed.push(record.conversation.laneKey);
+    out.restored += (record.queued || []).length;
+    runs.push(runResume(file, record, adapter, deps, { cutAt }));
+  }
+  out.runs = runs;
+  return out;
+}
+
+// A button is pressed in the chat it was posted in, by the person whose
+// message it was or by the owner.
+function mayPress(envelope, conversation, deps) {
+  if (String(envelope?.channelId || "") !== String(conversation.channelId)) return false;
+  if (deps.isOwner === true) return true;
+  return !!conversation.canonicalUserId && String(envelope?.canonicalUserId || "") === String(conversation.canonicalUserId);
+}
+
+// Continue / Drop on an offered turn (callback "rsm:go:<id>" / "rsm:drop:<id>").
+async function handleResumeAction(data, envelope, overrides = {}) {
+  const deps = { ...defaultDeps(), ...overrides };
+  const [, verb, askId] = String(data).split(":");
+  const hit = list().find((x) => x.record.turn?.askId === askId);
+  if (!hit) return deps.send("That cut-off turn is no longer waiting.");
+  const { file, record } = hit;
+  if (!mayPress(envelope, record.conversation, deps)) return deps.send("That button belongs to another chat or person.");
+  if (verb === "drop") {
+    record.turn = null;
+    store(file, record);
+    return deps.send("Dropped.");
+  }
+  const adapter = envelope?.adapter || null;
+  if (!adapter) return null;
+  return runResume(file, record, adapter, deps, { cutAt: record.turn.heartbeatAt || record.turn.startedAt || deps.now() });
+}
+
+// ── /stop: dropped queued messages can be run again ────────────────────
+
+function droppedFile() { return path.join(DIR(), "dropped.json"); }
+
+// Keep each dropped message (24 h) and return its button id.
+function rememberDropped(items, opts = {}) {
+  const at = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const all = read(droppedFile()) || {};
+  for (const [id, item] of Object.entries(all)) if (at - (item.at || 0) > DROPPED_KEEP_MS) delete all[id];
+  const ids = [];
+  for (const item of items) {
+    const runContext = item?.runContext;
+    if (!runContext || !journalable(runContext)) { ids.push(null); continue; }
+    const id = idFor(`${runContext.runId}:${at}`).slice(0, 10);
+    all[id] = { ...inboundOf(runContext), provider: runContext.provider, conversation: conversationOf(runContext), projectDir: runContext.project?.dir || null, at };
+    ids.push(id);
+  }
+  try { write(droppedFile(), all); } catch (_) { return items.map(() => null); }
+  return ids;
+}
+
+// The buttons for a /stop notice: one "Run it" per dropped message (max 5).
+function droppedKeyboard(items, opts = {}) {
+  const ids = rememberDropped(items, opts);
+  const rows = [];
+  items.forEach((item, i) => {
+    if (!ids[i] || rows.length >= 5) return;
+    const words = clip(item.text || item.runContext?.userPrompt || "", 28);
+    rows.push([{ text: `▶️ Run it: "${words}"`, callback_data: `rq:${ids[i]}` }]);
+  });
+  return rows.length ? { inline_keyboard: rows } : null;
+}
+
+async function handleRunDropped(data, envelope, overrides = {}) {
+  const deps = { ...defaultDeps(), ...overrides };
+  const id = String(data).slice(3);
+  const all = read(droppedFile()) || {};
+  const item = all[id];
+  if (!item) return deps.send("That message is no longer kept (24 h).");
+  if (!mayPress(envelope, item.conversation, deps)) return deps.send("That button belongs to another chat or person.");
+  delete all[id];
+  try { write(droppedFile(), all); } catch (_) {}
+  const scope = chatScope(item.conversation, envelope.adapter, deps);
+  return deps.runInChat(scope, () => deps.runAgent(item.prompt, item.projectDir, item.replyToMsgId, {
+    purpose: "foreground", provider: item.provider || undefined,
+    imagePaths: item.imagePaths || [], attachments: item.attachments || [],
+  }));
+}
+
+// ── planned restarts ───────────────────────────────────────────────────
+
+function isDraining() { return draining; }
+
+// Stop admitting new turns, give running ones up to DRAIN_TIMEOUT_S, then mark
+// shutdown so the turns still running stay journaled when they are killed.
+async function drain(opts = {}) {
+  draining = true;
+  const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : drainTimeoutMs();
+  const busy = opts.anyTurnActive || (() => require("./state").anyTurnActive());
+  const sleep = opts.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = opts.now || Date.now;
+  const deadline = now() + timeoutMs;
+  while (busy() && now() < deadline) await sleep(250);
+  const finished = !busy();
+  shuttingDown = true;
+  if (!finished) console.log(`[turn-journal] drain: turns still running after ${Math.round(timeoutMs / 1000)} s stay journaled and resume after the restart`);
+  return { finished };
+}
+
+// A planned exit (/restart, /upgrade, /downgrade): drain first.
+async function exitAfterDrain(code = 0, opts = {}) {
+  try { require("./scheduler").stopAll(); } catch (_) {}
+  try { await drain(opts); } catch (_) { shuttingDown = true; }
+  (opts.exit || process.exit)(code);
+}
+
+function markShuttingDown() { shuttingDown = true; }
+
+function _resetForTests() {
+  shuttingDown = false;
+  draining = false;
+  active.clear();
+  if (heartbeat) { clearInterval(heartbeat); heartbeat = null; }
+}
+
+module.exports = {
+  journalable, begin, end, enqueue, dropQueued, beat, list, fileFor,
+  resumeInterrupted, handleResumeAction, RESUME_PROMPT,
+  rememberDropped, droppedKeyboard, handleRunDropped,
+  drain, exitAfterDrain, isDraining, markShuttingDown,
+  resumeEnabled, maxAgeMs, drainTimeoutMs, sigtermDrainTimeoutMs, MAX_ATTEMPTS, HEARTBEAT_MS,
+  _resetForTests,
+};

package/core/utility-agent.js

@@ -514,6 +514,7 @@ function createUtilityAgentService(options = {}) {
     activeControllers.add(controller);
     request = { ...request, signal: controller.signal };
     let schemaResource = null;
+    const providerSchemaResources = [];
     try {
       const candidates = policy.candidates({ ...request, purpose });
       if (request.outputSchema) schemaResource = prepareSchemaFile(request.outputSchema);
@@ -522,6 +523,20 @@ function createUtilityAgentService(options = {}) {
         const selection = candidates[index];
         const provider = selection.provider;
         const effort = providerEffort(provider, request.effort);
+        // A provider may need its own dialect of the caller's schema, or none at
+        // all (Codex: OpenAI strict mode, 6 Oct 2026). The reply is still checked
+        // against the caller's schema after the run.
+        let providerSchema = request.outputSchema || null;
+        let providerSchemaPath = schemaResource ? schemaResource.file : null;
+        if (providerSchema && typeof provider.outputSchemaFor === "function") {
+          providerSchema = provider.outputSchemaFor(request.outputSchema) || null;
+          if (!providerSchema) providerSchemaPath = null;
+          else if (JSON.stringify(providerSchema) !== JSON.stringify(request.outputSchema)) {
+            const resource = prepareSchemaFile(providerSchema);
+            providerSchemaResources.push(resource);
+            providerSchemaPath = resource.file;
+          }
+        }
         const systemPrompt = typeof request.systemPrompt === "string" && request.systemPrompt.trim()
           ? request.systemPrompt
           : DEFAULT_SYSTEM_PROMPT;
@@ -541,7 +556,7 @@ function createUtilityAgentService(options = {}) {
             : {}),
           ...(request.allowedTools !== undefined ? { allowedTools: request.allowedTools } : {}),
           ...(request.disallowedTools !== undefined ? { disallowedTools: request.disallowedTools } : {}),
-          ...(request.outputSchema ? { outputSchema: request.outputSchema, outputSchemaPath: schemaResource.file } : {}),
+          ...(providerSchema ? { outputSchema: providerSchema, outputSchemaPath: providerSchemaPath } : {}),
           ...(effort ? { effort } : {}),
         };
 
@@ -615,6 +630,7 @@ function createUtilityAgentService(options = {}) {
       activeControllers.delete(controller);
       if (externalSignal) externalSignal.removeEventListener("abort", onExternalAbort);
       if (schemaResource) schemaResource.cleanup();
+      for (const resource of providerSchemaResources) resource.cleanup();
       release(purpose);
     }
   }