chainlesschain 0.162.176 → 0.162.178

package/src/runtime/coding-agent-contract-shared.cjs

@@ -876,6 +876,22 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
           type: "number",
           description: "Max wait for user reply in ms (default: 60000)",
         },
+        defaultValue: {
+          description:
+            "Fallback answer used only when onTimeout/onReject is useDefault",
+        },
+        onTimeout: {
+          type: "string",
+          enum: ["error", "useDefault", "skip"],
+          description:
+            "Timeout policy: error (default), useDefault, or skip with a null answer",
+        },
+        onReject: {
+          type: "string",
+          enum: ["error", "useDefault", "skip"],
+          description:
+            "User-rejection policy: error (default), useDefault, or skip with a null answer",
+        },
       },
       required: ["question"],
     },

package/src/runtime/headless-runner.js

@@ -61,6 +61,7 @@ import { SIDE_EFFECT_LEDGER_EVENT } from "../lib/side-effect-ledger-store.js";
 import { TurnBindingLog, createTurnBindingFeed } from "../lib/turn-binding.js";
 import { TURN_BINDING_EVENT } from "../lib/turn-binding-store.js";
 import { operationIdempotencyKey } from "../lib/idempotency.js";
+import { CLISkillLoader } from "../lib/skill-loader.js";
 import { expandFileRefsAsync } from "./file-ref-expander.js";
 import { composeSystemPrompt } from "./system-prompt.js";
 import { buildUserContent } from "../lib/image-input.js";
@@ -79,6 +80,7 @@ import {
 } from "../lib/exit-codes.cjs";
 import { isolationLevel } from "../lib/agent-sandbox.js";
 import { createBackgroundPhaseReporter } from "../lib/background-phase-reporter.js";
+import { createBackgroundInteractionClient } from "../lib/background-interaction-resolver.js";
 import { withQuietStdout } from "./quiet-stdout.js";
 import { CostBudget } from "../lib/cost-budget.js";
 import { estimateTokens } from "../harness/prompt-compressor.js";
@@ -87,6 +89,23 @@ import {
   recordDenial,
   formatDenials,
 } from "../lib/repl-denials.js";
