@inetafrica/open-claudia 2.14.8 → 3.0.0

package/core/utility-agent.js

@@ -0,0 +1,654 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { AsyncLocalStorage } = require("node:async_hooks");
+const { spawn } = require("child_process");
+const { MAX_PROCESS_TIMEOUT } = require("./config");
+const { killProcessTree } = require("./process-tree");
+const { redactSensitive } = require("./redact");
+const { validateInvocation } = require("./providers/contract");
+const { selectTerminalText } = require("./providers/events");
+const { createUtilityPolicy, normalizePurpose } = require("./providers/utility-policy");
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+const DEFAULT_MAX_STDERR_BYTES = 64 * 1024;
+const DEFAULT_MAX_STDOUT_BYTES = 4 * 1024 * 1024;
+const DEFAULT_KILL_GRACE_MS = 500;
+const DEFAULT_GLOBAL_CONCURRENCY = 6;
+const DEFAULT_PURPOSE_CONCURRENCY = 3;
+const DEFAULT_RECURSION_DEPTH = 2;
+const DEFAULT_SYSTEM_PROMPT = [
+  "You are a bounded Open Claudia utility agent.",
+  "Follow the supplied task and return only the requested result.",
+  "Do not message people, change Open Claudia state, or perform product side effects.",
+].join("\n");
+
+class UtilityAgentError extends Error {
+  constructor(code, message, result = null, details = {}) {
+    super(redactSensitive(message));
+    this.name = "UtilityAgentError";
+    this.code = code;
+    this.result = result;
+    this.details = details;
+  }
+}
+
+function positiveInteger(value, fallback, label) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) throw new TypeError(`${label} must be a positive integer`);
+  return parsed;
+}
+
+function boundedTimeout(value) {
+  const parsed = Number(value || DEFAULT_TIMEOUT_MS);
+  if (!Number.isFinite(parsed) || parsed <= 0) throw new TypeError("timeoutMs must be a positive number");
+  return Math.min(parsed, MAX_PROCESS_TIMEOUT || DEFAULT_TIMEOUT_MS);
+}
+
+function clipUtf8(value, maxBytes) {
+  const source = Buffer.from(String(value || ""), "utf8");
+  if (source.length <= maxBytes) return { text: source.toString("utf8"), truncated: false };
+  let text = source.subarray(0, maxBytes).toString("utf8");
+  if (text.endsWith("\ufffd")) text = text.slice(0, -1);
+  return { text, truncated: true };
+}
+
+function appendBounded(current, addition, maxBytes) {
+  const joined = `${current || ""}${addition || ""}`;
+  return clipUtf8(joined, maxBytes);
+}
+
+function stableError(code, message) {
+  return { code, message: redactSensitive(String(message || "Utility agent failed")) };
+}
+
+function extractJson(text) {
+  const raw = String(text || "").trim().replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/i, "");
+  try { return JSON.parse(raw); } catch (_) { /* try a bounded object/array below */ }
+  const objectStart = raw.indexOf("{");
+  const objectEnd = raw.lastIndexOf("}");
+  const arrayStart = raw.indexOf("[");
+  const arrayEnd = raw.lastIndexOf("]");
+  const candidates = [];
+  if (objectStart >= 0 && objectEnd > objectStart) candidates.push(raw.slice(objectStart, objectEnd + 1));
+  if (arrayStart >= 0 && arrayEnd > arrayStart) candidates.push(raw.slice(arrayStart, arrayEnd + 1));
+  for (const candidate of candidates) {
+    try { return JSON.parse(candidate); } catch (_) { /* continue */ }
+  }
+  throw new Error("utility output was not valid JSON");
+}
+
+function schemaTypeMatches(value, type) {
+  if (type === "object") return !!value && typeof value === "object" && !Array.isArray(value);
+  if (type === "array") return Array.isArray(value);
+  if (type === "string") return typeof value === "string";
+  if (type === "number") return typeof value === "number" && Number.isFinite(value);
+  if (type === "integer") return Number.isInteger(value);
+  if (type === "boolean") return typeof value === "boolean";
+  if (type === "null") return value === null;
+  return true;
+}
+
+function validateSchema(value, schema, location = "$", depth = 0) {
+  if (!schema || typeof schema !== "object" || depth > 20) return null;
+  if (schema.type && !schemaTypeMatches(value, schema.type)) return `${location} must be ${schema.type}`;
+  if (Array.isArray(schema.enum) && !schema.enum.some((entry) => Object.is(entry, value))) return `${location} is not an allowed value`;
+  if (schema.type === "object" && value && typeof value === "object" && !Array.isArray(value)) {
+    for (const key of schema.required || []) {
+      if (!Object.prototype.hasOwnProperty.call(value, key)) return `${location}.${key} is required`;
+    }
+    for (const [key, childSchema] of Object.entries(schema.properties || {})) {
+      if (!Object.prototype.hasOwnProperty.call(value, key)) continue;
+      const error = validateSchema(value[key], childSchema, `${location}.${key}`, depth + 1);
+      if (error) return error;
+    }
+    if (schema.additionalProperties === false) {
+      const known = new Set(Object.keys(schema.properties || {}));
+      const extra = Object.keys(value).find((key) => !known.has(key));
+      if (extra) return `${location}.${extra} is not allowed`;
+    }
+  }
+  if (schema.type === "array" && Array.isArray(value) && schema.items) {
+    for (let index = 0; index < value.length; index += 1) {
+      const error = validateSchema(value[index], schema.items, `${location}[${index}]`, depth + 1);
+      if (error) return error;
+    }
+  }
+  return null;
+}
+
+function prepareSchemaFile(schema) {
+  if (!schema) return null;
+  let serialized;
+  try { serialized = JSON.stringify(schema); }
+  catch (_) { throw new UtilityAgentError("INVALID_UTILITY_SCHEMA", "outputSchema must be JSON-serializable"); }
+  if (!serialized) throw new UtilityAgentError("INVALID_UTILITY_SCHEMA", "outputSchema must be JSON-serializable");
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), "open-claudia-utility-schema-"));
+  const file = path.join(directory, "schema.json");
+  fs.writeFileSync(file, `${serialized}\n`, { mode: 0o600 });
+  return {
+    file,
+    cleanup() { fs.rmSync(directory, { recursive: true, force: true }); },
+  };
+}
+
+function readOnlyMetadata(provider, requested) {
+  const capability = provider.capabilities?.readOnlyMode || { support: "unsupported", reason: "read-only capability is undeclared" };
+  return {
+    requested: !!requested,
+    support: requested ? capability.support : "not_requested",
+    reason: requested ? capability.reason : null,
+  };
+}
+
+function noToolsMetadata(options) {
+  const requested = Array.isArray(options.allowedTools) && options.allowedTools.length === 0;
+  return {
+    requested,
+    verified: false,
+    reason: requested
+      ? "No provider capability probe has verified complete hosted-tool suppression"
+      : "Complete tool suppression was not requested",
+  };
+}
+
+function providerEffort(provider, requested) {
+  const effort = String(requested || "").trim();
+  if (!effort) return null;
+  const values = provider.capabilities?.effort?.values;
+  if (!Array.isArray(values) || values.includes(effort)) return effort;
+  // `max` is the provider-neutral dream setting. Providers name their top
+  // reasoning level differently (Claude: max, Codex: xhigh), so map only this
+  // generic ceiling and leave every other invalid value to the adapter's
+  // normal typed validation.
+  if (effort === "max" && values.length) return values[values.length - 1];
+  return effort;
+}
+
+function executeUtilityInvocation(options) {
+  const {
+    provider,
+    invocation,
+    cwd,
+    spawnProcess,
+    killTree,
+    killGraceMs,
+    timeoutMs,
+    signal,
+    maxOutputBytes,
+    maxStderrBytes,
+    maxStdoutBytes,
+    outputSchema,
+  } = options;
+
+  const decoder = provider.createEventDecoder();
+  const parserState = invocation.parserState;
+  let proc = null;
+  let stdoutBytes = 0;
+  let stderr = "";
+  let stderrTruncated = false;
+  let finalText = "";
+  let finalTruncated = false;
+  let deltaText = "";
+  let deltaTruncated = false;
+  let resultText = "";
+  let resultTruncated = false;
+  let usage = null;
+  let terminalSeen = false;
+  let normalizedFailure = null;
+  let spawnFailure = null;
+  let closeInfo = null;
+  let stdoutEnded = false;
+  let timedOut = false;
+  let cancelled = false;
+  let outputLimit = false;
+  let terminationStarted = false;
+  let timeoutTimer = null;
+  let killTimer = null;
+
+  function appendText(kind, text) {
+    if (kind === "final") {
+      const next = appendBounded(finalText, text, maxOutputBytes);
+      finalText = next.text;
+      finalTruncated ||= next.truncated;
+    } else if (kind === "delta") {
+      const next = appendBounded(deltaText, text, maxOutputBytes);
+      deltaText = next.text;
+      deltaTruncated ||= next.truncated;
+    } else {
+      const next = appendBounded(resultText, text, maxOutputBytes);
+      resultText = next.text;
+      resultTruncated ||= next.truncated;
+    }
+  }
+
+  function handleNormalized(event) {
+    if (!event || typeof event !== "object") return;
+    if (event.type === "text_final") appendText("final", event.text);
+    else if (event.type === "text_delta") appendText("delta", event.text);
+    else if (event.type === "result") {
+      terminalSeen = true;
+      if (event.text) appendText("result", event.text);
+    } else if (event.type === "usage") usage = event;
+    else if (event.type === "error" && !normalizedFailure) {
+      terminalSeen = true;
+      normalizedFailure = event;
+    }
+  }
+
+  function handleRaw(events) {
+    for (const rawEvent of events || []) {
+      let normalized;
+      try { normalized = provider.normalizeEvent(rawEvent, parserState); }
+      catch (error) {
+        normalizedFailure ||= { message: `utility event normalization failed: ${error.message}`, authError: false };
+        continue;
+      }
+      for (const event of Array.isArray(normalized) ? normalized : (normalized ? [normalized] : [])) handleNormalized(event);
+    }
+  }
+
+  function finishDecoder() {
+    if (stdoutEnded) return;
+    stdoutEnded = true;
+    try { handleRaw(decoder.end()); }
+    catch (error) { normalizedFailure ||= { message: `utility stream decoding failed: ${error.message}`, authError: false }; }
+  }
+
+  function terminate(reason) {
+    if (!proc || terminationStarted) return;
+    terminationStarted = true;
+    if (reason === "timeout") timedOut = true;
+    else if (reason === "cancel") cancelled = true;
+    else if (reason === "output") outputLimit = true;
+    try { killTree(proc.pid, "SIGTERM"); } catch (_) { try { proc.kill("SIGTERM"); } catch (_) {} }
+    killTimer = setTimeout(() => {
+      try { killTree(proc.pid, "SIGKILL"); } catch (_) { try { proc.kill("SIGKILL"); } catch (_) {} }
+    }, killGraceMs);
+  }
+
+  return new Promise((resolve) => {
+    let closeResolved = false;
+    let stdoutResolved = false;
+    const maybeFinish = () => {
+      if (!closeResolved || !stdoutResolved) return;
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (killTimer) clearTimeout(killTimer);
+      if (signal) signal.removeEventListener("abort", onAbort);
+
+      const selectedText = selectTerminalText({ resultText, finalText, deltaText });
+      const truncated = resultText
+        ? resultTruncated
+        : (finalText ? finalTruncated : deltaTruncated);
+      const safeText = redactSensitive(selectedText.trim());
+      const safeStderr = redactSensitive(stderr.trim());
+      let failure = null;
+      if (spawnFailure) failure = stableError("UTILITY_SPAWN_FAILED", spawnFailure.message);
+      else if (cancelled) failure = stableError("UTILITY_CANCELLED", "Utility agent was cancelled");
+      else if (timedOut) failure = stableError("UTILITY_TIMEOUT", "Utility agent timed out");
+      else if (outputLimit) failure = stableError("UTILITY_OUTPUT_LIMIT", "Utility provider stdout exceeded its hard limit");
+      else if (normalizedFailure) failure = stableError(
+        normalizedFailure.authError ? "PROVIDER_UNAUTHENTICATED" : "UTILITY_PROVIDER_ERROR",
+        normalizedFailure.message || "Utility provider failed",
+      );
+      else if (closeInfo?.code !== 0) failure = stableError(
+        "UTILITY_PROCESS_FAILED",
+        safeStderr || `Utility provider exited with code ${closeInfo?.code == null ? "unknown" : closeInfo.code}`,
+      );
+      else if (!terminalSeen) failure = stableError("UTILITY_MISSING_TERMINAL", "Utility provider closed without a terminal event");
+
+      let json = null;
+      if (!failure && outputSchema) {
+        try {
+          json = extractJson(safeText);
+          const schemaError = validateSchema(json, outputSchema);
+          if (schemaError) failure = stableError("UTILITY_SCHEMA_INVALID", schemaError);
+        } catch (error) {
+          failure = stableError("UTILITY_SCHEMA_INVALID", error.message);
+        }
+      }
+
+      resolve({
+        ok: !failure,
+        status: failure ? "failed" : "succeeded",
+        text: safeText,
+        json,
+        truncated,
+        stderr: safeStderr,
+        stderrTruncated,
+        usage: usage ? { usage: usage.usage, scope: usage.scope } : null,
+        exitCode: closeInfo?.code ?? null,
+        signal: closeInfo?.signal ?? null,
+        timedOut,
+        cancelled,
+        terminalSeen,
+        stdoutEnded,
+        error: failure,
+      });
+    };
+
+    const onAbort = () => terminate("cancel");
+    try {
+      proc = spawnProcess(invocation.binary, invocation.args, {
+        cwd,
+        env: invocation.env,
+        stdio: [invocation.stdin === null ? "ignore" : "pipe", "pipe", "pipe"],
+        detached: process.platform !== "win32",
+        shell: false,
+      });
+    } catch (error) {
+      spawnFailure = error;
+      finishDecoder();
+      stdoutResolved = true;
+      closeInfo = { code: null, signal: null };
+      closeResolved = true;
+      maybeFinish();
+      return;
+    }
+
+    proc.stdout.on("data", (chunk) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > maxStdoutBytes) {
+        terminate("output");
+        return;
+      }
+      try { handleRaw(decoder.push(chunk)); }
+      catch (error) { normalizedFailure ||= { message: `utility stream decoding failed: ${error.message}`, authError: false }; }
+    });
+    proc.stdout.once("end", () => {
+      finishDecoder();
+      stdoutResolved = true;
+      maybeFinish();
+    });
+    proc.stdout.once("close", () => {
+      if (terminationStarted || spawnFailure) {
+        finishDecoder();
+        stdoutResolved = true;
+        maybeFinish();
+      }
+    });
+    proc.stdout.once("error", (error) => {
+      normalizedFailure ||= { message: `utility stdout failed: ${error.message}`, authError: false };
+      finishDecoder();
+      stdoutResolved = true;
+      maybeFinish();
+    });
+    proc.stderr.on("data", (chunk) => {
+      const next = appendBounded(stderr, chunk.toString("utf8"), maxStderrBytes);
+      stderr = next.text;
+      stderrTruncated ||= next.truncated;
+    });
+    proc.once("error", (error) => {
+      spawnFailure = error;
+      closeInfo = { code: null, signal: null };
+      closeResolved = true;
+      try { proc.stdout.destroy(); } catch (_) {}
+      finishDecoder();
+      stdoutResolved = true;
+      maybeFinish();
+    });
+    proc.once("close", (code, closeSignal) => {
+      closeInfo = { code, signal: closeSignal };
+      closeResolved = true;
+      if (!stdoutResolved && terminationStarted) {
+        try { proc.stdout.destroy(); } catch (_) {}
+        finishDecoder();
+        stdoutResolved = true;
+      }
+      maybeFinish();
+    });
+
+    if (invocation.stdin !== null && proc.stdin) {
+      proc.stdin.once("error", (error) => {
+        normalizedFailure ||= { message: `utility stdin failed: ${error.message}`, authError: false };
+      });
+      proc.stdin.end(invocation.stdin);
+    }
+    if (signal) {
+      signal.addEventListener("abort", onAbort, { once: true });
+      if (signal.aborted) onAbort();
+    }
+    timeoutTimer = setTimeout(() => terminate("timeout"), timeoutMs);
+  });
+}
+
+function fallbackEligible(errorCode) {
+  return new Set([
+    "PROVIDER_UNAVAILABLE",
+    "PROVIDER_INCOMPATIBLE",
+    "PROVIDER_UNAUTHENTICATED",
+    "NO_AVAILABLE_PROVIDER",
+    "MANDATORY_TOOL_HOOK_UNAVAILABLE",
+    "UTILITY_SPAWN_FAILED",
+  ]).has(errorCode);
+}
+
+function createUtilityAgentService(options = {}) {
+  const registry = options.registry || require("./providers");
+  const env = options.env || require("./config").config;
+  const policy = options.policy || createUtilityPolicy({ registry, env, activeProvider: options.activeProvider });
+  const spawnProcess = options.spawnProcess || spawn;
+  const killTree = options.killTree || killProcessTree;
+  const killGraceMs = positiveInteger(options.killGraceMs, DEFAULT_KILL_GRACE_MS, "killGraceMs");
+  const maxOutputBytes = positiveInteger(options.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES, "maxOutputBytes");
+  const maxStderrBytes = positiveInteger(options.maxStderrBytes, DEFAULT_MAX_STDERR_BYTES, "maxStderrBytes");
+  const maxStdoutBytes = positiveInteger(options.maxStdoutBytes, DEFAULT_MAX_STDOUT_BYTES, "maxStdoutBytes");
+  const maxGlobalConcurrency = positiveInteger(
+    options.maxGlobalConcurrency ?? env.UTILITY_MAX_CONCURRENCY,
+    DEFAULT_GLOBAL_CONCURRENCY,
+    "maxGlobalConcurrency",
+  );
+  const defaultPurposeLimit = positiveInteger(
+    options.maxPurposeConcurrency ?? env.UTILITY_MAX_PURPOSE_CONCURRENCY,
+    DEFAULT_PURPOSE_CONCURRENCY,
+    "maxPurposeConcurrency",
+  );
+  const maxRecursionDepth = positiveInteger(
+    options.maxRecursionDepth ?? env.UTILITY_MAX_RECURSION,
+    DEFAULT_RECURSION_DEPTH,
+    "maxRecursionDepth",
+  );
+  const purposeLimits = { ...(options.purposeConcurrency || {}) };
+  const context = new AsyncLocalStorage();
+  let activeGlobal = 0;
+  const activeByPurpose = new Map();
+  const activeControllers = new Set();
+
+  function purposeLimit(purpose) {
+    return positiveInteger(purposeLimits[purpose], defaultPurposeLimit, `${purpose} concurrency limit`);
+  }
+
+  function reserve(purpose) {
+    const activePurpose = activeByPurpose.get(purpose) || 0;
+    if (activeGlobal >= maxGlobalConcurrency || activePurpose >= purposeLimit(purpose)) {
+      throw new UtilityAgentError(
+        "UTILITY_CONCURRENCY_LIMIT",
+        `Utility concurrency limit reached for ${purpose}`,
+        null,
+        { purpose, activeGlobal, activePurpose },
+      );
+    }
+    activeGlobal += 1;
+    activeByPurpose.set(purpose, activePurpose + 1);
+  }
+
+  function release(purpose) {
+    activeGlobal = Math.max(0, activeGlobal - 1);
+    const activePurpose = activeByPurpose.get(purpose) || 0;
+    if (activePurpose <= 1) activeByPurpose.delete(purpose);
+    else activeByPurpose.set(purpose, activePurpose - 1);
+  }
+
+  function stats() {
+    return {
+      activeGlobal,
+      activeByPurpose: Object.fromEntries([...activeByPurpose.entries()].sort(([left], [right]) => left.localeCompare(right))),
+    };
+  }
+
+  async function spawnUtilityAgent(prompt, request = {}) {
+    if (typeof prompt !== "string") throw new TypeError("utility prompt must be a string");
+    const purpose = normalizePurpose(request.purpose);
+    const inheritedDepth = Number(env.OC_UTILITY_DEPTH || process.env.OC_UTILITY_DEPTH || 0);
+    const depth = Math.max(
+      context.getStore()?.depth || 0,
+      Number.isSafeInteger(inheritedDepth) && inheritedDepth >= 0 ? inheritedDepth : 0,
+    );
+    if (depth >= maxRecursionDepth) {
+      throw new UtilityAgentError("UTILITY_RECURSION_LIMIT", `Utility recursion limit reached for ${purpose}`, null, { purpose, depth });
+    }
+    if (request.signal?.aborted) {
+      throw new UtilityAgentError("UTILITY_CANCELLED", "Utility agent was cancelled before spawn", {
+        ok: false, status: "failed", provider: null, purpose, cancelled: true,
+      });
+    }
+    reserve(purpose);
+    const externalSignal = request.signal || null;
+    const controller = new AbortController();
+    const onExternalAbort = () => controller.abort();
+    if (externalSignal) externalSignal.addEventListener("abort", onExternalAbort, { once: true });
+    activeControllers.add(controller);
+    request = { ...request, signal: controller.signal };
+    let schemaResource = null;
+    try {
+      const candidates = policy.candidates({ ...request, purpose });
+      if (request.outputSchema) schemaResource = prepareSchemaFile(request.outputSchema);
+      let lastResult = null;
+      for (let index = 0; index < candidates.length; index += 1) {
+        const selection = candidates[index];
+        const provider = selection.provider;
+        const effort = providerEffort(provider, request.effort);
+        const systemPrompt = typeof request.systemPrompt === "string" && request.systemPrompt.trim()
+          ? request.systemPrompt
+          : DEFAULT_SYSTEM_PROMPT;
+        const invocationContext = {
+          purpose,
+          tier: selection.tier,
+          model: selection.model,
+          coreInstructions: systemPrompt,
+          dynamicContext: "",
+          userPrompt: prompt,
+          prompt,
+          fresh: true,
+          readOnly: request.readOnly !== false,
+          cwd: request.cwd || process.cwd(),
+          ...(request.allowedTools !== undefined ? { allowedTools: request.allowedTools } : {}),
+          ...(request.disallowedTools !== undefined ? { disallowedTools: request.disallowedTools } : {}),
+          ...(request.outputSchema ? { outputSchema: request.outputSchema, outputSchemaPath: schemaResource.file } : {}),
+          ...(effort ? { effort } : {}),
+        };
+
+        let invocation;
+        try {
+          invocation = validateInvocation(provider.buildUtilityInvocation(invocationContext));
+          invocation = validateInvocation({
+            ...invocation,
+            env: {
+              ...invocation.env,
+              OC_PROVIDER: selection.providerId,
+              OC_UTILITY_DEPTH: String(depth + 1),
+              OC_UTILITY_PURPOSE: purpose,
+            },
+          });
+        } catch (error) {
+          const result = {
+            ok: false,
+            status: "failed",
+            text: "",
+            provider: selection.providerId,
+            model: selection.model,
+            tier: selection.tier,
+            purpose,
+            preferredProvider: selection.preferredProviderId,
+            fallbackUsed: selection.fallbackUsed,
+            effort,
+            error: stableError(error.code || "UTILITY_INVOCATION_FAILED", error.message),
+          };
+          lastResult = result;
+          if (index + 1 < candidates.length && fallbackEligible(result.error.code)) continue;
+          throw new UtilityAgentError(result.error.code, result.error.message, result);
+        }
+
+        const result = await context.run({ depth: depth + 1, purpose }, () => executeUtilityInvocation({
+          provider,
+          invocation,
+          cwd: request.cwd || process.cwd(),
+          spawnProcess,
+          killTree,
+          killGraceMs,
+          timeoutMs: boundedTimeout(request.timeoutMs),
+          signal: request.signal || null,
+          maxOutputBytes,
+          maxStderrBytes,
+          maxStdoutBytes,
+          outputSchema: request.outputSchema || null,
+        }));
+        Object.assign(result, {
+          provider: selection.providerId,
+          model: selection.model,
+          tier: selection.tier,
+          purpose,
+          preferredProvider: selection.preferredProviderId,
+          fallbackUsed: selection.fallbackUsed,
+          effort,
+          noTools: noToolsMetadata(request),
+          noProductSideEffects: readOnlyMetadata(provider, request.readOnly !== false),
+        });
+        lastResult = result;
+        if (result.ok) return result;
+        if (index + 1 < candidates.length && fallbackEligible(result.error?.code)) continue;
+        throw new UtilityAgentError(result.error?.code || "UTILITY_AGENT_FAILED", result.error?.message || "Utility agent failed", result);
+      }
+      throw new UtilityAgentError(
+        lastResult?.error?.code || "NO_AVAILABLE_UTILITY_PROVIDER",
+        lastResult?.error?.message || `No provider completed the ${purpose} utility task`,
+        lastResult,
+      );
+    } finally {
+      activeControllers.delete(controller);
+      if (externalSignal) externalSignal.removeEventListener("abort", onExternalAbort);
+      if (schemaResource) schemaResource.cleanup();
+      release(purpose);
+    }
+  }
+
+  async function cancelAll(options = {}) {
+    const timeoutMs = positiveInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, "cancel timeoutMs");
+    for (const controller of activeControllers) controller.abort();
+    const deadline = Date.now() + timeoutMs;
+    while (activeControllers.size && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, Math.min(10, Math.max(1, deadline - Date.now()))));
+    }
+    return { drained: activeControllers.size === 0, active: activeControllers.size };
+  }
+
+  return {
+    cancelAll,
+    spawnUtilityAgent,
+    stats,
+    withUtilityContext(fn) {
+      const depth = (context.getStore()?.depth || 0) + 1;
+      return context.run({ depth, purpose: context.getStore()?.purpose || "test" }, fn);
+    },
+  };
+}
+
+const defaultService = createUtilityAgentService();
+
+module.exports = {
+  DEFAULT_MAX_OUTPUT_BYTES,
+  DEFAULT_SYSTEM_PROMPT,
+  UtilityAgentError,
+  createUtilityAgentService,
+  executeUtilityInvocation,
+  extractJson,
+  providerEffort,
+  cancelUtilityAgents: defaultService.cancelAll,
+  spawnUtilityAgent: defaultService.spawnUtilityAgent,
+  utilityAgentStats: defaultService.stats,
+  validateSchema,
+};