chainlesschain 0.165.2 → 0.165.4

package/src/runtime/headless-runner.js

@@ -120,6 +120,16 @@ import {
 import executionBroker from "../lib/process-execution-broker/index.js";
 import { extractPluginUsageAttribution } from "../lib/plugin-usage-attribution.js";
 import { formatManagedCheckpointEvent } from "../lib/managed-checkpoint-render.js";
+import {
+  openProductionSessionBudgetRoot,
+  sessionBudgetAdmissionError,
+} from "../lib/session-budget-production-root.js";
+import {
+  beginSessionBudgetUsage,
+  markSessionBudgetUsageUnknown,
+  recordSessionBudgetUsage,
+  rejectSessionBudgetUsageUnknown,
+} from "../lib/session-budget-usage.js";
 
 const goalBrokerRunner = executionBroker.spawnSync.bind(executionBroker);
 
@@ -466,11 +476,12 @@ async function withHeadlessSessionHostLease(options, deps, task) {
     deps.acquireSessionHostLease ||
     (!hasInjectedSessionStore ? acquireSessionHostLease : null);
   let lease = null;
+  let budgetRoot = null;
   try {
     if (authoritySessionId && typeof acquireHostLease === "function") {
       lease = acquireHostLease(authoritySessionId, { hostKind: "headless" });
     }
-    const scopedOptions = lease?.signal
+    let scopedOptions = lease?.signal
       ? {
           ...options,
           signal: options.signal
@@ -478,12 +489,28 @@ async function withHeadlessSessionHostLease(options, deps, task) {
             : lease.signal,
         }
       : options;
+    budgetRoot = openProductionSessionBudgetRoot(
+      authoritySessionId,
+      options.sessionBudgetRoot,
+      {
+        persist: resolution.persist,
+        signal: scopedOptions.signal || null,
+        table: options.sessionBudgetRoot?.table,
+        open: deps.openSessionBudget,
+        store: deps.sessionBudgetStore,
+        registry: deps.sessionBudgetRegistry,
+      },
+    );
+    if (budgetRoot.enabled) {
+      scopedOptions = { ...scopedOptions, ...budgetRoot.options };
+    }
     return await task(scopedOptions, {
       ...deps,
       [HEADLESS_SESSION_RESOLUTION]: resolution,
       [HEADLESS_SESSION_HOST_LEASE]: lease,
     });
   } finally {
+    budgetRoot?.close?.();
     lease?.release?.();
   }
 }
@@ -773,8 +800,9 @@ async function runAgentHeadlessInWorkspace(
       const loaded = loadHooks({ cwd, settingsFile: options.settingsFile });
       // Fold in installed plugins' hooks/hooks.json (Phase 3.3c) — plugins ADD
       // to the user's settings hooks, never replace them.
-      const { mergePluginHooks } =
-        await import("../lib/plugin-runtime/hooks.js");
+      const { mergePluginHooks } = await import(
+        "../lib/plugin-runtime/hooks.js"
+      );
       const effectiveHooks = mergePluginHooks(
         attachAuthorityErrors(loaded.hooks, loaded.authorityErrors),
         { cwd },
@@ -815,8 +843,9 @@ async function runAgentHeadlessInWorkspace(
   // the run, so no explicit restore is needed.
   if (!hermeticExecution) {
     try {
-      const { applyPluginBinPath } =
-        await import("../lib/plugin-runtime/bin.js");
+      const { applyPluginBinPath } = await import(
+        "../lib/plugin-runtime/bin.js"
+      );
       applyPluginBinPath({ cwd });
     } catch {
       /* best-effort — plugin bin PATH never blocks a headless run */
@@ -827,8 +856,9 @@ async function runAgentHeadlessInWorkspace(
   // keys not already set; the process exits at the end so no restore is needed.
   if (!hermeticExecution) {
     try {
-      const { applyPluginSettingsEnv } =
-        await import("../lib/plugin-runtime/settings.js");
+      const { applyPluginSettingsEnv } = await import(
+        "../lib/plugin-runtime/settings.js"
+      );
       applyPluginSettingsEnv({ cwd });
     } catch {
       /* best-effort — plugin settings never block a headless run */
@@ -961,8 +991,9 @@ async function runAgentHeadlessInWorkspace(
   if (isHeadlessConfigCommand(prompt)) {
     const cm = await import("../lib/config-manager.js");
     const { getConfigPath } = await import("../lib/paths.js");
-    const { runConfigDirective } =
-      await import("../lib/headless-config-command.js");
+    const { runConfigDirective } = await import(
+      "../lib/headless-config-command.js"
+    );
     const { text, isError } = runConfigDirective(prompt, {
       configManager: cm,
       getConfigPath,
@@ -1038,8 +1069,9 @@ async function runAgentHeadlessInWorkspace(
           model = macro.model;
           writeErr(`  command: model → ${model}\n`);
           try {
-            const { maybeWarnDeprecatedModel } =
-              await import("../lib/model-deprecation.js");
+            const { maybeWarnDeprecatedModel } = await import(
+              "../lib/model-deprecation.js"
+            );
             maybeWarnDeprecatedModel({ model });
           } catch {
             // deprecation notice is best-effort
@@ -1076,8 +1108,9 @@ async function runAgentHeadlessInWorkspace(
 
   // ── Permission + tool resolution ──────────────────────────────────────
   if (managedSettings) {
-    const { assertManagedPermissionMode } =
-      await import("../lib/settings-loader.cjs");
+    const { assertManagedPermissionMode } = await import(
+      "../lib/settings-loader.cjs"
+    );
     assertManagedPermissionMode(options.permissionMode, managedSettings);
   }
   const perm = resolvePermissionMode(options.permissionMode);
@@ -1533,8 +1566,9 @@ async function runAgentHeadlessInWorkspace(
       : null;
   if (!hermeticExecution && !instructionExcludes) {
     try {
-      const { readStringArraySetting } =
-        await import("../lib/settings-loader.cjs");
+      const { readStringArraySetting } = await import(
+        "../lib/settings-loader.cjs"
+      );
       const fromSettings = readStringArraySetting("instructionExcludes", {
         cwd,
         settingsFile: options.settingsFile,
@@ -1588,8 +1622,9 @@ async function runAgentHeadlessInWorkspace(
   // settings.json UserPromptSubmit hooks. block → abort the run; context → inject.
   if (settingsHooks) {
     try {
-      const { runUserPromptSubmitHooks } =
-        await import("../lib/settings-hook-events.js");
+      const { runUserPromptSubmitHooks } = await import(
+        "../lib/settings-hook-events.js"
+      );
       const ups = runUserPromptSubmitHooks(settingsHooks, {
         prompt: userContent,
         cwd,
@@ -1619,8 +1654,9 @@ async function runAgentHeadlessInWorkspace(
   let instructionsLoadedContext = null;
   if (settingsHooks && _loadedInstructions) {
     try {
-      const { runInstructionsLoadedHooks } =
-        await import("../lib/settings-hook-events.js");
+      const { runInstructionsLoadedHooks } = await import(
+        "../lib/settings-hook-events.js"
+      );
       instructionsLoadedContext = runInstructionsLoadedHooks(settingsHooks, {
         files: _loadedInstructions.files,
         cwd,
@@ -1635,8 +1671,9 @@ async function runAgentHeadlessInWorkspace(
   let sessionStartContext = null;
   if (settingsHooks) {
     try {
-      const { runSessionStartHooks } =
-        await import("../lib/settings-hook-events.js");
+      const { runSessionStartHooks } = await import(
+        "../lib/settings-hook-events.js"
+      );
       sessionStartContext = runSessionStartHooks(settingsHooks, {
         source: resumeId ? "resume" : "startup",
         cwd,
@@ -1654,8 +1691,9 @@ async function runAgentHeadlessInWorkspace(
   // back up" — e.g. re-run a workspace sanity check. Observe-only, best-effort.
   if (settingsHooks && resumeId && history.length > 0) {
     try {
-      const { runObserveHooks } =
-        await import("../lib/settings-hook-events.js");
+      const { runObserveHooks } = await import(
+        "../lib/settings-hook-events.js"
+      );
       runObserveHooks(
         settingsHooks,
         "SessionResume",
@@ -1886,8 +1924,9 @@ async function runAgentHeadlessInWorkspace(
   // --add-dir → workspaceRootDirs = [cwd] and this is a no-op. Best-effort.
   if (hostMcp?.mcpClient && additionalDirectories.length > 0) {
     try {
-      const { notifyMcpRootsChanged, workspaceRootDirs } =
-        await import("../repl/add-dir.js");
+      const { notifyMcpRootsChanged, workspaceRootDirs } = await import(
+        "../repl/add-dir.js"
+      );
       notifyMcpRootsChanged(
         [hostMcp.mcpClient],
         workspaceRootDirs(options.cwd || process.cwd(), additionalDirectories),
@@ -1995,8 +2034,9 @@ async function runAgentHeadlessInWorkspace(
         error.code = "CC_REMOTE_APPROVAL_GATE_UNAVAILABLE";
         throw error;
       }
-      const { startHeadlessRemoteApproval } =
-        await import("../lib/remote-approval-bridge.js");
+      const { startHeadlessRemoteApproval } = await import(
+        "../lib/remote-approval-bridge.js"
+      );
       _remoteApproval = await (
         deps.startHeadlessRemoteApproval || startHeadlessRemoteApproval
       )({
@@ -2025,8 +2065,9 @@ async function runAgentHeadlessInWorkspace(
   let _collectorEnabled = false;
   if (!hermeticExecution) {
     try {
-      const { isOtlpCollectorEnabled } =
-        await import("../lib/observability/index.js");
+      const { isOtlpCollectorEnabled } = await import(
+        "../lib/observability/index.js"
+      );
       _collectorEnabled = isOtlpCollectorEnabled();
     } catch {
       _collectorEnabled = false;
@@ -2034,8 +2075,9 @@ async function runAgentHeadlessInWorkspace(
   }
   if (!hermeticExecution && (options.otlp || _collectorEnabled)) {
     try {
-      const { TelemetryRecorder } =
-        await import("../lib/telemetry/span-recorder.js");
+      const { TelemetryRecorder } = await import(
+        "../lib/telemetry/span-recorder.js"
+      );
       _otlpRecorder = new TelemetryRecorder({ serviceName: "cc-agent" });
     } catch {
       _otlpRecorder = null; // telemetry is best-effort, never blocks the run
@@ -2049,8 +2091,9 @@ async function runAgentHeadlessInWorkspace(
   let _hookSupervisor = null;
   if (settingsHooks) {
     try {
-      const { AsyncHookSupervisor } =
-        await import("../lib/async-hook-supervisor.js");
+      const { AsyncHookSupervisor } = await import(
+        "../lib/async-hook-supervisor.js"
+      );
       _hookSupervisor = new AsyncHookSupervisor({
         persistStats: true,
         // Durably park failed-rewake signals keyed by session so a crash before
@@ -2161,6 +2204,7 @@ async function runAgentHeadlessInWorkspace(
     additionalDirectories,
     sandbox: options.sandbox || null,
     sessionId,
+    sessionBudget: options.sessionBudget || null,
     // Content-free continuity metadata from the same verified sample used for
     // replay history and MCP recovery authority.
     sessionHostSnapshot: canonicalResume?.snapshot || null,
@@ -2373,8 +2417,9 @@ async function runAgentHeadlessInWorkspace(
   if (options.goal !== undefined && options.goal !== false) {
     try {
       const explicitId = typeof options.goal === "string" ? options.goal : null;
-      const { resolveActiveGoal, linkSession } =
-        await import("../lib/goal-store.js");
+      const { resolveActiveGoal, linkSession } = await import(
+        "../lib/goal-store.js"
+      );
       const goal = (deps.resolveActiveGoal || resolveActiveGoal)({
         explicitId,
         sessionId,
@@ -2502,8 +2547,9 @@ async function runAgentHeadlessInWorkspace(
   let _asyncStopHandled = false;
   const _settleAsyncStop = async () => {
     if (!settingsHooks || !_hookSupervisor) return { rewakes: [], results: [] };
-    const { dispatchAsyncHooks } =
-      await import("../lib/settings-hook-events.js");
+    const { dispatchAsyncHooks } = await import(
+      "../lib/settings-hook-events.js"
+    );
     dispatchAsyncHooks(
       settingsHooks,
       "Stop",
@@ -2554,6 +2600,7 @@ async function runAgentHeadlessInWorkspace(
       provider,
       model,
       source: "model",
+      sessionBudget: options.sessionBudget || null,
       call: () =>
         chatWithTools([{ role: "user", content: judgePrompt }], {
           model,
@@ -2935,6 +2982,11 @@ async function runAgentHeadlessInWorkspace(
                 ),
               );
             }
+            beginSessionBudgetUsage(
+              options.sessionBudget,
+              event,
+              "headless provider call",
+            );
             break;
           }
           case "model-usage-unknown":
@@ -2948,6 +3000,10 @@ async function runAgentHeadlessInWorkspace(
                 ),
               );
             }
+            const budgetUsageUnknown = markSessionBudgetUsageUnknown(
+              options.sessionBudget,
+              event,
+            );
             if (event.type === "compaction-usage-unknown") {
               endReason = "compaction-usage-unknown";
               stopForCompactionUsageUnknown = true;
@@ -2960,6 +3016,14 @@ async function runAgentHeadlessInWorkspace(
                 usage_outcome: "unknown",
               });
             }
+            if (budgetUsageUnknown) {
+              rejectSessionBudgetUsageUnknown(
+                event,
+                event.type === "compaction-usage-unknown"
+                  ? "headless semantic compaction"
+                  : "headless provider call",
+              );
+            }
             break;
           }
           case "token-usage": {
@@ -2969,6 +3033,11 @@ async function runAgentHeadlessInWorkspace(
                 store.appendTokenUsage(sessionId, persistedUsage),
               );
             }
+            recordSessionBudgetUsage(
+              options.sessionBudget,
+              event,
+              "headless usage settlement",
+            );
             if (!event.attribution) {
               usage.input_tokens += event.usage?.input_tokens || 0;
               usage.output_tokens += event.usage?.output_tokens || 0;
@@ -3222,12 +3291,25 @@ async function runAgentHeadlessInWorkspace(
   } catch (err) {
     const runtimeLedgerPersistenceFailed =
       err?.runtimeLedgerPersistence === true;
+    const sessionBudgetFailed =
+      err?.code === "CC_SESSION_BUDGET_EXHAUSTED" ||
+      err?.code === "CC_SESSION_BUDGET_USAGE_UNKNOWN" ||
+      options.sessionBudget?.signal?.aborted === true;
     const message = runtimeLedgerPersistenceFailed
       ? RUNTIME_LEDGER_PERSISTENCE_FAILURE_MESSAGE
-      : err?.message || String(err);
+      : err?.code === "CC_SESSION_BUDGET_USAGE_UNKNOWN"
+        ? err.message
+        : sessionBudgetFailed
+          ? sessionBudgetAdmissionError(
+            options.sessionBudget?.reason?.() || err?.budgetReason,
+            "run",
+          ).message
+          : err?.message || String(err);
     const errorSubtype = runtimeLedgerPersistenceFailed
       ? "error_persistence"
-      : "error";
+      : sessionBudgetFailed
+        ? "error_session_budget"
+        : "error";
     if (isStream) {
       emitStream({
         type: "result",
@@ -3258,7 +3340,10 @@ async function runAgentHeadlessInWorkspace(
     // Provider/transport failures get their own exit code (5) so CI can tell
     // "the model call failed" from "the run itself errored" (1).
     loopFailureOutcome = {
-      exitCode: runtimeLedgerPersistenceFailed ? 1 : classifyLoopError(err),
+      exitCode:
+        runtimeLedgerPersistenceFailed || sessionBudgetFailed
+          ? 1
+          : classifyLoopError(err),
       result: message,
       isError: true,
     };
@@ -3298,8 +3383,9 @@ async function runAgentHeadlessInWorkspace(
     await cleanupDeadline.run("settings-hooks", async () => {
       if (settingsHooks) {
         try {
-          const { runObserveHooks, dispatchAsyncHooks } =
-            await import("../lib/settings-hook-events.js");
+          const { runObserveHooks, dispatchAsyncHooks } = await import(
+            "../lib/settings-hook-events.js"
+          );
           const stopPayload = {
             reason: pipeState.closed ? "pipe_closed" : endReason,
             cwd,
@@ -3497,6 +3583,7 @@ async function runAgentHeadlessInWorkspace(
               provider,
               model,
               source: "model",
+              sessionBudget: options.sessionBudget || null,
               call: () =>
                 chatWithTools([{ role: "user", content: assessPrompt }], {
                   model,
@@ -3561,8 +3648,9 @@ async function runAgentHeadlessInWorkspace(
       emitStream({ type: "denials_summary", count: denials.length, denials });
     }
     try {
-      const { appendRecentDenials } =
-        await import("../lib/permission-denial-store.js");
+      const { appendRecentDenials } = await import(
+        "../lib/permission-denial-store.js"
+      );
       appendRecentDenials(denials, {
         sessionId,
         permissionMode: options.permissionMode || "default",
@@ -3633,8 +3721,9 @@ async function runAgentHeadlessInWorkspace(
     }
     if (_collectorEnabled) {
       try {
-        const { exportTelemetryRecorder } =
-          await import("../lib/observability/index.js");
+        const { exportTelemetryRecorder } = await import(
+          "../lib/observability/index.js"
+        );
         exportTelemetryRecorder(_otlpRecorder);
       } catch {
         // Telemetry is observational only and never changes the agent result.