+import executionBroker from "../lib/process-execution-broker/index.js";
+
+const goalBrokerRunner = executionBroker.spawnSync.bind(executionBroker);
+
+export const _goalProcessDeps = {
+  run: goalBrokerRunner,
+};
+
+function runHeadlessGoalCommand(command, options = {}) {
+  return _goalProcessDeps.run(command, [], {
+    ...options,
+    timeout: options.timeout ?? 30000,
+    origin: "headless-goal:exit-zero",
+    policy: "allow",
+    scope: "headless-goal",
+  });
+}
 
 /** Tools that cannot mutate the filesystem or run commands. */
 export const READ_ONLY_TOOLS = Object.freeze([
@@ -717,21 +736,51 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     deps.backgroundPhaseReporter || createBackgroundPhaseReporter();
 
   const sideEffectRunNonce = String(deps.now ? deps.now() : Date.now());
+  const _backgroundPolicyDigest = _bgPhase.enabled
+    ? computePolicyDigest({
+        permissionMode: options.permissionMode,
+        allowedTools: options.allowedTools,
+        disallowedTools: options.disallowedTools,
+        permissionRules,
+      })
+    : null;
+  const _backgroundInteraction = _bgPhase.enabled
+    ? deps.backgroundInteractionClient ||
+      createBackgroundInteractionClient({
+        backgroundAgentId: process.env.CC_BACKGROUND_AGENT_ID,
+        sessionId,
+        // One headless invocation is one user turn even when its model/tool
+        // loop contains several internal iterations.
+        turnId: options.turnId || sideEffectRunNonce,
+      })
+    : null;
   let sideEffectLedger = new SideEffectLedger({ clock: deps.now || null });
+  let sideEffectLedgerLoadError = null;
   let sideEffectSeq = 0;
   let currentSideEffectOpId = null;
   let resumeSideEffectContext = null;
   let resumeAsyncHookContext = null;
   const persistSideEffectLedger = () => {
     if (!persist) return;
+    if (sideEffectLedgerLoadError) throw sideEffectLedgerLoadError;
     try {
-      store.appendEvent(
+      const persisted = store.appendEvent(
         sessionId,
         SIDE_EFFECT_LEDGER_EVENT,
         sideEffectLedger.toJSON(),
       );
-    } catch {
-      // best-effort — never fail the run over ledger persistence
+      if (persisted === false) {
+        throw new Error("session store rejected the ledger snapshot");
+      }
+    } catch (cause) {
+      const error = new Error(
+        `Side-effect ledger persistence failed for ${sessionId}: ${
+          cause?.message || String(cause)
+        }`,
+        { cause },
+      );
+      error.code = "SIDE_EFFECT_LEDGER_PERSIST_FAILED";
+      throw error;
     }
   };
   // P1 explicit turn→checkpoint binding: feed the TurnBindingLog in real time
@@ -744,6 +793,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   // context. Only writes when a turn actually recorded something, and only for
   // persisted runs — a tool-free Q&A or ephemeral run stays byte-identical.
   let turnBindingLog = new TurnBindingLog();
+  let turnBindingLoadError = null;
   if (persist) {
     try {
       const events = store.readEvents(sessionId) || [];
@@ -759,8 +809,15 @@ export async function runAgentHeadless(options = {}, deps = {}) {
           break;
         }
       }
-    } catch {
-      // fresh log — best effort
+    } catch (cause) {
+      const error = new Error(
+        `Turn binding read failed for ${sessionId}: ${
+          cause?.message || String(cause)
+        }`,
+        { cause },
+      );
+      error.code = "TURN_BINDING_READ_FAILED";
+      turnBindingLoadError = error;
     }
   }
   // Event→table folding + id synthesis live in the SHARED feeder core
@@ -771,11 +828,26 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     : null;
   const persistTurnBindingLog = () => {
     if (!turnBindingFeed || !turnBindingFeed.isDirty()) return;
+    if (turnBindingLoadError) throw turnBindingLoadError;
     try {
-      store.appendEvent(sessionId, TURN_BINDING_EVENT, turnBindingLog.toJSON());
+      const persisted = store.appendEvent(
+        sessionId,
+        TURN_BINDING_EVENT,
+        turnBindingLog.toJSON(),
+      );
+      if (persisted === false) {
+        throw new Error("session store rejected the binding snapshot");
+      }
       turnBindingFeed.clearDirty();
-    } catch {
-      // best-effort — never fail the run over binding persistence
+    } catch (cause) {
+      const error = new Error(
+        `Turn binding persistence failed for ${sessionId}: ${
+          cause?.message || String(cause)
+        }`,
+        { cause },
+      );
+      error.code = "TURN_BINDING_PERSIST_FAILED";
+      throw error;
     }
   };
   if (persist) {
@@ -795,8 +867,17 @@ export async function runAgentHeadless(options = {}, deps = {}) {
           break;
         }
       }
-    } catch {
-      // fresh ledger — best effort
+    } catch (cause) {
+      const error = new Error(
+        `Side-effect ledger read failed for ${sessionId}: ${
+          cause?.message || String(cause)
+        }`,
+        { cause },
+      );
+      error.code = "SIDE_EFFECT_LEDGER_READ_FAILED";
+      // Keep read-only turns available; classified side effects call the
+      // persistence gate above before the generator can execute the tool.
+      sideEffectLedgerLoadError = error;
     }
     // On resume, surface any operation that was in flight when the prior run
     // died: its outcome is UNKNOWN, so the model is told to VERIFY before any
@@ -951,10 +1032,19 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   const _leanNoProjectMemory = options.projectMemory === false;
   let _loadedInstructions = null;
   let _loadedPersonaSkills = [];
+  let _skillCacheLedger = null;
+  const _runtimeSkillLoader =
+    options.skillLoader || new CLISkillLoader();
   const systemContent = composeSystemPrompt(
     buildSystemPrompt(cwd, {
       additionalDirectories,
       projectMemory: options.projectMemory,
+      sessionId,
+      skillLoader: _runtimeSkillLoader,
+      onSkillsLoaded: (skills, cacheLedger) => {
+        _loadedPersonaSkills = Array.isArray(skills) ? skills : [];
+        _skillCacheLedger = cacheLedger || null;
+      },
     }),
     {
       systemPrompt: options.systemPrompt,
@@ -965,9 +1055,6 @@ export async function runAgentHeadless(options = {}, deps = {}) {
       onInstructionsLoaded: (loaded) => {
         _loadedInstructions = loaded;
       },
-      onSkillsLoaded: (skills) => {
-        _loadedPersonaSkills = Array.isArray(skills) ? skills : [];
-      },
     },
   );
 
@@ -975,7 +1062,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   if (settingsHooks) {
     try {
       const { runUserPromptSubmitHooks } =
-        await import("../lib/settings-hook-events.cjs");
+        await import("../lib/settings-hook-events.js");
       const ups = runUserPromptSubmitHooks(settingsHooks, {
         prompt: userContent,
         cwd,
@@ -1006,7 +1093,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   if (settingsHooks && _loadedInstructions) {
     try {
       const { runInstructionsLoadedHooks } =
-        await import("../lib/settings-hook-events.cjs");
+        await import("../lib/settings-hook-events.js");
       instructionsLoadedContext = runInstructionsLoadedHooks(settingsHooks, {
         files: _loadedInstructions.files,
         cwd,
@@ -1022,7 +1109,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   if (settingsHooks) {
     try {
       const { runSessionStartHooks } =
-        await import("../lib/settings-hook-events.cjs");
+        await import("../lib/settings-hook-events.js");
       sessionStartContext = runSessionStartHooks(settingsHooks, {
         source: resumeId ? "resume" : "startup",
         cwd,
@@ -1041,7 +1128,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   if (settingsHooks && resumeId && history.length > 0) {
     try {
       const { runObserveHooks } =
-        await import("../lib/settings-hook-events.cjs");
+        await import("../lib/settings-hook-events.js");
       runObserveHooks(
         settingsHooks,
         "SessionResume",
@@ -1313,7 +1400,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   if (settingsHooks) {
     try {
       const { AsyncHookSupervisor } =
-        await import("../lib/async-hook-supervisor.cjs");
+        await import("../lib/async-hook-supervisor.js");
       _hookSupervisor = new AsyncHookSupervisor({
         persistStats: true,
         // Durably park failed-rewake signals keyed by session so a crash before
@@ -1350,10 +1437,17 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   // Persist the admitted runtime schema surface so `cc context --sources` can
   // attribute MCP cost to the actual server/tool definitions used by this run,
   // rather than guessing from the current environment on a later invocation.
-  if (
-    persist &&
-    (mcp?.extraToolDefinitions?.length || _loadedPersonaSkills.length)
-  ) {
+  const persistContextSources = () => {
+    if (!persist) return false;
+    _skillCacheLedger =
+      _runtimeSkillLoader.getCacheLedger?.() || _skillCacheLedger;
+    if (
+      !mcp?.extraToolDefinitions?.length &&
+      !_loadedPersonaSkills.length &&
+      !_skillCacheLedger?.descriptors?.resident
+    ) {
+      return false;
+    }
     try {
       store.appendEvent(sessionId, "context_sources", {
         mcp: (mcp?.extraToolDefinitions || []).map((definition) => ({
@@ -1367,13 +1461,22 @@ export async function runAgentHeadless(options = {}, deps = {}) {
           id: skill?.id || skill?.displayName || "skill",
           displayName: skill?.displayName || skill?.id || "skill",
           source: skill?.source || "skill",
-          body: typeof skill?.body === "string" ? skill.body : "",
+          tokens: estimateTokens(
+            `## Persona: ${skill?.displayName || skill?.id || "skill"}\n${
+              typeof skill?.body === "string" ? skill.body : ""
+            }`,
+          ),
+          bodyLoaded: skill?.bodyLoaded === true,
         })),
+        skillCache: _skillCacheLedger,
       });
+      return true;
     } catch {
       // Source attribution is observability-only; never fail the agent run.
+      return false;
     }
-  }
+  };
+  persistContextSources();
 
   const loopOptions = {
     model,
@@ -1392,6 +1495,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     baseUrl,
     apiKey,
     cwd,
+    skillLoader: _runtimeSkillLoader,
     additionalDirectories,
     sandbox: options.sandbox || null,
     sessionId,
@@ -1418,27 +1522,39 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     disabledTools,
     iterationBudget: budget,
     toolAdmission: options.toolAdmission || null,
-    // `ask_user_question` in a BACKGROUND turn child (P0 state-machine
-    // producer for `needs_input`): there is no live channel to a human
-    // mid-turn, but the question IS the structured needs-input signal. Park
-    // it — record `phase: "needs_input"` + the question in the shared state
-    // file (dashboard "Needs input" gets real data; the user's reply arrives
-    // as the next attach prompt) and tell the model to end the turn. A
-    // non-background run supplies no interaction → the handler's existing
-    // `user_not_reachable` path stays byte-identical.
+    // `ask_user_question` in a BACKGROUND turn child: send a bound request to
+    // the worker over Node IPC and await the answer here. `executeTool` remains
+    // suspended, so the model continues the SAME turn/tool call after the user
+    // answers instead of receiving the answer as a follow-up turn.
     ...(_bgPhase.enabled
       ? {
           interaction: {
-            askUser: async ({ question, options: qOptions } = {}) => {
+            askUser: async ({
+              question,
+              options: qOptions,
+              multiSelect,
+              timeoutMs,
+              defaultValue,
+              toolUseId,
+              turnId,
+              policyDigest,
+            } = {}) => {
               _bgPhase.reportQuestion({
                 question: typeof question === "string" ? question : "",
                 options: Array.isArray(qOptions) ? qOptions : null,
               });
-              throw new Error(
-                "question parked for the user (background session). End this " +
-                  "turn now — the user's reply will arrive as the next " +
-                  "message. Do not repeat the question.",
-              );
+              return _backgroundInteraction.request({
+                kind: "question",
+                question,
+                options: qOptions,
+                multiSelect,
+                timeoutMs,
+                defaultValue,
+                toolUseId,
+                turnId,
+                policyDigest: policyDigest || _backgroundPolicyDigest,
+                sessionId,
+              });
             },
           },
         }
@@ -1603,7 +1719,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   const _settleAsyncStop = async () => {
     if (!settingsHooks || !_hookSupervisor) return { rewakes: [], results: [] };
     const { dispatchAsyncHooks } =
-      await import("../lib/settings-hook-events.cjs");
+      await import("../lib/settings-hook-events.js");
     dispatchAsyncHooks(
       settingsHooks,
       "Stop",
@@ -1783,7 +1899,6 @@ export async function runAgentHeadless(options = {}, deps = {}) {
   process.once("SIGTERM", _onHardSignal);
 
   try {
-    // eslint-disable-next-line no-constant-condition
     while (true) {
       // P1 turn→checkpoint binding: one drain of the loop = one turn. Anchor
       // the conversation offset before the model sees the new user turn. A
@@ -1808,10 +1923,15 @@ export async function runAgentHeadless(options = {}, deps = {}) {
             if (isText) writeErr(line + "\n");
             emitStream({
               type: "tool_use",
+              ...(event.tool_use_id ? { id: event.tool_use_id } : {}),
+              tool: event.tool,
+              args: event.args,
+            });
+            toolCalls.push({
+              ...(event.tool_use_id ? { id: event.tool_use_id } : {}),
               tool: event.tool,
               args: event.args,
             });
-            toolCalls.push({ tool: event.tool, args: event.args });
             // P0-2: record an irreversible effect as STARTED (persisted before
             // it settles) so a crash before the matching tool-result leaves a
             // reconcilable "in flight" marker instead of a silent replay.
@@ -1866,6 +1986,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
             if (isText && err) writeErr(`  Error: ${err}\n`);
             emitStream({
               type: "tool_result",
+              ...(event.tool_use_id ? { id: event.tool_use_id } : {}),
               tool: event.tool,
               is_error: Boolean(err),
               error: err,
@@ -2085,8 +2206,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
         try {
           if (_goalHelpers.isDeterministicCondition(cond)) {
             const gc = deps.goalCheck || {};
-            const spawnSync =
-              gc.spawnSync || (await import("node:child_process")).spawnSync;
+            const spawnSync = gc.spawnSync || runHeadlessGoalCommand;
             const existsSync =
               gc.existsSync || (await import("node:fs")).existsSync;
             evaluation = _goalHelpers.runDeterministicCheck(cond, {
@@ -2183,6 +2303,14 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     // "the model call failed" from "the run itself errored" (1).
     return { exitCode: classifyLoopError(err), result: message, isError: true };
   } finally {
+    // Capture body-cache hits/misses caused by list_skills/run_skill during the
+    // turn. `cc context --sources` reads the newest snapshot.
+    persistContextSources();
+    try {
+      _backgroundInteraction?.close?.();
+    } catch {
+      // Best-effort listener cleanup; never mask the run result.
+    }
     // Drop the signal handlers first — a normal return must not leave a
     // process-wide SIGINT/SIGTERM listener behind (a later Ctrl-C would wrongly
     // exit with 130, and repeated in-process runs would leak listeners).
@@ -2221,7 +2349,7 @@ export async function runAgentHeadless(options = {}, deps = {}) {
     if (settingsHooks) {
       try {
         const { runObserveHooks, dispatchAsyncHooks } =
-          await import("../lib/settings-hook-events.cjs");
+          await import("../lib/settings-hook-events.js");
         const stopPayload = { reason: endReason, cwd, session_id: sessionId };
         runObserveHooks(settingsHooks, "Stop", stopPayload, { cwd });
         // Skip the async Stop dispatch/settle here if the auto-rewake re-drive