chainlesschain 0.165.1 → 0.165.3

package/src/runtime/agent-core.js

@@ -3583,6 +3583,10 @@ export async function executeTool(name, args, context = {}) {
       sessionId: context.sessionId || null,
       turnId: context.turnId || null,
       toolCallId: context.toolCallId || null,
+      workflowEffectId: context.workflowEffectId || null,
+      workflowChildEffectId: context.workflowChildEffectId || null,
+      workflowChildSequence: context.workflowChildSequence || null,
+      workflowEffectProtocol: context.workflowEffectProtocol || null,
       // Parent LLM config — documented at toolContext as forwarded to
       // spawn_sub_agent for provider/key inheritance; without this line it
       // never actually reached executeToolInner (sub-agents silently fell
@@ -4969,6 +4973,10 @@ async function executeToolInner(
     sessionId,
     turnId,
     toolCallId,
+    workflowEffectId = null,
+    workflowChildEffectId = null,
+    workflowChildSequence = null,
+    workflowEffectProtocol = null,
     planManager = null,
     permissionRules = null,
     effectiveAllowedToolNames = null,
@@ -6713,6 +6721,10 @@ async function executeToolInner(
           interaction,
           sessionId,
           llmOptions,
+          workflowEffectId,
+          workflowChildEffectId,
+          workflowChildSequence,
+          workflowEffectProtocol,
           subAgentDepth,
           subAgentBudget,
           sessionBudget,
@@ -7646,6 +7658,9 @@ async function executeToolInner(
             ? event
             : {
                 ...event,
+                ...(["model", "semantic-compaction"].includes(event?.source)
+                  ? { workflowRequestSource: event.source }
+                  : {}),
                 source:
                   event?.source === "semantic-compaction"
                     ? "semantic-compaction"
@@ -7721,6 +7736,9 @@ async function executeToolInner(
             toolAdmission,
             cwd,
             llmOptions: skillLlmOptions,
+            ...(strictUsageTelemetry === true && workflowChildEffectId
+              ? { workflowEffectId: workflowChildEffectId }
+              : {}),
             ...(sessionBudget ? { sessionBudget } : {}),
             ...(permissionRules ? { permissionRules } : {}),
             ...(hostManagedToolPolicy
@@ -7811,7 +7829,12 @@ async function executeToolInner(
             toolsUsed: result.toolsUsed,
           });
         } catch (err) {
-          if (err?.runtimeLedgerPersistence === true) throw err;
+          if (
+            err?.runtimeLedgerPersistence === true ||
+            err?.workflowEffectOutcomeUnknown === true
+          ) {
+            throw err;
+          }
           if (
             signal?.aborted ||
             skillExecutionSignal?.aborted ||
@@ -8035,6 +8058,14 @@ async function executeToolInner(
             ledgerTicket = await ledger.begin({
               sessionId,
               turnId,
+              ...(workflowEffectId
+                ? {
+                    workflowEffectId,
+                    workflowChildEffectId,
+                    workflowChildSequence,
+                    workflowEffectProtocol,
+                  }
+                : {}),
               toolName: localToolExecutor.toolName,
               serverName: localToolExecutor.serverName,
               input: mcpWireInput,
@@ -8108,12 +8139,20 @@ async function executeToolInner(
               localToolExecutor.toolName,
               mcpWireInput,
             ];
-            if (signal || mcpDispatchAdmission) {
+            if (signal || mcpDispatchAdmission || workflowEffectId) {
               callArguments.push({
                 ...(signal ? { signal } : {}),
                 ...(mcpDispatchAdmission
                   ? { dispatchAdmission: mcpDispatchAdmission }
                   : {}),
+                ...(workflowEffectId
+                  ? {
+                      workflowEffectId,
+                      workflowChildEffectId,
+                      workflowChildSequence,
+                      workflowEffectProtocol,
+                    }
+                  : {}),
               });
             }
             pendingResult = Reflect.apply(
@@ -8242,8 +8281,9 @@ async function executeToolInner(
             );
           }
 
+          let settledLedgerRecord;
           try {
-            await ledgerTicket.settle(
+            settledLedgerRecord = await ledgerTicket.settle(
               protocolError
                 ? {
                     status: "failed",
@@ -8265,11 +8305,26 @@ async function executeToolInner(
           }
 
           const mcpLedgerId = safeMcpProperty(ledgerTicket, "ledgerId") || null;
+          const mcpLedgerPrewritePersisted =
+            safeMcpProperty(ledgerTicket, "prewritePersisted") === true;
+          const mcpLedgerSettlementPersisted =
+            safeMcpProperty(settledLedgerRecord, "settlementPersistence") ===
+            "persisted";
           try {
             if (result && typeof result === "object") {
-              return attachDescriptor({ ...result, mcpLedgerId });
+              return attachDescriptor({
+                ...result,
+                mcpLedgerId,
+                mcpLedgerPrewritePersisted,
+                mcpLedgerSettlementPersisted,
+              });
             }
-            return attachDescriptor({ result, mcpLedgerId });
+            return attachDescriptor({
+              result,
+              mcpLedgerId,
+              mcpLedgerPrewritePersisted,
+              mcpLedgerSettlementPersisted,
+            });
           } catch (projectionError) {
             return attachDescriptor({
               error:
@@ -8296,7 +8351,18 @@ async function executeToolInner(
         interaction &&
         typeof interaction.requestHostTool === "function"
       ) {
-        const hostedResult = await interaction.requestHostTool(name, args);
+        const hostedResult = workflowEffectId
+          ? await interaction.requestHostTool(
+              name,
+              args,
+              Object.freeze({
+                workflowEffectId,
+                workflowChildEffectId,
+                workflowChildSequence,
+                workflowEffectProtocol,
+              }),
+            )
+          : await interaction.requestHostTool(name, args);
         if (hostedResult?.success === false) {
           return attachDescriptor({
             error:
@@ -8959,7 +9025,12 @@ function _backgroundSubAgentResultText(entry) {
 
 function _throwBackgroundSubAgentUsageFailure(entry) {
   const error = entry?.outcome?.fatalError;
-  if (error?.runtimeLedgerPersistence === true) throw error;
+  if (
+    error?.runtimeLedgerPersistence === true ||
+    error?.workflowEffectOutcomeUnknown === true
+  ) {
+    throw error;
+  }
 }
 
 function _throwSettledBackgroundUsageFailure(map) {
@@ -9514,6 +9585,9 @@ async function _executeSpawnSubAgent(args, ctx) {
       ? u
       : {
           ...u,
+          ...(["model", "semantic-compaction"].includes(u?.source)
+            ? { workflowRequestSource: u.source }
+            : {}),
           source:
             u?.source === "semantic-compaction"
               ? "semantic-compaction"
@@ -9663,6 +9737,9 @@ async function _executeSpawnSubAgent(args, ctx) {
     cwd: ctx.cwd,
     profile: profile || null,
     llmOptions: subLlmOptions,
+    ...(ctx.strictUsageTelemetry === true && ctx.workflowChildEffectId
+      ? { workflowEffectId: ctx.workflowChildEffectId }
+      : {}),
     depth: currentDepth + 1, // nested spawns see their own level
     // Same shared counter object so the child's own spawns draw from the run's
     // single total-sub-agent pool (breadth cap spans the whole tree).
@@ -9864,7 +9941,8 @@ async function _executeSpawnSubAgent(args, ctx) {
           return {
             result: subCtx.result,
             error: err.message,
-            ...(err?.runtimeLedgerPersistence === true
+            ...(err?.runtimeLedgerPersistence === true ||
+            err?.workflowEffectOutcomeUnknown === true
               ? { fatalError: err }
               : {}),
           };
@@ -9997,7 +10075,12 @@ async function _executeSpawnSubAgent(args, ctx) {
       completedAt: subCtx.completedAt,
     });
 
-    if (err?.runtimeLedgerPersistence === true) throw err;
+    if (
+      err?.runtimeLedgerPersistence === true ||
+      err?.workflowEffectOutcomeUnknown === true
+    ) {
+      throw err;
+    }
 
     return {
       error: `Sub-agent failed: ${err.message}`,
@@ -10077,6 +10160,72 @@ function _hasCompleteProviderUsage(usage) {
   );
 }
 
+const PROVIDER_REQUEST_ID_RE = /^[\x21-\x7e]{1,512}$/;
+const PROVIDER_RECEIPT_ID_RE = /^[A-Za-z0-9._:-]{1,256}$/;
+
+function _normalizeProviderRequestId(value) {
+  if (value == null) return null;
+  if (typeof value !== "string" || !PROVIDER_REQUEST_ID_RE.test(value)) {
+    throw new TypeError(
+      "providerRequestId must be 1-512 printable ASCII characters",
+    );
+  }
+  return value;
+}
+
+function _physicalProviderRequestId(logicalRequestId, attempt) {
+  if (!logicalRequestId) return null;
+  const retry = Number(attempt);
+  if (!Number.isSafeInteger(retry) || retry <= 0) return logicalRequestId;
+  const suffix = `-r${retry}`;
+  return `${logicalRequestId.slice(0, 512 - suffix.length)}${suffix}`;
+}
+
+function _providerReceiptId(value) {
+  return typeof value === "string" && PROVIDER_RECEIPT_ID_RE.test(value)
+    ? value
+    : null;
+}
+
+function _isOfficialOpenAIEndpoint(provider, baseUrl) {
+  if (provider !== "openai") return false;
+  try {
+    const parsed = new URL(String(baseUrl));
+    return (
+      parsed.protocol === "https:" &&
+      parsed.hostname.toLowerCase() === "api.openai.com" &&
+      !parsed.port &&
+      !parsed.username &&
+      !parsed.password
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Capture only provider-returned identifiers. X-Client-Request-Id is a
+ * trace/correlation header, not an idempotency guarantee, so a locally sent
+ * client id alone is deliberately not called a receipt.
+ */
+function _openAIProviderRequestReceipt(response, data, clientRequestId) {
+  if (!clientRequestId) return null;
+  const requestId = _providerReceiptId(
+    response?.headers?.get?.("x-request-id"),
+  );
+  const responseId = _providerReceiptId(data?.id);
+  if (!requestId && !responseId) return null;
+  return Object.freeze({
+    protocol: "cc-provider-request-receipt/v1",
+    provider: "openai",
+    clientRequestId,
+    requestId,
+    responseId,
+    requestIdentitySemantics: "trace-only",
+    independentlyReadable: false,
+  });
+}
+
 /**
  * Send a chat completion request with tool definitions.
  * Supports 8 providers: ollama, anthropic, openai, deepseek, dashscope, gemini, mistral, volcengine
@@ -10095,6 +10244,10 @@ export async function chatWithTools(rawMessages, options) {
     signal,
   } = options;
 
+  const providerRequestId = _normalizeProviderRequestId(
+    options.providerRequestId,
+  );
+
   const tools = getEffectiveToolDefinitions(options);
 
   const lastUserMsg = [...rawMessages].reverse().find((m) => m.role === "user");
@@ -10140,6 +10293,7 @@ export async function chatWithTools(rawMessages, options) {
           ),
         {
           signal,
+          retries: options.workflowEffectId ? 0 : undefined,
           strictRetryObserver: options.strictUsageTelemetry === true,
           ...(typeof options.onStreamRetry === "function"
             ? {
@@ -10289,6 +10443,7 @@ export async function chatWithTools(rawMessages, options) {
           ),
         {
           signal,
+          retries: options.workflowEffectId ? 0 : undefined,
           strictRetryObserver: options.strictUsageTelemetry === true,
           ...(typeof options.onStreamRetry === "function"
             ? {
@@ -10381,6 +10536,10 @@ export async function chatWithTools(rawMessages, options) {
       `Unsupported provider: ${provider}. Supported: ollama, anthropic, openai, deepseek, dashscope, mistral, gemini, volcengine`,
     );
   }
+  const supportsOpenAIRequestIdentity = _isOfficialOpenAIEndpoint(
+    provider,
+    url,
+  );
 
   const envKey = providerApiKeyEnvs[provider] || "OPENAI_API_KEY";
   const key = apiKey || process.env[envKey];
@@ -10392,7 +10551,7 @@ export async function chatWithTools(rawMessages, options) {
     dashscope: "qwen-turbo",
     mistral: "mistral-large-latest",
     gemini: "gemini-2.0-flash",
-    volcengine: "doubao-seed-2-1-pro-260628",
+    volcengine: "deepseek-v4-flash-260425",
   };
 
   // Real token streaming (--include-partial-messages) for every OpenAI-compatible
@@ -10401,7 +10560,7 @@ export async function chatWithTools(rawMessages, options) {
   // delta-fragmented tool_calls into the standard {message, usage} shape.
   if (typeof options.onToken === "function") {
     return await _retryStreamingChat(
-      () =>
+      (attempt = 0) =>
         _chatOpenAIStreaming(
           `${url}/chat/completions`,
           {
@@ -10421,9 +10580,13 @@ export async function chatWithTools(rawMessages, options) {
           options.onStall,
           options.streamStallMs,
           options.streamStallTimeoutMs,
+          supportsOpenAIRequestIdentity
+            ? _physicalProviderRequestId(providerRequestId, attempt)
+            : null,
         ),
       {
         signal,
+        retries: options.workflowEffectId ? 0 : undefined,
         strictRetryObserver: options.strictUsageTelemetry === true,
         ...(typeof options.onStreamRetry === "function"
           ? {
@@ -10444,6 +10607,9 @@ export async function chatWithTools(rawMessages, options) {
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${key}`,
+      ...(supportsOpenAIRequestIdentity && providerRequestId
+        ? { "X-Client-Request-Id": providerRequestId }
+        : {}),
     },
     signal,
     body: JSON.stringify({
@@ -10466,6 +10632,10 @@ export async function chatWithTools(rawMessages, options) {
   }
   const choice = data.choices[0];
   const out = { message: choice.message };
+  const providerReceipt = supportsOpenAIRequestIdentity
+    ? _openAIProviderRequestReceipt(response, data, providerRequestId)
+    : null;
+  if (providerReceipt) out.providerReceipt = providerReceipt;
   if (_hasCompleteProviderUsage(data.usage)) {
     // OpenAI/DeepSeek/volcengine report cached prompt tokens AS PART of
     // prompt_tokens — split them out so cost prices the cached prefix at the
@@ -10708,7 +10878,7 @@ export async function _retryStreamingChat(streamFn, opts = {}) {
   for (;;) {
     const attemptStartedAt = now();
     try {
-      return await streamFn();
+      return await streamFn(attempt);
     } catch (err) {
       if (attempt >= retries || !_isRetryableStreamError(err, signal))
         throw err;
@@ -11188,6 +11358,7 @@ function _openaiCachedTokens(usage) {
 
 function _openaiInitState() {
   return {
+    responseId: null,
     text: "",
     tools: [],
     inputTokens: null,
@@ -11208,6 +11379,7 @@ function _openaiReduceLine(state, raw, onToken) {
   } catch {
     return state;
   }
+  if (!state.responseId) state.responseId = _providerReceiptId(obj.id);
   const delta = obj.choices?.[0]?.delta;
   if (delta?.content) {
     state.text += delta.content;
@@ -11294,12 +11466,16 @@ async function _chatOpenAIStreaming(
   onStall,
   stallMs,
   stallTimeoutMs,
+  providerRequestId = null,
 ) {
   const response = await fetch(apiUrl, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${apiKey}`,
+      ...(providerRequestId
+        ? { "X-Client-Request-Id": providerRequestId }
+        : {}),
     },
     signal,
     body: JSON.stringify(body),
@@ -11333,9 +11509,23 @@ async function _chatOpenAIStreaming(
   } catch (err) {
     if (_streamErrorDisposition(err, signal, state.text) === "rethrow")
       throw err;
-    return _finalizeTruncatedStream(_openaiFinalize, state);
-  }
-  return _openaiFinalize(state);
+    const out = _finalizeTruncatedStream(_openaiFinalize, state);
+    const providerReceipt = _openAIProviderRequestReceipt(
+      response,
+      { id: state.responseId },
+      providerRequestId,
+    );
+    if (providerReceipt) out.providerReceipt = providerReceipt;
+    return out;
+  }
+  const out = _openaiFinalize(state);
+  const providerReceipt = _openAIProviderRequestReceipt(
+    response,
+    { id: state.responseId },
+    providerRequestId,
+  );
+  if (providerReceipt) out.providerReceipt = providerReceipt;
+  return out;
 }
 
 /**
@@ -11632,6 +11822,7 @@ function _managedCheckpointUncoveredWriterReason(toolContext) {
  *   { type: "tool-executing", tool, args }
  *   { type: "tool-result", tool, result, error }
  *   { type: "model-usage-started", callId, provider, model, source }
+ *   { type: "provider-request-receipt", source, workflowEffectId, clientRequestId, requestId, responseId }
  *   { type: "token-usage", callId, provider, model, usage, source? }
  *   { type: "model-usage-unknown", callId, provider, model, source, code }
  *   { type: "response-complete", content }
@@ -11655,6 +11846,154 @@ function _newModelUsageCallId(source = "model") {
   return `${prefix}-${randomUUID()}`;
 }
 
+const WORKFLOW_EFFECT_ID_RE = /^sha256:[a-f0-9]{64}$/;
+const WORKFLOW_CHILD_EFFECT_PROTOCOL = "cc-workflow-child-effect/v1";
+const WORKFLOW_TOOL_CALL_ID_RE = /^[\x21-\x7e]{1,512}$/;
+
+function _normalizeWorkflowEffectId(value) {
+  if (value == null) return null;
+  if (typeof value !== "string" || !WORKFLOW_EFFECT_ID_RE.test(value)) {
+    throw new TypeError("workflowEffectId must be a canonical sha256 identity");
+  }
+  return value;
+}
+
+function _workflowProviderRequestId(workflowEffectId, source, sequence) {
+  if (!workflowEffectId) return null;
+  return `ccwf_${createHash("sha256")
+    .update(
+      `${workflowEffectId}\0${String(source || "model")}\0${String(sequence)}`,
+      "utf8",
+    )
+    .digest("hex")}`;
+}
+
+function _workflowToolEffectBinding(
+  workflowEffectId,
+  sequence,
+  toolCallId,
+  toolName,
+) {
+  if (!workflowEffectId) return null;
+  if (
+    !Number.isSafeInteger(sequence) ||
+    sequence < 1 ||
+    typeof toolCallId !== "string" ||
+    !WORKFLOW_TOOL_CALL_ID_RE.test(toolCallId) ||
+    typeof toolName !== "string" ||
+    !toolName
+  ) {
+    const error = new TypeError(
+      "workflow-bound tool call identity is malformed",
+    );
+    error.code = "CC_WORKFLOW_CHILD_EFFECT_IDENTITY_INVALID";
+    throw error;
+  }
+  const childEffectId = `sha256:${createHash("sha256")
+    .update(
+      `${workflowEffectId}\0tool\0${String(sequence)}\0${toolCallId}\0${toolName}`,
+      "utf8",
+    )
+    .digest("hex")}`;
+  return Object.freeze({
+    workflowEffectProtocol: WORKFLOW_CHILD_EFFECT_PROTOCOL,
+    workflowEffectId,
+    workflowChildEffectId: childEffectId,
+    workflowChildSequence: sequence,
+  });
+}
+
+function _workflowNestedToolOutcomeUnknown(binding, toolName, result) {
+  if (!binding || safeMcpProperty(result, "outcomeUnknown") !== true) {
+    return null;
+  }
+  const error = new Error(
+    `Workflow-bound nested tool ${toolName} has an unknown outcome and requires reconciliation`,
+  );
+  error.code = "CC_WORKFLOW_NESTED_TOOL_OUTCOME_UNKNOWN";
+  error.workflowEffectOutcomeUnknown = true;
+  error.workflowEffectId = binding.workflowEffectId;
+  error.workflowChildEffectId = binding.workflowChildEffectId;
+  return error;
+}
+
+function _workflowCompactionOutcomeUnknown(
+  cause,
+  code = "CC_WORKFLOW_COMPACTION_PROVIDER_OUTCOME_UNKNOWN",
+  message = "Workflow-bound semantic compaction provider outcome is unknown",
+) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.code = code;
+  error.workflowEffectOutcomeUnknown = true;
+  error.compactionFailureReported = false;
+  return error;
+}
+
+function _markWorkflowCompactionFailureReported(error) {
+  if (error?.workflowEffectOutcomeUnknown === true) {
+    error.compactionFailureReported = true;
+  }
+  return error;
+}
+
+function _snapshotProviderRequestReceipt(
+  value,
+  expectedClientRequestId,
+  expectedProvider,
+) {
+  if (value == null) return null;
+  if (isProxy(value)) {
+    throw new TypeError("provider request receipt must not be a Proxy");
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const expectedFields = [
+    "clientRequestId",
+    "independentlyReadable",
+    "protocol",
+    "provider",
+    "requestId",
+    "requestIdentitySemantics",
+    "responseId",
+  ];
+  const fields = Object.keys(descriptors).sort();
+  const hasOnlyDataFields =
+    fields.length === expectedFields.length &&
+    fields.every(
+      (field, index) =>
+        field === expectedFields[index] &&
+        Object.hasOwn(descriptors[field], "value") &&
+        descriptors[field].enumerable === true,
+    );
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    !hasOnlyDataFields ||
+    descriptors.protocol.value !== "cc-provider-request-receipt/v1" ||
+    !/^[a-z0-9][a-z0-9._-]{0,63}$/.test(descriptors.provider.value || "") ||
+    descriptors.provider.value !== expectedProvider ||
+    descriptors.clientRequestId.value !== expectedClientRequestId ||
+    descriptors.requestIdentitySemantics.value !== "trace-only" ||
+    descriptors.independentlyReadable.value !== false
+  ) {
+    throw new TypeError("provider request receipt is malformed");
+  }
+  const requestId = _providerReceiptId(descriptors.requestId.value);
+  const responseId = _providerReceiptId(descriptors.responseId.value);
+  if (!requestId && !responseId) {
+    throw new TypeError("provider request receipt has no provider identifier");
+  }
+  return Object.freeze({
+    protocol: "cc-provider-request-receipt/v1",
+    provider: descriptors.provider.value,
+    clientRequestId: expectedClientRequestId,
+    requestId,
+    responseId,
+    requestIdentitySemantics: "trace-only",
+    independentlyReadable: false,
+  });
+}
+
 function _runtimeUsageBoundaryFailure(error, code, fallbackMessage) {
   const failure =
     error && (typeof error === "object" || typeof error === "function")
@@ -11824,7 +12163,7 @@ function _assertStrictUsageObserver(observer, phase) {
 function _autoCompactionUsageState(options) {
   let state = _autoCompactionUsageStates.get(options);
   if (!state) {
-    state = { calls: [] };
+    state = { calls: [], callSequence: null };
     _autoCompactionUsageStates.set(options, state);
   }
   return state;
@@ -11848,27 +12187,59 @@ function _instrumentAutoCompactorUsage(compactor, options) {
   const original = installed?.original || compactor.llmQuery;
   const state = _autoCompactionUsageState(options);
   const wrapper = async function instrumentedCompactionQuery(...args) {
+    const workflowEffectId = _normalizeWorkflowEffectId(
+      options.workflowEffectId,
+    );
+    const callSequence =
+      Number.isSafeInteger(state.callSequence) && state.callSequence > 0
+        ? state.callSequence
+        : null;
+    if (workflowEffectId && callSequence == null) {
+      throw _runtimeUsageBoundaryFailure(
+        null,
+        "CC_COMPACTION_REQUEST_SEQUENCE_REQUIRED",
+        "Workflow-bound semantic compaction requires a stable call sequence",
+      );
+    }
+    const providerRequestId = _workflowProviderRequestId(
+      workflowEffectId,
+      "semantic-compaction",
+      callSequence,
+    );
     const call = {
       callId: _newModelUsageCallId("semantic-compaction"),
-      provider: options.provider || null,
-      model: options.model || null,
+      provider: options.provider || "ollama",
+      model: options.model || "unknown",
       source: "semantic-compaction",
+      workflowEffectId,
+      callSequence,
+      providerRequestId,
+      providerReceipt: null,
       observerError: null,
       observerFailed: false,
       boundaryNotified: false,
     };
     state.calls.push(call);
+    const boundaryEvent = {
+      type: "model-usage-started",
+      callId: call.callId,
+      provider: call.provider,
+      model: call.model,
+      source: call.source,
+      ...(providerRequestId
+        ? {
+            workflowEffectId,
+            callSequence,
+            providerRequestId,
+            requestIdentitySemantics: "trace-only",
+          }
+        : {}),
+    };
     try {
       if (typeof options.onUsageBoundary === "function") {
         // Synchronous and before `original`: a host can durably append the
         // start row, and any append failure prevents provider spend.
-        const observation = options.onUsageBoundary({
-          type: "model-usage-started",
-          callId: call.callId,
-          provider: call.provider,
-          model: call.model,
-          source: call.source,
-        });
+        const observation = options.onUsageBoundary(boundaryEvent);
         if (observation && typeof observation.then === "function") {
           void Promise.resolve(observation).catch(() => {});
           const error = new Error(
@@ -11879,13 +12250,54 @@ function _instrumentAutoCompactorUsage(compactor, options) {
         }
         call.boundaryNotified = true;
       }
+      if (
+        providerRequestId &&
+        typeof options.onProviderRequestBoundary === "function"
+      ) {
+        const observation = options.onProviderRequestBoundary(boundaryEvent);
+        if (observation && typeof observation.then === "function") {
+          void Promise.resolve(observation).catch(() => {});
+          throw _runtimeUsageBoundaryFailure(
+            null,
+            "CC_PROVIDER_REQUEST_BOUNDARY_ASYNC",
+            "Provider request boundary observer must be synchronous",
+          );
+        }
+      }
     } catch (error) {
       call.observerError = error;
       call.observerFailed = true;
       throw error;
     }
 
-    return await original.apply(this, args);
+    const requestBinding = providerRequestId
+      ? Object.freeze({
+          workflowEffectId,
+          callSequence,
+          source: "semantic-compaction",
+          providerRequestId,
+          requestIdentitySemantics: "trace-only",
+        })
+      : null;
+    try {
+      const result = await original.apply(
+        this,
+        requestBinding ? [...args, requestBinding] : args,
+      );
+      call.providerReceipt = providerRequestId
+        ? _snapshotProviderRequestReceipt(
+            result?.providerReceipt,
+            providerRequestId,
+            call.provider,
+          )
+        : null;
+      return result;
+    } catch (error) {
+      if (workflowEffectId) {
+        throw _workflowCompactionOutcomeUnknown(error);
+      }
+      throw error;
+    }
   };
 
   try {
@@ -11939,7 +12351,7 @@ async function _getAutoCompactor(options) {
           ? options.compactionLlmQuery
           : options.chatFn
             ? null
-            : async (prompt) => {
+            : async (prompt, requestBinding = null) => {
                 const maxOutputTokens = Math.min(
                   4096,
                   Math.max(
@@ -11958,14 +12370,17 @@ async function _getAutoCompactor(options) {
                     onToken: undefined,
                     onStall: undefined,
                     onStreamRetry: undefined,
+                    providerRequestId:
+                      requestBinding?.providerRequestId || undefined,
                     maxOutputTokens,
                   },
                 );
                 return {
                   summary: response?.message?.content || "",
                   usage: response?.usage || null,
-                  provider: options.provider || null,
-                  model: options.model || null,
+                  provider: options.provider || "ollama",
+                  model: options.model || "unknown",
+                  providerReceipt: response?.providerReceipt || null,
                 };
               };
       compressor = new PromptCompressor({
@@ -12205,6 +12620,7 @@ export async function* agentLoop(messages, options) {
     await import("../lib/iteration-budget.js");
   const budget = options.iterationBudget || new IterationBudget();
   const signal = options.signal || null;
+  const workflowEffectId = _normalizeWorkflowEffectId(options.workflowEffectId);
   // Optional OpenTelemetry recorder (TelemetryRecorder). When present, the loop
   // emits model/tool/retry spans + a per-run counter; when absent, zero cost.
   const recorder = options.recorder || null;
@@ -12215,6 +12631,7 @@ export async function* agentLoop(messages, options) {
     options.runId ||
     `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   let automaticCompactionSettlementBlocked = false;
+  let workflowChildEffectSequence = 0;
 
   const fileMutationScope = normalizeExactFileMutationScope(
     options.fileMutationScope,
@@ -12314,6 +12731,7 @@ export async function* agentLoop(messages, options) {
     mcpDispatchAdmission: hermeticExecution
       ? null
       : options.mcpDispatchAdmission || null,
+    workflowEffectId,
     // A loop-local identity prevents one session's lazy instruction commits
     // from suppressing first-access delivery in another session at the same
     // cwd. Hosts may inject a stable identity across resumed turns.
@@ -12507,10 +12925,13 @@ export async function* agentLoop(messages, options) {
   // attempt inside one logical `llmCall`, where this generator cannot durably
   // bracket each transport attempt. Strict call-ledger sessions therefore
   // disable that recovery path and surface the configured provider's failure
-  // as unknown; legacy sessions keep the existing self-healing behavior.
+  // as unknown. A workflow-bound request does the same: a hidden fallback
+  // would be a second physical provider attempt under one durable effect.
+  // Legacy sessions keep the existing self-healing behavior.
   if (
     options.runnableProviderFallback !== false &&
-    options.strictUsageTelemetry !== true
+    options.strictUsageTelemetry !== true &&
+    workflowEffectId == null
   ) {
     const { makeRunnableProviderFallback } =
       await import("../lib/runnable-provider.js");
@@ -12654,6 +13075,7 @@ export async function* agentLoop(messages, options) {
         if (compactor && compactor.shouldAutoCompact(messages)) {
           compactionUsageState = _autoCompactionUsageState(options);
           compactionUsageState.calls = [];
+          compactionUsageState.callSequence = budget.consumed;
           // This is the canonical pre-provider authority snapshot. A local
           // micro-compact may change the working input, but the durable CAS must
           // still compare against the transcript state that existed before any
@@ -12750,6 +13172,16 @@ export async function* agentLoop(messages, options) {
           }
           compactionUsageCall = compactionUsageState.calls.at(-1) || null;
           const compactionUsage = _compactionTokenUsage(stats);
+          if (compactionUsageCall?.providerReceipt) {
+            yield {
+              type: "provider-request-receipt",
+              callId: compactionUsageCall.callId,
+              workflowEffectId,
+              callSequence: compactionUsageCall.callSequence,
+              source: "semantic-compaction",
+              ...compactionUsageCall.providerReceipt,
+            };
+          }
           if (stats.degraded === true) {
             const usageOutcomeUnknown = stats.summaryUsageUnknown === true;
             const projectedStats = usageOutcomeUnknown
@@ -12816,6 +13248,15 @@ export async function* agentLoop(messages, options) {
               backgroundSubAgents,
               backgroundUsageFailureState,
             );
+            if (workflowEffectId) {
+              throw _markWorkflowCompactionFailureReported(
+                _workflowCompactionOutcomeUnknown(
+                  null,
+                  "CC_WORKFLOW_COMPACTION_USAGE_UNKNOWN",
+                  "Workflow-bound semantic compaction usage is unknown",
+                ),
+              );
+            }
             return;
           }
           if (
@@ -12869,6 +13310,15 @@ export async function* agentLoop(messages, options) {
                 backgroundSubAgents,
                 backgroundUsageFailureState,
               );
+              if (workflowEffectId) {
+                throw _markWorkflowCompactionFailureReported(
+                  _workflowCompactionOutcomeUnknown(
+                    error,
+                    "CC_WORKFLOW_COMPACTION_SETTLEMENT_UNKNOWN",
+                    "Workflow-bound semantic compaction settlement is unknown",
+                  ),
+                );
+              }
               return;
             }
             if (!hermeticExecution) {
@@ -12916,6 +13366,12 @@ export async function* agentLoop(messages, options) {
       } catch (_e) {
         if (isAbortError(_e) || signal?.aborted) throw _e;
         if (_e?.runtimeLedgerPersistence === true) throw _e;
+        if (
+          _e?.workflowEffectOutcomeUnknown === true &&
+          _e?.compactionFailureReported === true
+        ) {
+          throw _e;
+        }
         if (compactionObserverFailure === _e) throw _e;
         const observerFailure = compactionUsageState?.calls?.find(
           (call) => call.observerFailed && call.observerError === _e,
@@ -12942,6 +13398,13 @@ export async function* agentLoop(messages, options) {
             backgroundSubAgents,
             backgroundUsageFailureState,
           );
+          if (workflowEffectId) {
+            throw _markWorkflowCompactionFailureReported(
+              _e?.workflowEffectOutcomeUnknown === true
+                ? _e
+                : _workflowCompactionOutcomeUnknown(_e),
+            );
+          }
           return;
         }
         yield {
@@ -13048,12 +13511,28 @@ export async function* agentLoop(messages, options) {
     throwIfAborted(signal);
     _throwBackgroundUsageFailureState(backgroundUsageFailureState);
     _throwSettledBackgroundUsageFailure(backgroundSubAgents);
+    const providerRequestId = _workflowProviderRequestId(
+      workflowEffectId,
+      "model",
+      budget.consumed,
+    );
+    const providerCallOptions = providerRequestId
+      ? { ...effectiveToolOptions, providerRequestId }
+      : effectiveToolOptions;
     const modelUsageCall = {
       type: "model-usage-started",
       callId: _newModelUsageCallId("model"),
       provider: options.provider || "ollama",
       model: options.model || "unknown",
       source: "model",
+      ...(providerRequestId
+        ? {
+            workflowEffectId,
+            callSequence: budget.consumed,
+            providerRequestId,
+            requestIdentitySemantics: "trace-only",
+          }
+        : {}),
     };
     // The consumer receives this boundary before `.next()` resumes into the
     // provider call, so a durable append failure can prevent spend.
@@ -13079,6 +13558,7 @@ export async function* agentLoop(messages, options) {
     }
 
     let result;
+    let providerReceipt = null;
     try {
       result = await _withSpan(
         recorder,
@@ -13089,7 +13569,7 @@ export async function* agentLoop(messages, options) {
           "agent.iteration": budget.consumed,
           ...(modelIdAttrs || {}),
         },
-        () => llmCall(callMessages, effectiveToolOptions),
+        () => llmCall(callMessages, providerCallOptions),
         (span, r) => {
           const t = _usageTokens(r?.usage);
           if (t) {
@@ -13130,6 +13610,13 @@ export async function* agentLoop(messages, options) {
         },
         "model_error",
       );
+      providerReceipt = providerRequestId
+        ? _snapshotProviderRequestReceipt(
+            result?.providerReceipt,
+            providerRequestId,
+            modelUsageCall.provider,
+          )
+        : null;
     } catch (error) {
       // Never retain provider error text in the usage ledger. Pause on a fixed
       // unknown settlement, then rethrow only after the consumer resumes.
@@ -13150,6 +13637,20 @@ export async function* agentLoop(messages, options) {
     if (recorder) recorder.counter("agent.model.calls", 1);
     const msg = result?.message;
 
+    if (providerReceipt) {
+      // Yield the provider-returned identifiers before billable usage. A host
+      // that stops after a cost boundary still retains the exact request/effect
+      // binding. This is trace evidence only, never an exactly-once assertion.
+      yield {
+        type: "provider-request-receipt",
+        callId: modelUsageCall.callId,
+        workflowEffectId,
+        callSequence: budget.consumed,
+        source: modelUsageCall.source,
+        ...providerReceipt,
+      };
+    }
+
     // Close the already-persisted call boundary before honoring an abort that
     // raced with a successful provider response. Once the transport returned,
     // dropping this settlement would strand a durable `started` row forever.
@@ -13375,7 +13876,13 @@ export async function* agentLoop(messages, options) {
         } catch {
           toolArgs = {};
         }
-        return { call, toolArgs };
+        const workflowBinding = _workflowToolEffectBinding(
+          workflowEffectId,
+          workflowEffectId ? (workflowChildEffectSequence += 1) : 0,
+          call.id,
+          call.function.name,
+        );
+        return { call, toolArgs, workflowBinding };
       });
       // Yield every start boundary before dispatch. Async-generator consumers
       // persist each boundary before asking for the next item, so by the time
@@ -13384,20 +13891,21 @@ export async function* agentLoop(messages, options) {
       try {
         throwIfAborted(signal);
         _throwBackgroundUsageFailureState(backgroundUsageFailureState);
-        for (const { call, toolArgs } of prepared) {
+        for (const { call, toolArgs, workflowBinding } of prepared) {
           yield {
             type: "tool-executing",
             tool: call.function.name,
             args: toolArgs,
             tool_use_id: call.id,
             turn_id: `${runId}:t${budget.consumed}`,
+            ...(workflowBinding || {}),
           };
-          startedPrepared.push({ call, toolArgs });
+          startedPrepared.push({ call, toolArgs, workflowBinding });
           throwIfAborted(signal);
         }
         _throwBackgroundUsageFailureState(backgroundUsageFailureState);
       } catch (admissionFailure) {
-        for (const { call } of startedPrepared) {
+        for (const { call, workflowBinding } of startedPrepared) {
           yield {
             type: "tool-result",
             tool: call.function.name,
@@ -13405,6 +13913,7 @@ export async function* agentLoop(messages, options) {
             error: "tool execution cancelled before dispatch",
             tool_use_id: call.id,
             turn_id: `${runId}:t${budget.consumed}`,
+            ...(workflowBinding || {}),
           };
         }
         throw admissionFailure;
@@ -13412,18 +13921,30 @@ export async function* agentLoop(messages, options) {
       // Only after every start has been consumed do we kick every read off.
       // Settle each promise into {result,error} so an abort before its ordered
       // result is consumed can never surface an unhandled rejection.
-      const inflight = prepared.map(({ call, toolArgs }) => {
+      const inflight = prepared.map(({ call, toolArgs, workflowBinding }) => {
         const promise = executeTool(call.function.name, toolArgs, {
           ...toolContext,
           toolCallId: call.id,
           turnId: `${runId}:t${budget.consumed}`,
+          ...(workflowBinding || {}),
         }).then(
           (result) => ({ result, error: null }),
-          (err) => ({ result: { error: err.message }, error: err.message }),
+          (err) => ({
+            result: {
+              error: err.message,
+              ...(workflowBinding
+                ? {
+                    code: "CC_WORKFLOW_NESTED_TOOL_EXECUTION_THROWN",
+                    outcomeUnknown: true,
+                  }
+                : {}),
+            },
+            error: err.message,
+          }),
         );
-        return { call, toolArgs, promise };
+        return { call, toolArgs, workflowBinding, promise };
       });
-      for (const { call, toolArgs, promise } of inflight) {
+      for (const { call, toolArgs, workflowBinding, promise } of inflight) {
         throwIfAborted(signal);
         _throwBackgroundUsageFailureState(backgroundUsageFailureState);
         const { result: toolResult, error: toolError } = await promise;
@@ -13463,9 +13984,16 @@ export async function* agentLoop(messages, options) {
           error: toolError,
           tool_use_id: call.id,
           turn_id: `${runId}:t${budget.consumed}`,
+          ...(workflowBinding || {}),
           permission_decision_id: decision?.id || null,
           permission_decision: decision,
         };
+        const nestedOutcomeUnknown = _workflowNestedToolOutcomeUnknown(
+          workflowBinding,
+          call.function.name,
+          toolResult,
+        );
+        if (nestedOutcomeUnknown) throw nestedOutcomeUnknown;
         messages.push({
           role: "tool",
           content: toolContent,
@@ -13610,6 +14138,7 @@ export async function* agentLoop(messages, options) {
 
       let managedCheckpointHandle = null;
       let managedCheckpointPreparationError = null;
+      let workflowBinding = null;
       try {
         managedCheckpointHandle = beginManagedToolCheckpoint({
           enabled: toolContext.managedCheckpoint === true,
@@ -13663,12 +14192,19 @@ export async function* agentLoop(messages, options) {
         // event. Consumers use that event to bind hooks, telemetry and turns to
         // an actual invocation.
         if (!managedCheckpointPreparationError) {
+          workflowBinding = _workflowToolEffectBinding(
+            workflowEffectId,
+            workflowEffectId ? (workflowChildEffectSequence += 1) : 0,
+            call.id,
+            toolName,
+          );
           yield {
             type: "tool-executing",
             tool: toolName,
             args: toolArgs,
             tool_use_id: call.id,
             turn_id: `${runId}:t${budget.consumed}`,
+            ...(workflowBinding || {}),
           };
           // The event yield is a host persistence boundary. A detached child's
           // fatal usage write can settle while the consumer handles it; fence
@@ -13686,6 +14222,7 @@ export async function* agentLoop(messages, options) {
               error: "authoritative background usage persistence failure",
               tool_use_id: call.id,
               turn_id: `${runId}:t${budget.consumed}`,
+              ...(workflowBinding || {}),
             };
             throw backgroundFailure;
           }
@@ -13735,6 +14272,7 @@ export async function* agentLoop(messages, options) {
                   ...toolContext,
                   toolCallId: call.id,
                   turnId: `${runId}:t${budget.consumed}`,
+                  ...(workflowBinding || {}),
                 }),
               (span, r) => {
                 span.setAttribute(
@@ -13774,7 +14312,15 @@ export async function* agentLoop(messages, options) {
             );
           } catch (err) {
             if (err?.runtimeLedgerPersistence === true) throw err;
-            toolResult = { error: err.message };
+            toolResult = {
+              error: err.message,
+              ...(workflowBinding
+                ? {
+                    code: "CC_WORKFLOW_NESTED_TOOL_EXECUTION_THROWN",
+                    outcomeUnknown: true,
+                  }
+                : {}),
+            };
             toolError = err.message;
           }
         }
@@ -13878,10 +14424,18 @@ export async function* agentLoop(messages, options) {
           error: toolError,
           tool_use_id: call.id,
           turn_id: `${runId}:t${budget.consumed}`,
+          ...(workflowBinding || {}),
           permission_decision_id: decision?.id || null,
           permission_decision: decision,
         };
 
+        const nestedOutcomeUnknown = _workflowNestedToolOutcomeUnknown(
+          workflowBinding,
+          toolName,
+          toolResult,
+        );
+        if (nestedOutcomeUnknown) throw nestedOutcomeUnknown;
+
         messages.push({
           role: "tool",
           content: toolContent,