@sema-agent/core 5.61.0 → 5.63.0

package/dist/core/usage-window-store.js

@@ -24,6 +24,9 @@ export function resolveUsageWindows(windows) {
         if (typeof w.maxTokens !== "number" || !Number.isFinite(w.maxTokens) || w.maxTokens < 0) {
             throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].maxTokens must be a finite, non-negative number (got ${String(w.maxTokens)})`);
         }
+        if (w.maxCostUsd !== undefined && (typeof w.maxCostUsd !== "number" || !Number.isFinite(w.maxCostUsd) || w.maxCostUsd < 0)) {
+            throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].maxCostUsd must be a finite, non-negative number of USD when present (got ${String(w.maxCostUsd)})`);
+        }
         if (w.anchor !== "first-use" && w.anchor !== "rolling") {
             throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].anchor must be "first-use" or "rolling" (got ${String(w.anchor)})`);
         }
@@ -40,11 +43,34 @@ function rollingHorizonMs(windows) {
     }
     return widest;
 }
-export function chargeUsageRecord(record, tokens, at, windows) {
+export function windowsGovernCost(windows) {
+    return windows.some((w) => w.maxCostUsd !== undefined);
+}
+function maxCostMicroUsdOf(w) {
+    return w.maxCostUsd === undefined ? undefined : Math.ceil(Number((w.maxCostUsd * 1e6).toPrecision(12)));
+}
+export function chargeUsageRecord(record, tokens, at, windows, costMicroUsd) {
     const horizon = rollingHorizonMs(windows);
-    const keptSlots = horizon === undefined ? [] : record.slots.filter((s) => s.at > at - horizon).map((s) => ({ at: s.at, tokens: s.tokens }));
-    if (horizon !== undefined && tokens > 0)
-        keptSlots.push({ at, tokens });
+    const governsCost = windowsGovernCost(windows);
+    if (governsCost && costMicroUsd === undefined) {
+        throw usageConfigError("usage_window.store_cost_unanswered", "a usage-window CHARGE for a deployment that governs maxCostUsd arrived with no cost figure at all. Core supplies one (a number, or an explicit null for spend nothing could price) on every such charge, so an absent one means a store in the chain does not carry the cost argument — folding it to 0 would leave the money ceiling open forever with nothing able to notice. Forward `costMicroUsd` from `UsageWindowStore.charge` into `chargeUsageRecord`.");
+    }
+    const cost = governsCost && costMicroUsd !== null ? costMicroUsd : undefined;
+    const unknown = governsCost && costMicroUsd === null;
+    const moves = tokens > 0 || (cost !== undefined && cost > 0) || unknown;
+    const keptSlots = horizon === undefined
+        ? []
+        : record.slots
+            .filter((s) => s.at > at - horizon)
+            .map((s) => ({
+            at: s.at,
+            tokens: s.tokens,
+            ...(s.costMicroUsd === undefined ? {} : { costMicroUsd: s.costMicroUsd }),
+            ...(s.costUnknown === true ? { costUnknown: true } : {}),
+        }));
+    if (horizon !== undefined && moves) {
+        keptSlots.push({ at, tokens, ...(cost === undefined ? {} : { costMicroUsd: cost }), ...(unknown ? { costUnknown: true } : {}) });
+    }
     const buckets = [];
     for (const w of windows) {
         if (w.anchor !== "first-use")
@@ -54,11 +80,21 @@ export function chargeUsageRecord(record, tokens, at, windows) {
         const prior = record.buckets.find((b) => b.windowMs === w.windowMs);
         const lapsed = prior === undefined || at >= prior.openedAt + w.windowMs;
         if (lapsed) {
-            if (tokens > 0)
-                buckets.push({ windowMs: w.windowMs, openedAt: at, tokens });
+            if (moves) {
+                buckets.push({ windowMs: w.windowMs, openedAt: at, tokens, ...(cost === undefined ? {} : { costMicroUsd: cost }), ...(unknown ? { costUnknown: true } : {}) });
+            }
             continue;
         }
-        buckets.push({ windowMs: w.windowMs, openedAt: prior.openedAt, tokens: prior.tokens + tokens });
+        const priorCost = prior.costMicroUsd;
+        const nextCost = cost === undefined ? priorCost : (priorCost ?? 0) + cost;
+        const nextUnknown = unknown || prior.costUnknown === true;
+        buckets.push({
+            windowMs: w.windowMs,
+            openedAt: prior.openedAt,
+            tokens: prior.tokens + tokens,
+            ...(nextCost === undefined ? {} : { costMicroUsd: nextCost }),
+            ...(nextUnknown ? { costUnknown: true } : {}),
+        });
     }
     return { slots: keptSlots, buckets };
 }
@@ -66,6 +102,8 @@ export function readUsageRecord(record, windows, now) {
     const readings = [];
     for (const w of windows) {
         let tokens = 0;
+        let costMicroUsd = 0;
+        let costUnknown = false;
         let freesAt;
         if (w.anchor === "rolling") {
             const floor = now - w.windowMs;
@@ -74,6 +112,9 @@ export function readUsageRecord(record, windows, now) {
                 if (s.at <= floor)
                     continue;
                 tokens += s.tokens;
+                costMicroUsd += s.costMicroUsd ?? 0;
+                if (s.costUnknown === true)
+                    costUnknown = true;
                 if (oldest === undefined || s.at < oldest)
                     oldest = s.at;
             }
@@ -84,18 +125,44 @@ export function readUsageRecord(record, windows, now) {
             const row = record.buckets.find((b) => b.windowMs === w.windowMs);
             if (row !== undefined && now < row.openedAt + w.windowMs) {
                 tokens = row.tokens;
+                costMicroUsd = row.costMicroUsd ?? 0;
+                if (row.costUnknown === true)
+                    costUnknown = true;
                 freesAt = row.openedAt + w.windowMs;
             }
         }
-        const exhausted = tokens >= w.maxTokens;
+        const maxCostMicroUsd = maxCostMicroUsdOf(w);
+        const exhausted = tokens >= w.maxTokens || (maxCostMicroUsd !== undefined && costMicroUsd >= maxCostMicroUsd);
         const retryAfterMs = exhausted ? Math.max(1, freesAt === undefined ? w.windowMs : freesAt - now) : 0;
-        readings.push({ window: w, tokens, exhausted, retryAfterMs });
+        readings.push({
+            window: w,
+            tokens,
+            ...(maxCostMicroUsd !== undefined ? { costMicroUsd } : {}),
+            ...(maxCostMicroUsd !== undefined && costUnknown ? { costUnknown: true } : {}),
+            exhausted,
+            retryAfterMs,
+        });
     }
     return readings;
 }
-export function usageRetryAfterMs(readings) {
+export function usageRetryAfterMs(readings, windows) {
+    if (windows !== undefined) {
+        if (readings.length !== windows.length) {
+            throw usageConfigError("usage_window.store_cost_unanswered", `the usage-window ledger answered ${String(readings.length)} reading(s) for ${String(windows.length)} declared window(s) — the read contract is one reading per window, in the order given. A window with no reading was never evaluated: refused rather than treated as open.`);
+        }
+        for (let i = 0; i < windows.length; i++) {
+            const w = windows[i];
+            const echoed = readings[i].window;
+            if (echoed === undefined || echoed.windowMs !== w.windowMs || echoed.anchor !== w.anchor || echoed.maxTokens !== w.maxTokens || echoed.maxCostUsd !== w.maxCostUsd) {
+                throw usageConfigError("usage_window.store_cost_unanswered", `the usage-window ledger's reading #${String(i)} does not echo declared window #${String(i)} verbatim (declared: windowMs ${String(w.windowMs)}, ${String(w.anchor)}, maxTokens ${String(w.maxTokens)}, maxCostUsd ${String(w.maxCostUsd)}) — the read contract requires the window back verbatim, in order, so its ceilings are provably the ones evaluated. Refused rather than re-attributed.`);
+            }
+        }
+    }
     let worst;
     for (const r of readings) {
+        if (r.window?.maxCostUsd !== undefined && r.costMicroUsd === undefined) {
+            throw usageConfigError("usage_window.store_cost_unanswered", `the usage-window ledger answered a window that declares maxCostUsd ${String(r.window.maxCostUsd)} (windowMs ${String(r.window.windowMs)}, ${String(r.window.anchor)}) with NO costMicroUsd — the money ceiling was never evaluated. Refused rather than treated as open: the store must persist the cost charged to it and report what the window holds.`);
+        }
         if (!r.exhausted)
             continue;
         if (worst === undefined || r.retryAfterMs > worst)
@@ -105,9 +172,9 @@ export function usageRetryAfterMs(readings) {
 }
 export class InMemoryUsageWindowStore {
     records = new Map();
-    async charge(key, tokens, at, windows) {
+    async charge(key, tokens, at, windows, costMicroUsd) {
         const prior = this.records.get(key) ?? EMPTY_USAGE_WINDOW_RECORD;
-        this.records.set(key, chargeUsageRecord(prior, tokens, at, windows));
+        this.records.set(key, chargeUsageRecord(prior, tokens, at, windows, costMicroUsd));
     }
     async read(key, windows, now) {
         return readUsageRecord(this.records.get(key) ?? EMPTY_USAGE_WINDOW_RECORD, windows, now);

package/dist/engine/harness/agent-harness.js

@@ -547,7 +547,7 @@ export class AgentHarness {
         userInputParkRecords.delete(message);
         engineNotePayloads.delete(message);
     }
-    createLoopConfig(getTurnState, setTurnState) {
+    createLoopConfig(getTurnState, setTurnState, runPromptOverride) {
         const turnState = getTurnState();
         const self = this;
         return {
@@ -564,9 +564,24 @@ export class AgentHarness {
                 : {}),
             convertToLlm: (messages) => stripEngineMetadata(convertToLlm(messages)),
             shouldStopAfterTurn: () => this._stopAfterTurn,
-            transformContext: async (messages) => {
-                const result = await this.emitHook({ type: "context", messages: [...messages] });
-                return result?.messages ?? messages;
+            transformContext: async (messages, signal) => {
+                const result = await this.emitHook({ type: "context", messages: [...messages], ...(signal !== undefined ? { signal } : {}) });
+                if (result?.adoptSessionRebuild !== true) {
+                    return result?.messages ?? messages;
+                }
+                await this.flushPendingSessionWrites();
+                const nextTurnState = await this.createTurnState();
+                setTurnState(nextTurnState);
+                const rebuiltContext = this.createContext(nextTurnState, runPromptOverride);
+                const recheck = await this.emitHook({ type: "context", messages: [...rebuiltContext.messages], ...(signal !== undefined ? { signal } : {}), recheck: true });
+                return {
+                    messages: recheck?.messages ?? rebuiltContext.messages,
+                    adoptedContext: {
+                        messages: rebuiltContext.messages,
+                        systemPrompt: rebuiltContext.systemPrompt,
+                        ...(rebuiltContext.systemBlocks !== undefined ? { systemBlocks: rebuiltContext.systemBlocks } : {}),
+                    },
+                };
             },
             beforeToolCall: async ({ toolCall, args }) => {
                 const result = await this.emitHook({
@@ -780,7 +795,7 @@ export class AgentHarness {
         this.runAbortController = abortController;
         const runResultPromise = (async () => {
             try {
-                return await runAgentLoop(messages, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState), (event) => this.handleAgentEvent(event, abortController.signal), abortController.signal, this.createStreamFn(getTurnState), undefined, this.loopTrace);
+                return await runAgentLoop(messages, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState, beforeResult?.systemPrompt), (event) => this.handleAgentEvent(event, abortController.signal), abortController.signal, this.createStreamFn(getTurnState), undefined, this.loopTrace);
             }
             catch (error) {
                 try {

package/dist/engine/harness/types.d.ts

@@ -919,6 +919,25 @@ export interface BeforeAgentStartEvent<TSkill extends Skill = Skill, TPromptTemp
 export interface ContextEvent {
     type: "context";
     messages: AgentMessage[];
+    /**
+     * The TURN-scoped abort signal of the request build being transformed (present when the loop
+     * handed one — it always does in production; absent only for bare-harness callers). A handler
+     * that runs an EXPENSIVE reduction (the slice-3 arm-B in-turn compaction is the standing case)
+     * must honor it: a turn interrupt (design/373) fires this signal, and a reduction that only
+     * watches the RUN-level signal would make the interrupt wait out a long summary call and commit
+     * a session mutation the interrupted turn no longer needs (adversarial review r3).
+     */
+    signal?: AbortSignal;
+    /**
+     * design/374 slice 3 — set on the ONE bounded re-dispatch of the adopt seam
+     * ({@link ContextResult.adoptSessionRebuild}): `messages` are the just-adopted session rebuild,
+     * re-presented so the handler's request pipeline applies to what the provider will actually
+     * receive (the "recheck" step of build→reduce→adopt→recheck). A handler must not request a
+     * second adoption on this dispatch — the harness does not honor it (see the result member's
+     * doc) — so a reduction that is still over budget takes the handler's own next arm (the trim
+     * last resort) instead of looping. Absent on every ordinary dispatch.
+     */
+    recheck?: boolean;
 }
 export interface TurnBoundaryEvent {
     /** Fires between model-request boundaries, after session flush, before the context rebuild. */
@@ -997,6 +1016,25 @@ export interface BeforeAgentStartResult {
 /** Hook result for replacing the full context message list before provider conversion. */
 export interface ContextResult {
     messages: AgentMessage[];
+    /**
+     * design/374 slice 3 (arm B, the adopt seam) — the handler PERSISTED a session-level reduction
+     * during this dispatch (e.g. an in-turn forced compaction appended to the session) and asks the
+     * harness to adopt it MID-BUILD, the same three-step form as the two existing adoption flows
+     * (turn_boundary / prompt-too-long recovery): flush pending session writes, rebuild the turn
+     * context from the session (`createTurnState`), adopt it (`setTurnState` + the loop-context
+     * adoption via {@link import("../loop/types.js").TransformedContext}), then re-dispatch the
+     * context hook ONCE on the rebuilt view (`ContextEvent.recheck`) so the request pipeline applies
+     * to it. Result: the provider request, every subsequent hook dispatch, and the active turn state
+     * all see the SAME reduced transcript — the three-party co-view the seam exists for. `messages`
+     * on this arm are the handler's best unadopted view and are superseded by the rebuild.
+     *
+     * Honored AT MOST ONCE per request build: on the recheck dispatch this member is ignored (its
+     * `messages` are used verbatim) — the bound that keeps a reduction that cannot get under budget
+     * from re-entering forever. Typed on the hook RESULT deliberately (not a closure side channel):
+     * the adoption is part of the hook's answer, and the one prior closure-ref transport in this
+     * area (`requestLossyRef`) is a recorded bypass shape, not a precedent to grow.
+     */
+    adoptSessionRebuild?: boolean;
 }
 /** Hook result for patching provider request options before payload construction. */
 export interface BeforeProviderRequestResult {

package/dist/engine/loop/agent-loop.js

@@ -524,7 +524,26 @@ async function settleInterruptedTurn(state, message, executor, committedResults,
 async function streamAssistantResponse(context, config, signal, emit, streamFn, runtime, executor, staticReasoningCutDowngrade) {
     let messages = context.messages;
     if (config.transformContext) {
-        messages = await config.transformContext(messages, signal);
+        const transformed = await config.transformContext(messages, signal);
+        if (Array.isArray(transformed)) {
+            messages = transformed;
+        }
+        else {
+            const adopted = transformed.adoptedContext;
+            if (adopted !== undefined) {
+                context.messages = adopted.messages;
+                if (adopted.systemPrompt !== undefined) {
+                    context.systemPrompt = adopted.systemPrompt;
+                    if (adopted.systemBlocks !== undefined) {
+                        context.systemBlocks = adopted.systemBlocks;
+                    }
+                    else {
+                        delete context.systemBlocks;
+                    }
+                }
+            }
+            messages = transformed.messages;
+        }
     }
     const llmMessages = await config.convertToLlm(messages);
     const llmContext = {

package/dist/engine/loop/types.d.ts

@@ -223,6 +223,40 @@ export interface LoopThinkingOnlyRecovery {
  *  side is `recover(messages, attempt)` and also carries `withholdErrorEvents`, so the two can never share
  *  one type. (`agent-harness.ts` is outside this file's edit scope — its side of this mutual-reference
  *  note is pending.) */
+/**
+ * design/374 slice 3 — the transform's ADOPTING return shape (see
+ * {@link AgentLoopConfig.transformContext}). Two arrays with different standings, on purpose:
+ * `messages` is the WIRE view for this one request (a request-only projection — cleared markers,
+ * caps, trim — which must NEVER become loop state, the D-4 non-destructive posture), while
+ * `adoptedContext` is a session-rebuilt TRANSCRIPT the loop adopts as its live context
+ * (`state.context.messages`) so the rest of the turn — later requests, the interrupt reconcile,
+ * the recovery pops — continues from the reduced transcript. This is the transform-seam sibling of
+ * the ④b recover adoption (`state.context.messages = replaced`); a transform that reduced the
+ * SESSION but only re-projected the wire would leave the loop replaying the pre-reduction
+ * transcript into every later request of the turn.
+ */
+export interface TransformedContext {
+    /** The wire view for THIS request (what `convertToLlm` receives). */
+    messages: AgentMessage[];
+    /** Present ⇒ adopt this rebuilt context as the loop's live state before streaming. */
+    adoptedContext?: {
+        /** The rebuilt transcript the loop adopts as `state.context.messages`. */
+        messages: AgentMessage[];
+        /** When present, the rebuilt SYSTEM PROMPT is adopted too — and it applies to THIS very
+         *  request (the loop reads `context.systemPrompt` after the transform): an in-turn compaction
+         *  can commit a prompt-epoch change (center-prompt adoption/rollback rides the compaction
+         *  pass), and a request built from the rebuilt transcript under the PRE-epoch prompt would
+         *  disagree with the epoch the session just recorded (adversarial review r1). `systemBlocks`
+         *  must only ever accompany the prompt they byte-correspond to; when the prompt is adopted
+         *  WITHOUT blocks, stale blocks are dropped (the string face is the truth source — same
+         *  degrade-to-string posture as the harness's atomic-face guard). */
+        systemPrompt?: string;
+        systemBlocks?: Array<{
+            text: string;
+            cacheControlBoundary: boolean;
+        }>;
+    };
+}
 export interface LoopRecoveryOptions {
     promptTooLong?: LoopPromptTooLongRecovery;
     truncatedOutput?: LoopTruncatedOutputRecovery;
@@ -328,8 +362,14 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      *   return messages;
      * }
      * ```
+     *
+     * Return shape (design/374 slice 3): a bare array is the historic contract — a REQUEST-ONLY
+     * projection, never adopted into the loop's live context. Returning a
+     * {@link TransformedContext} additionally lets the transform ADOPT a session-rebuilt transcript
+     * mid-turn (the in-turn forced-compaction seam) — the loop half of the same two-half adoption
+     * form the prompt-too-long recovery already has (`state.context.messages = replaced`).
      */
-    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[] | TransformedContext>;
     /**
      * Resolves an API key dynamically for each LLM call.
      *

package/dist/index.d.ts

@@ -168,7 +168,7 @@ export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootA
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, type AdoptionStatus, type AdoptLocalDataRootOptions, type AdoptLocalDataRootResult, type AdoptionCarriageLeg, type AdoptionCarriageLegContext, type AdoptionConfigWitnessReceipt, } from "./stores/file/adoption/adopt.js";
 export { formatHookFeedback, runToolGate, createHookEnvCapabilities, createPreToolUseConstraintPolicy, type PersistedRuleHit, type PersistedRuleHitRule, type PersistedRuleUnreadable, type PersistedRuleCoverage, type PersistedRuleAnswer, normalizePersistedRuleHit, type Hooks, type HookToolContext, type HookInvocationIdentity, type UserPromptSubmitContext, type PostToolBatchContext, type HookEnvCapabilities, type HookToolOutput, type PreToolUseResult, type PostToolUseResult, type UserPromptSubmitResult, type HookToolFailure, type PostToolUseFailureResult, type PostToolBatchCall, type PostToolBatchResult, type PreCompactContext, type PreCompactResult, type PostCompactContext, type StopFailureContext, type PermissionDeniedPayload, type PermissionDeniedSource, } from "./core/hooks.js";
 export { InMemoryMemoryStore, composeMemoryBlock, composeLayeredMemoryBlock, normalizeMemorySpec, type NormalizedMemorySpec, type MemorySpecInput, supportsConsolidation, supportsPeriodicConsolidation, firstSentence, expandLexicalTerms, lexicalSearchMatch, type Embedder, classifyPromotable, enforcePromotableWriteGate, guardedMemoryStore, MemoryGateError, detectSecret, enforceSecretWriteGate, enforceStructuredNoteSecretGate, type UtilityGate, type MemoryStore, type MemoryVectorMode, type ScoredMemory, type MemoryNoteHeader, type MemoryNoteRecord, type MemoryNoteType, type StructuredNoteInput, } from "./core/memory.js";
-export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_ORIGIN_CAUSES, committedOriginOf, originEquals, ambiguousOriginRepresentation, type OriginClearanceRow, type OriginClearanceEvent, committedDistilledOf, distilledEquals, type MemoryEntryDistilled, type MemoryEntryDistilledInput, CONSOLIDATION_DEFAULTS, ConsolidationRefusedError, MEMORY_SEARCH_SUPERSEDED_TAG, consolidationTypeEligible, deriveSupersededSet, memorySupersededNote, readIntentCredentials, supersessionFuseCeiling, memoryConsolidationRecommendedNotice, memoryConsolidationCommittedNotice, memoryConsolidationConflictNotice, memoryConsolidationIncompleteNotice, memoryConsolidationRefusedNotice, type ConsolidationGateRead, type ConsolidationGateRow, type ConsolidationIntent, type ConsolidationIntentCredentialRow, type ConsolidationLeaseSeat, type ConsolidationProductProposal, type ConsolidationProposal, type MemoryConsolidationOptions, type ConsolidationCommitReceipt, type ConsolidationReconcileReport, type ConsolidationResolveReceipt, type ConsolidationPlanSummary, type ConsolidationPlanFoldEvidence, DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT, LLM_DISTILLER_CONTRACT, LLM_DISTILLER_CONTRACT_DL2, LLM_DISTILLER_CONTRACT_DL3, LLM_DISTILLER_CONTRACTS, MEMORY_DISTILLER_CONTRACT_V1, contractGroupingDiff, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintExposurePartitionedPlan, mintLlmConsolidationPlan, openAiCompatChatSeat, parseJsonAnswer, planParseRepairs, sanitizeLlmGroups, scheduleUnderFuse, type ConsolidationDistillFn, type ConsolidationDriveCycleRow, type ConsolidationDriveEngine, type ConsolidationDriveResult, type ConsolidationFoldState, type DistillerCandidate, type DistillerChatAnswer, type DistillerChatFn, type DistillerChatRequest, type FuseSchedule, type LlmConsolidationPlan, type LlmConsolidationPlanArm, type LlmConsolidationPlanProduct, type LlmDistillerContract, type MintLlmConsolidationPlanResult, type PlanParseRepairs, type SanitizedLlmGroups, CONSOLIDATION_DRIVER_PLANS_DIR, CONSOLIDATION_DRIVER_RUNS_FILE, CONSOLIDATION_RUN_STOP_REASONS, archiveDistillerPlan, readConsolidationDriverRun, runMemoryConsolidationDriver, type ConsolidationDriverEngine, type ConsolidationDriverRunRow, type ConsolidationRunReceipt, type ConsolidationRunStopReason, type RunMemoryConsolidationOptions, isInstructionEntry, type MemoryEntryOrigin, type MemoryOriginCause, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, readV2HeaderHints, type V2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type CleanMemorySearchHit, type ExposedMemorySearchHit, MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, memoryExposureIndexRow, type MemoryGetDetails, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, type MemoryAnnouncement, type ScanFinding, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, computeMemoryBundleHash, type MemoryExportBundle, type MemoryImportReport, type MemoryExportSnapshot, type MemoryBundleImportPlan, type BundleChallengeRow, type BundleLineageRow, type BundlePollutedSession, type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type MemoryEntryHeader, type MemoryScopeEnumeration, type ScoredMemoryEntry, type NotePatch, type PatchReport, type MaterializedFile, type MemorySessionHandle, type HarvestReport, type HarvestRejection, type HarvestRejectionCode, type ParsedEntryFile, type ScannedEntryFile, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, type ParsedScopeKey, migrateScope, type MigrateScopeReport, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, type RemoteMemoryFile, type RemoteMemoryBaseline, type RemoteMaterialization, type RemoteHarvestResult, type InboundEntryFinding, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, type MemorySyncCursor, type MemorySyncConflict, type MemorySyncPlan, type RecallSource, syncMemoryScope, type MemorySyncTransport, type MemorySyncRequestBody, type MemorySyncResponseBody, type MemorySyncClientConflict, type SyncMemoryScopeOptions, type MemorySyncClientResult, } from "./core/memory-engine/index.js";
+export { MemoryEngine, FileMemoryEngineBackend, memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, buildMemoryInstruction, truncateIndex, scanEntryFiles, deriveRepoKey, deriveRepoMemoryDir, deriveControlPlaneDir, deriveRepoControlPlaneDir, resolveMemoryEngineRoot, scopeDirName, ControlPlaneCorruptError, parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, MEMORY_ORIGIN_CAUSES, committedOriginOf, originEquals, ambiguousOriginRepresentation, type OriginClearanceRow, type OriginClearanceEvent, type OriginClearanceShadow, committedDistilledOf, distilledEquals, type MemoryEntryDistilled, type MemoryEntryDistilledInput, CONSOLIDATION_DEFAULTS, ConsolidationRefusedError, MEMORY_SEARCH_SUPERSEDED_TAG, consolidationTypeEligible, deriveSupersededSet, memorySupersededNote, readIntentCredentials, supersessionFuseCeiling, memoryConsolidationRecommendedNotice, memoryConsolidationCommittedNotice, memoryConsolidationConflictNotice, memoryConsolidationIncompleteNotice, memoryConsolidationRefusedNotice, type ConsolidationGateRead, type ConsolidationGateRow, type ConsolidationIntent, type ConsolidationIntentCredentialRow, type ConsolidationLeaseSeat, type ConsolidationProductProposal, type ConsolidationProposal, type MemoryConsolidationOptions, type ConsolidationCommitReceipt, type ConsolidationReconcileReport, type ConsolidationResolveReceipt, type ConsolidationPlanSummary, type ConsolidationPlanFoldEvidence, DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT, LLM_DISTILLER_CONTRACT, LLM_DISTILLER_CONTRACT_DL2, LLM_DISTILLER_CONTRACT_DL3, LLM_DISTILLER_CONTRACTS, MEMORY_DISTILLER_CONTRACT_V1, contractGroupingDiff, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintExposurePartitionedPlan, mintLlmConsolidationPlan, openAiCompatChatSeat, parseJsonAnswer, planParseRepairs, sanitizeLlmGroups, scheduleUnderFuse, type ConsolidationDistillFn, type ConsolidationDriveCycleRow, type ConsolidationDriveEngine, type ConsolidationDriveResult, type ConsolidationFoldState, type DistillerCandidate, type DistillerChatAnswer, type DistillerChatFn, type DistillerChatRequest, type FuseSchedule, type LlmConsolidationPlan, type LlmConsolidationPlanArm, type LlmConsolidationPlanProduct, type LlmDistillerContract, type MintLlmConsolidationPlanResult, type PlanParseRepairs, type SanitizedLlmGroups, CONSOLIDATION_DRIVER_PLANS_DIR, CONSOLIDATION_DRIVER_RUNS_FILE, CONSOLIDATION_RUN_STOP_REASONS, archiveDistillerPlan, readConsolidationDriverRun, runMemoryConsolidationDriver, type ConsolidationDriverEngine, type ConsolidationDriverRunRow, type ConsolidationRunReceipt, type ConsolidationRunStopReason, type RunMemoryConsolidationOptions, isInstructionEntry, type MemoryEntryOrigin, type MemoryOriginCause, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, readV2HeaderHints, type V2HeaderHints, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, MEMORY_INDEX_FILENAME, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type CleanMemorySearchHit, type ExposedMemorySearchHit, MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, memoryExposureIndexRow, type MemoryGetDetails, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_MAX_ENTRY_DEPTH, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE, renderAnnouncements, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, type MemoryAnnouncement, type ScanFinding, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, computeMemoryBundleHash, type MemoryExportBundle, type MemoryImportReport, type MemoryExportSnapshot, type MemoryBundleImportPlan, type BundleChallengeRow, type BundleLineageRow, type BundlePollutedSession, type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type MemoryEntryHeader, type MemoryScopeEnumeration, type ScoredMemoryEntry, type NotePatch, type PatchReport, type MaterializedFile, type MemorySessionHandle, type HarvestReport, type HarvestRejection, type HarvestRejectionCode, type ParsedEntryFile, type ScannedEntryFile, SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, type ParsedScopeKey, migrateScope, type MigrateScopeReport, materializeEntriesToFiles, harvestFilesToPatches, projectionsToWriteBack, screenInboundEntries, REMOTE_HARVEST_PER_FILE_BYTES, REMOTE_MASS_DELETION_FUSE_RATIO, type RemoteMemoryFile, type RemoteMemoryBaseline, type RemoteMaterialization, type RemoteHarvestResult, type InboundEntryFinding, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, reconcileMemoryEntries, nextSyncBaseline, mergeRecallHits, type MemorySyncCursor, type MemorySyncConflict, type MemorySyncPlan, type RecallSource, syncMemoryScope, type MemorySyncTransport, type MemorySyncRequestBody, type MemorySyncResponseBody, type MemorySyncClientConflict, type SyncMemoryScopeOptions, type MemorySyncClientResult, } from "./core/memory-engine/index.js";
 export { SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_LIST_PAGE_SIZE, SharedMemoryStoreError, type SharedMemoryStoreProvider, type SharedMemoryStoreReader, type SharedMemoryPagedList, type SharedMemoryStoreInfo, type SharedMemoryDocumentEntry, type SharedMemorySnapshot, type SharedMemoryRequestContext, type MemoryListDetails, type MemoryReadDetails, } from "./core/shared-memory/types.js";
 export { sharedMemoryStoreContract, type SharedMemoryFixture, type SharedMemoryStoreContractHooks, } from "./core/shared-memory/contract.js";
 export { termSet, jaccardDistance, cosineDistance } from "./core/memory-vector.js";

package/dist/orchestration/run-workflow-tool.d.ts

@@ -278,8 +278,8 @@ export interface RunWorkflowToolDeps {
      *  (`RunnerDeps.onAsk`, else the fail-closed headless auto-deny). */
     parentOnAsk?: import("../core/tool-policy.js").OnAsk;
     /** The HOST run's display sink (its `RunInternals.onForwardEvent` behind the runner's ctx wrapper:
-     *  `task_progress` always, plus the children's content events — `text_delta`/`reasoning_delta`/
-     *  `tool_start`/`tool_end`, UNTRUSTED-RAW: the consumer must redact — when the HOST spec set
+     *  `task_progress` always, plus the children's content events — `text_delta`/`text_end`/
+     *  `reasoning_delta`/`tool_start`/`tool_end`, UNTRUSTED-RAW: the consumer must redact — when the HOST spec set
      *  `forwardSubagentEvents: true`) — threaded via `startWorkflow` into every spawned agent's trusted
      *  internals so a workflow child's events bubble to the deployment's one sink, the same
      *  channel a `createSubagentTool` delegation threads. Display-only; absent ⇒ ticks stay in each

package/dist/orchestration/workflow-types.d.ts

@@ -153,6 +153,45 @@ export interface WorkflowRun {
      *  contract (store status filters, terminal checks like `isTerminalWorkflowStatus`, monitor rows all
      *  switch on the closed enum — a new enum value would break them; an optional field cannot). */
     agentFailures?: number;
+    /** The run's TERMINAL token-budget overshoot — present ONLY when the run actually spent MORE than its
+     *  ceiling (`spentTokens + unsettledTokens > budgetTokens`), absent on every run that stayed within it and
+     *  on every run that set no budget at all. Same ADDITIVE-observation contract as {@link agentFailures}
+     *  (never a gate input, never re-read by the engine, and the status enums stay untouched).
+     *
+     *  WHY IT CAN EXIST AT ALL: the budget is a per-CALL ADMISSION gate — it refuses NEW `ctx.agent` calls
+     *  once settled live spend reaches the ceiling, and agents already IN FLIGHT at that moment are not bound
+     *  by it (the {@link WorkflowBudgetExceededError} message promises exactly that: "In-flight agents will
+     *  complete"). So a wide concurrency window can land far past the ceiling while the script's body still
+     *  returns normally — a run that read as an unqualified `completed` with no trace of the overrun anywhere
+     *  on its record. This seat is that trace; the same fact is also narrated on the run's log lane.
+     *
+     *  `budgetTokens` is the configured ceiling and `spentTokens` is the gate's OWN input — LIVE settled spend
+     *  (`ctx.budget.spent()`) at the terminal, which is NOT the same figure as `stats.tokens +
+     *  stats.nested.tokens` (run stats also count REPLAYED work, which the budget deliberately never charges).
+     *
+     *  `unsettledTokens` (present only when non-zero) is spend OBSERVED on agents still IN FLIGHT at the
+     *  terminal — a fire-and-forget `agentStream`, or one a deadline abandoned. Nothing downstream ever
+     *  accounts for it (a settle landing after the run finalized is dropped by design), so it is reported
+     *  here rather than silently lost: without it this seat would answer "no overshoot" for a run that in
+     *  fact burned several times its ceiling. It is kept SEPARATE from `spentTokens` — the own/nested
+     *  discipline {@link WorkflowRunStats} uses — because the two have different standing: settled spend the
+     *  gate itself read, versus a best-known observation the gate never charged. **A consumer measuring the
+     *  overshoot adds them** (`spentTokens + unsettledTokens - budgetTokens`).
+     *
+     *  ⚠️ `unsettledTokens` is an ESTIMATE, stated rather than implied — the SAME live per-turn figure the
+     *  running-agent observation surfaces already show (`stats` while an agent runs), with the same standing:
+     *  · it omits work those agents DELEGATED (that reaches this engine only through `TaskResult.stats.nested`
+     *    at their settle, which for an agent still in flight at the terminal never arrives), and
+     *  · it is the beat's own per-turn arithmetic (cache-inclusive input + output), which APPROXIMATES the
+     *    authoritative per-call figure a settle would have written rather than reproducing it.
+     *  So a run whose overshoot rests ENTIRELY on this member is a best-effort disclosure, not a measurement:
+     *  read it as "this run appears to have overrun, and here is what was seen". `spentTokens` carries no such
+     *  caveat — it is the gate's own settled figure. */
+    budgetOvershoot?: {
+        budgetTokens: number;
+        spentTokens: number;
+        unsettledTokens?: number;
+    };
     phases: WorkflowPhase[];
     agents: WorkflowAgentRun[];
     /** design/97 CORE-3: nested `ctx.workflow` sub-groups (the persisted group tree). Empty when the script
@@ -372,9 +411,17 @@ export declare class WorkflowMaxAgentsError extends Error {
     /** The run's token ceiling AT THE MOMENT THE CAP FIRED, or `null` when the run set no budget. It selects
      *  which cause the message may name — the two are mutually exclusive facts, not one fixed label. */
     readonly budgetTotal: number | null;
+    /** LIVE spend at the moment the cap fired, when the caller knows it. It selects the THIRD arm below:
+     *  a cap that fires while the token ceiling is ALREADY overshot must not send the reader off to raise
+     *  `maxAgents` (raising it buys more overshoot, not less). Absent ⇒ the two historic arms only. */
+    readonly spentTokens?: number | undefined;
     readonly code = "workflow.max_agents";
     constructor(max: number, 
     /** The run's token ceiling AT THE MOMENT THE CAP FIRED, or `null` when the run set no budget. It selects
      *  which cause the message may name — the two are mutually exclusive facts, not one fixed label. */
-    budgetTotal?: number | null);
+    budgetTotal?: number | null, 
+    /** LIVE spend at the moment the cap fired, when the caller knows it. It selects the THIRD arm below:
+     *  a cap that fires while the token ceiling is ALREADY overshot must not send the reader off to raise
+     *  `maxAgents` (raising it buys more overshoot, not less). Absent ⇒ the two historic arms only. */
+    spentTokens?: number | undefined);
 }

package/dist/orchestration/workflow-types.js

@@ -58,17 +58,25 @@ export class WorkflowAgentBlockedError extends Error {
 export class WorkflowMaxAgentsError extends Error {
     max;
     budgetTotal;
+    spentTokens;
     code = "workflow.max_agents";
-    constructor(max, budgetTotal = null) {
+    constructor(max, budgetTotal = null, spentTokens) {
         super(budgetTotal === null
             ? `Workflow agent() call cap reached (${max}). This usually means a loop using budget.remaining() never ` +
                 `terminates because no token budget was set — remaining() returns Infinity when budget.total is null. ` +
                 `Add a hard iteration cap to the loop, or pass a token budget.`
-            : `Workflow agent() call cap reached (${max}). A token budget IS set (${budgetTotal.toLocaleString()} output tokens), ` +
-                `so this is the CALL-COUNT cap, not the token ceiling: the script asked for more than ${max} agent() calls. ` +
-                `Fan out over fewer items, or raise maxAgents.`);
+            : spentTokens !== undefined && spentTokens > budgetTotal
+                ? `Workflow agent() call cap reached (${max}), and the token budget is ALREADY EXCEEDED ` +
+                    `(${spentTokens.toLocaleString()} spent / ${budgetTotal.toLocaleString()} output tokens): agents already in flight when ` +
+                    `the ceiling was reached are not bound by the per-call gate, so their spend landed on top of it. BOTH bounds are ` +
+                    `binding — raising maxAgents alone would only buy more overshoot. Fan out over fewer items, or lower concurrency ` +
+                    `(it bounds the overshoot) and raise the token budget deliberately.`
+                : `Workflow agent() call cap reached (${max}). A token budget IS set (${budgetTotal.toLocaleString()} output tokens), ` +
+                    `so this is the CALL-COUNT cap, not the token ceiling: the script asked for more than ${max} agent() calls. ` +
+                    `Fan out over fewer items, or raise maxAgents.`);
         this.max = max;
         this.budgetTotal = budgetTotal;
+        this.spentTokens = spentTokens;
         this.name = "WorkflowMaxAgentsError";
     }
 }

package/dist/orchestration/workflow.d.ts

@@ -201,8 +201,19 @@ export interface WorkflowAgentHandle {
      * live is parked and delivered into the NEXT turn's context (birth-window delivery, bounded — ledger item 36); steers are
      * delivered in call order, the birth window included. Rejects with `steering.not_running` once the task has
      * finished (teardown included).
+     *
+     * `opts.inputId` is a PASS-THROUGH of the underlying `TaskStream.steer` correlation/idempotency key
+     * (design/171 §6.3 — its whole contract, value domain and typed refusals are that verb's; absent ⇒ byte-identical
+     * to every pre-existing call). A launcher whose own ingress already minted a message id passes it here so the two
+     * legs of one steering ingress are equally replay-safe. ⚠️ ONE arm of that contract is NOT reachable through this
+     * handle, deliberately: the idempotent-REPLAY arm ("same id, same payload ⇒ injects nothing"). Each call mints a
+     * FRESH unguessable correlation marker into the framing it delivers, so a retry under the same id is a
+     * same-id-DIFFERENT-instruction call and refuses typed `steering.duplicate_input_id`. What the key buys on this
+     * lane is therefore AT-MOST-ONCE: a retried ingress is refused LOUDLY instead of injecting a second copy.
      */
-    steer(content: string): Promise<string>;
+    steer(content: string, opts?: {
+        inputId?: string;
+    }): Promise<string>;
     /** Await the agent's {@link TaskResult} (the same value the eager recording used; idempotent). */
     result(): Promise<TaskResult>;
 }
@@ -384,8 +395,8 @@ export interface RunWorkflowOptions {
     parentCenterArtifactDigest?: string;
     parentCenterSourceRevision?: string;
     /** The launching run's display sink (`RunInternals.onForwardEvent` behind the runner's ctx wrapper:
-     *  `task_progress` always, PLUS the children's content events — `text_delta`/`reasoning_delta`/
-     *  `tool_start`/`tool_end`, UNTRUSTED-RAW: the consumer must redact — when the HOST spec set
+     *  `task_progress` always, PLUS the children's content events — `text_delta`/`text_end`/
+     *  `reasoning_delta`/`tool_start`/`tool_end`, UNTRUSTED-RAW: the consumer must redact — when the HOST spec set
      *  `forwardSubagentEvents: true`) — threaded into every spawned agent's trusted internals so the
      *  children's events bubble out of their isolated streams to the deployment's one sink (fleet
      *  footer/monitor rows). Display-only; absent ⇒ ticks stay in each child's own stream. */