@rulvar/core 1.51.0 → 1.53.0

package/dist/index.js

@@ -8002,6 +8002,12 @@ function mergeUsageLimits(call, profile, engine) {
 	if (timeoutMs !== void 0) merged.timeoutMs = timeoutMs;
 	const noProgressTurns = pick("noProgressTurns");
 	if (noProgressTurns !== void 0) merged.noProgressTurns = noProgressTurns;
+	const toolBudgetNotices = pick("toolBudgetNotices");
+	if (toolBudgetNotices !== void 0) merged.toolBudgetNotices = toolBudgetNotices;
+	const maxRepeatedToolSignature = pick("maxRepeatedToolSignature");
+	if (maxRepeatedToolSignature !== void 0) merged.maxRepeatedToolSignature = maxRepeatedToolSignature;
+	const maxNoNewEvidenceCalls = pick("maxNoNewEvidenceCalls");
+	if (maxNoNewEvidenceCalls !== void 0) merged.maxNoNewEvidenceCalls = maxNoNewEvidenceCalls;
 	return merged;
 }
 /**
@@ -8023,6 +8029,9 @@ function validateUsageLimits(limits, site) {
 	if (limits.timeoutMs !== void 0) requirePositiveInteger(limits.timeoutMs, `${site}.timeoutMs`);
 	if (limits.streamIdleTimeoutMs !== void 0) requireTimerDelayMs(limits.streamIdleTimeoutMs, `${site}.streamIdleTimeoutMs`);
 	if (limits.noProgressTurns !== void 0) requirePositiveInteger(limits.noProgressTurns, `${site}.noProgressTurns`);
+	if (limits.toolBudgetNotices !== void 0 && typeof limits.toolBudgetNotices !== "boolean") throw new ConfigError(`${site}.toolBudgetNotices must be a boolean; got ${typeof limits.toolBudgetNotices}`);
+	if (limits.maxRepeatedToolSignature !== void 0) requirePositiveInteger(limits.maxRepeatedToolSignature, `${site}.maxRepeatedToolSignature`);
+	if (limits.maxNoNewEvidenceCalls !== void 0) requirePositiveInteger(limits.maxNoNewEvidenceCalls, `${site}.maxNoNewEvidenceCalls`);
 }
 //#endregion
 //#region src/runtime/model-retry.ts
@@ -8518,6 +8527,182 @@ function formatRePrompt(issues, attempt, maxAttempts) {
 	};
 }
 //#endregion
+//#region src/runtime/exploration.ts
+/**
+* Exploration guards (RV-210, first slice): the engine-side counters that
+* make an oscillating tool loop visible and boundable. The published gap:
+* an agent that repeats the byte-identical tool call, or keeps receiving
+* pages it has already seen, burns its whole tool budget with zero signal
+* and dies as a bare 'limit' terminal; the no-progress detector never
+* trips because tool calls reset it.
+*
+* Three opt-in UsageLimits fields drive this module:
+*
+* - `maxRepeatedToolSignature`: how many times the SAME signature (tool
+*   name + RFC 8785 canonical args) may execute per invocation. The call
+*   that would exceed it is not dispatched; the model receives a typed
+*   error tool result instead (visible, bounded, never terminal), and the
+*   denial does not consume the tool budget.
+* - `maxNoNewEvidenceCalls`: how many consecutive successful executions
+*   may return only already-seen result digests before the loop aborts as
+*   status 'limit' with abortClass 'exploration' (paid partial work; the
+*   executed results stand and the terminal memoizes like every
+*   engine-decided abort).
+* - `toolBudgetNotices`: soft 50%/80% thresholds over `maxToolCalls`,
+*   surfaced to the model as a plain user message with the exact
+*   remaining count, so pacing is possible before the hard cap.
+*
+* Determinism: signatures and digests derive from the canonical JCS
+* serialization; values JCS cannot serialize never match anything (a
+* unique signature; a fresh-evidence result), so the guards fail open,
+* never spuriously. On resume the guard state is rebuilt from the
+* restored checkpoint messages (successful executions only, and only the
+* window a compaction kept), which is the same source the model itself
+* sees; enforcement is engine-side and live-only, while a replayed
+* guard abort is re-stamped from the journaled terminal like every other
+* abort class.
+*/
+/** The docs anchor cited by guard denials and the guard abort. */
+const GUARD_DOCS_URL = "https://docs.rulvar.com/guide/agents#exploration-guards";
+/** True when any exploration guard field asks for tracking. */
+function explorationTrackingEnabled(limits) {
+	return limits.maxRepeatedToolSignature !== void 0 || limits.maxNoNewEvidenceCalls !== void 0 || limits.toolBudgetNotices === true;
+}
+function digestOf$1(value) {
+	try {
+		return createHash("sha256").update(jcsSerialize(value), "utf8").digest("hex");
+	} catch {
+		return;
+	}
+}
+var ExplorationGuard = class {
+	config;
+	signatureExecutions = /* @__PURE__ */ new Map();
+	seenDigests = /* @__PURE__ */ new Set();
+	byTool = /* @__PURE__ */ new Map();
+	noNewEvidenceStreak = 0;
+	executed = 0;
+	repeated = 0;
+	duplicateResults = 0;
+	denied = 0;
+	unserializableSeq = 0;
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* The canonical signature: tool name + JCS args. Args JCS cannot
+	* serialize get a unique per-occurrence signature, so they never
+	* repeat and the guard fails open.
+	*/
+	signatureOf(name, args) {
+		try {
+			return `${name}\u0000${jcsSerialize(args ?? null)}`;
+		} catch {
+			this.unserializableSeq += 1;
+			return `${name}\u0000<unserializable:${String(this.unserializableSeq)}>`;
+		}
+	}
+	/**
+	* Rebuilds guard state from restored checkpoint messages: assistant
+	* tool-call parts paired with their successful tool results by id.
+	* Error results (denials, tool failures) are skipped, so a resume
+	* never over-counts; a compaction naturally narrows the window to
+	* what the model itself still sees.
+	*/
+	restore(messages) {
+		const callsById = /* @__PURE__ */ new Map();
+		for (const msg of messages) for (const part of msg.parts) if (part.type === "tool-call") callsById.set(part.id, {
+			name: part.name,
+			args: part.args
+		});
+		else if (part.type === "tool-result" && part.isError !== true) {
+			const call = callsById.get(part.id);
+			if (call === void 0) continue;
+			this.recordExecution(call.name, call.args, part.result, true);
+		}
+	}
+	/**
+	* The pre-dispatch verdict: denies the call that would exceed
+	* maxRepeatedToolSignature executions of the same signature.
+	*/
+	beforeExecute(name, args) {
+		const max = this.config.maxRepeatedToolSignature;
+		if (max === void 0) return { deny: false };
+		const executions = this.signatureExecutions.get(this.signatureOf(name, args)) ?? 0;
+		if (executions < max) return { deny: false };
+		this.denied += 1;
+		return {
+			deny: true,
+			executions,
+			reason: `exploration guard: this exact '${name}' call already executed ${String(executions)} time(s) this invocation (maxRepeatedToolSignature ${String(max)}). Reuse the earlier result or change the arguments (${GUARD_DOCS_URL}).`
+		};
+	}
+	/**
+	* Records one dispatched execution and answers whether the
+	* no-new-evidence guard trips. Only successful results feed the
+	* evidence chain: an error result neither resets nor lengthens it
+	* (repeated failing calls are the signature guard's job), and a
+	* result JCS cannot digest counts as fresh evidence.
+	*/
+	afterExecute(name, args, result, isError) {
+		return this.recordExecution(name, args, result, !isError);
+	}
+	recordExecution(name, args, result, successful) {
+		this.executed += 1;
+		this.byTool.set(name, (this.byTool.get(name) ?? 0) + 1);
+		const signature = this.signatureOf(name, args);
+		const prior = this.signatureExecutions.get(signature) ?? 0;
+		if (prior > 0) this.repeated += 1;
+		this.signatureExecutions.set(signature, prior + 1);
+		if (!successful) return false;
+		const digest = digestOf$1(result);
+		if (digest === void 0 || !this.seenDigests.has(digest)) {
+			if (digest !== void 0) this.seenDigests.add(digest);
+			this.noNewEvidenceStreak = 0;
+			return false;
+		}
+		this.duplicateResults += 1;
+		this.noNewEvidenceStreak += 1;
+		const max = this.config.maxNoNewEvidenceCalls;
+		return max !== void 0 && this.noNewEvidenceStreak >= max;
+	}
+	/** The abort message for a tripped no-new-evidence guard. */
+	describeTrip() {
+		return `exploration guard: ${String(this.noNewEvidenceStreak)} consecutive tool calls returned no new evidence (maxNoNewEvidenceCalls ${String(this.config.maxNoNewEvidenceCalls ?? this.noNewEvidenceStreak)}; every result was already seen this invocation). The executed work is kept; narrow the scope, vary the queries, or raise the limit (${GUARD_DOCS_URL}).`;
+	}
+	/** The structured summary; `toolCallsUsed` is the loop's own counter. */
+	summary(toolCallsUsed) {
+		const byTool = {};
+		for (const [name, count] of [...this.byTool.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) byTool[name] = count;
+		return {
+			toolCallsUsed,
+			distinctSignatures: this.signatureExecutions.size,
+			repeatedCalls: this.repeated,
+			duplicateResultCalls: this.duplicateResults,
+			deniedRepeats: this.denied,
+			byTool
+		};
+	}
+};
+/** The soft notice thresholds over maxToolCalls, in ascending order. */
+const TOOL_BUDGET_NOTICE_THRESHOLDS = [.5, .8];
+/**
+* Which notice thresholds `used` calls out of `max` have crossed
+* (ceil-based, so a threshold fires no earlier than its exact fraction).
+*/
+function crossedNoticeThresholds(used, max) {
+	return TOOL_BUDGET_NOTICE_THRESHOLDS.filter((threshold) => used >= Math.ceil(threshold * max)).map((threshold) => threshold);
+}
+/**
+* The model-visible budget notice. Deterministic for a given usage
+* count, so a recorded conversation rebuilds byte-identically on
+* resume and replay.
+*/
+function toolBudgetNoticeText(used, max) {
+	const remaining = Math.max(0, max - used);
+	return `Tool budget notice: ${String(used)} of ${String(max)} tool calls used; ${String(remaining)} remaining. Prioritize the highest value calls and finish with what you have.`;
+}
+//#endregion
 //#region src/runtime/agent-loop.ts
 /**
 * Agent runtime v1 (M1-T06): the single subagent loop shared by every
@@ -8978,6 +9163,34 @@ async function runAgent(options) {
 	let escalationRequest;
 	let abortClass;
 	const noProgress = new NoProgressDetector(limits.noProgressTurns);
+	const guard = explorationTrackingEnabled(limits) ? new ExplorationGuard(limits) : void 0;
+	if (limits.toolBudgetNotices === true && limits.maxToolCalls === void 0) events?.emit({
+		type: "log",
+		level: "warn",
+		msg: "toolBudgetNotices is enabled but maxToolCalls is not set; the notices are inert"
+	});
+	const firedNotices = /* @__PURE__ */ new Set();
+	/**
+	* Pushes the soft tool-budget notice when an unfired threshold has
+	* been crossed (one message per boundary, carrying the exact counts,
+	* so the model can pace itself before the hard cap). The notice is an
+	* ordinary user message: it rides checkpoints and transcripts, so a
+	* resume never re-fires a threshold the restored count already
+	* crossed.
+	*/
+	const maybePushBudgetNotice = () => {
+		if (limits.toolBudgetNotices !== true || limits.maxToolCalls === void 0) return;
+		const crossed = crossedNoticeThresholds(toolCallsUsed, limits.maxToolCalls).filter((threshold) => !firedNotices.has(threshold));
+		if (crossed.length === 0) return;
+		for (const threshold of crossed) firedNotices.add(threshold);
+		messages.push({
+			role: "user",
+			parts: [{
+				type: "text",
+				text: toolBudgetNoticeText(toolCallsUsed, limits.maxToolCalls)
+			}]
+		});
+	};
 	const modelRetryCounts = /* @__PURE__ */ new Map();
 	let lastTurnUsage = {
 		inputTokens: 0,
@@ -9004,6 +9217,8 @@ async function runAgent(options) {
 			addPhaseUsage(slice.role ?? primaryRole, slice.servedBy, sliceUsage);
 			options.budget?.onUsage(sliceUsage, slice.servedBy);
 		}
+		guard?.restore(messages);
+		if (limits.toolBudgetNotices === true && limits.maxToolCalls !== void 0) for (const threshold of crossedNoticeThresholds(toolCallsUsed, limits.maxToolCalls)) firedNotices.add(threshold);
 	}
 	const usageSlices = () => [...usageByPhaseModel.values()].map(({ role, servedBy: sliceServedBy, usage }) => ({
 		servedBy: sliceServedBy,
@@ -9222,8 +9437,25 @@ async function runAgent(options) {
 					finished: finishArgs.result ?? null
 				};
 			}
+			if (guard !== void 0) {
+				const guardVerdict = guard.beforeExecute(gatedCall.name, gatedCall.args);
+				if (guardVerdict.deny) {
+					events?.emit({
+						type: "tool:end",
+						toolName: gatedCall.name,
+						outcome: "denied",
+						durationMs: now() - gateStartedAt,
+						guard: "repeated-signature"
+					});
+					parts.push(errorPart(call, {
+						error: guardVerdict.reason,
+						guard: "repeated-signature"
+					}));
+					continue;
+				}
+			}
 			toolCallsUsed += 1;
-			parts.push(await executeToolCall({
+			const executedPart = await executeToolCall({
 				call: gatedCall,
 				runtime,
 				retryCounts: modelRetryCounts,
@@ -9231,7 +9463,16 @@ async function runAgent(options) {
 				...events === void 0 ? {} : { events },
 				...gateAudit === void 0 ? {} : { audit: gateAudit },
 				now
-			}));
+			});
+			parts.push(executedPart);
+			if (guard !== void 0) {
+				const executedRecord = executedPart;
+				if (guard.afterExecute(gatedCall.name, gatedCall.args, executedRecord.result, executedRecord.isError === true)) return {
+					parts,
+					limitHit: true,
+					guardTrip: true
+				};
+			}
 		}
 		return {
 			parts,
@@ -9249,7 +9490,7 @@ async function runAgent(options) {
 			if (record.isError === true) part.isError = true;
 			return part;
 		});
-		const { parts, limitHit, escalated, finished } = await runToolCalls([restored.pending.awaiting, ...restored.pending.remaining], priorParts);
+		const { parts, limitHit, escalated, finished, guardTrip } = await runToolCalls([restored.pending.awaiting, ...restored.pending.remaining], priorParts);
 		if (parts.length > 0) messages.push({
 			role: "tool",
 			parts
@@ -9261,8 +9502,20 @@ async function runAgent(options) {
 			output = finished;
 			finishedViaTool = true;
 			await saveBoundary();
-		} else if (limitHit) status = "limit";
-		else await saveBoundary();
+		} else if (limitHit) {
+			status = "limit";
+			if (guardTrip === true && guard !== void 0) {
+				abortClass = "exploration";
+				agentError = {
+					kind: "terminal",
+					retryable: false
+				};
+				errorMessage = guard.describeTrip();
+			}
+		} else {
+			maybePushBudgetNotice();
+			await saveBoundary();
+		}
 	}
 	const separateExtract = options.extract !== void 0 && options.schema !== void 0;
 	events?.emit({
@@ -9597,7 +9850,7 @@ async function runAgent(options) {
 		}
 		if (options.tools !== void 0 && outcome.turn.toolCalls.length > 0) {
 			noProgress.recordTurn({ toolCalls: outcome.turn.toolCalls.length });
-			const { parts, limitHit, escalated, finished } = await runToolCalls(outcome.turn.toolCalls, []);
+			const { parts, limitHit, escalated, finished, guardTrip } = await runToolCalls(outcome.turn.toolCalls, []);
 			if (parts.length > 0) messages.push({
 				role: "tool",
 				parts
@@ -9615,8 +9868,17 @@ async function runAgent(options) {
 			}
 			if (limitHit) {
 				status = "limit";
+				if (guardTrip === true && guard !== void 0) {
+					abortClass = "exploration";
+					agentError = {
+						kind: "terminal",
+						retryable: false
+					};
+					errorMessage = guard.describeTrip();
+				}
 				break;
 			}
+			maybePushBudgetNotice();
 			if (options.summarize !== void 0 && !compactionDisabled && shouldCompact({
 				lastTurnUsage,
 				contextWindow: options.adapter.caps(options.resolved.model).contextWindow,
@@ -10057,6 +10319,7 @@ async function runAgent(options) {
 	if (escalationRequest !== void 0) result.escalationRequest = escalationRequest;
 	if (abortClass !== void 0) result.abortClass = abortClass;
 	if (errorMessage !== void 0) result.errorMessage = errorMessage;
+	if (guard !== void 0) result.exploration = guard.summary(toolCallsUsed);
 	if (usageApprox) result.usageApprox = true;
 	if (transportRetries > 0) result.transportRetries = transportRetries;
 	return result;
@@ -11891,8 +12154,9 @@ function createCtx(internals, rootWorkflow) {
 			if (terminal?.artifacts !== void 0) result.artifacts = terminal.artifacts;
 			if (terminal?.status === "escalated" && terminal.escalation !== void 0) result.escalation = terminal.escalation;
 			{
-				const stamped = (terminal?.error?.data)?.abortClass;
-				if (stamped !== void 0) result.abortClass = stamped;
+				const stampedData = terminal?.error?.data;
+				if (stampedData?.abortClass !== void 0) result.abortClass = stampedData.abortClass;
+				if (stampedData?.exploration !== void 0) result.exploration = stampedData.exploration;
 			}
 			let replayedToolResults = [];
 			if (matched.kind === "replay" && terminal?.checkpointRef !== void 0) {
@@ -11956,7 +12220,8 @@ function createCtx(internals, rootWorkflow) {
 				usage,
 				costUsd,
 				entryRef: terminal?.seq ?? matched.running.seq,
-				...terminal?.usageApprox === true ? { usageApprox: true } : {}
+				...terminal?.usageApprox === true ? { usageApprox: true } : {},
+				...result.exploration === void 0 ? {} : { exploration: result.exploration }
 			}, spanId, true);
 			for (const slice of replayPriced?.priced ?? []) bump(internals.cost.byModel, slice.servedBy, slice.usd);
 			for (const slice of replayPriced?.unpriced ?? []) internals.cost.unpriced.push({
@@ -12423,7 +12688,8 @@ function createCtx(internals, rootWorkflow) {
 					...terminalPatch.error,
 					data: {
 						...dataRecord,
-						abortClass: result.abortClass
+						abortClass: result.abortClass,
+						...result.abortClass === "exploration" && result.exploration !== void 0 ? { exploration: result.exploration } : {}
 					}
 				};
 			}
@@ -12439,7 +12705,8 @@ function createCtx(internals, rootWorkflow) {
 			costUsd: result.costUsd,
 			entryRef: terminal.seq,
 			...resultUsageApprox ? { usageApprox: true } : {},
-			...result.transportRetries !== void 0 && result.transportRetries > 0 ? { retryCount: result.transportRetries } : {}
+			...result.transportRetries !== void 0 && result.transportRetries > 0 ? { retryCount: result.transportRetries } : {},
+			...result.exploration === void 0 ? {} : { exploration: result.exploration }
 		}, spanId);
 		if (result.status === "escalated" && result.escalation !== void 0) {
 			let decision = flavorBDecision;
@@ -13019,6 +13286,11 @@ async function executeWorkflow(internals, wf, args) {
 */
 /** How many rejected finishes are repaired by default: the plan's repair once. */
 const DEFAULT_FINISH_MAX_REPAIRS = 1;
+/**
+* Default maxTurns of the synthesize invocation (RV-211): the finish
+* call plus headroom for one validator repair exchange.
+*/
+const DEFAULT_SYNTHESIS_MAX_TURNS = 4;
 const ORCHESTRATE_WORKFLOW_NAME = "rulvar-orchestrate";
 /**
 * One page of a string, for the child result evidence tools: maxChars is
@@ -13076,6 +13348,19 @@ function validateOrchestrateOptions(opts) {
 		}
 		if (fv.maxRepairs !== void 0) requireNonNegativeInteger(fv.maxRepairs, "orchestrate finishValidation.maxRepairs");
 	}
+	if (opts.synthesis !== void 0) {
+		const synthesis = opts.synthesis;
+		if (synthesis.effort !== void 0 && ![
+			"low",
+			"medium",
+			"high",
+			"xhigh",
+			"max"
+		].includes(synthesis.effort)) throw new ConfigError(`orchestrate synthesis.effort must be one of 'low' | 'medium' | 'high' | 'xhigh' | 'max'; got ${JSON.stringify(synthesis.effort)}`);
+		if (synthesis.limits !== void 0) validateUsageLimits(synthesis.limits, "orchestrate synthesis.limits");
+		if (synthesis.instructions !== void 0 && typeof synthesis.instructions !== "string") throw new ConfigError(`orchestrate synthesis.instructions must be a string; got ${typeof synthesis.instructions}`);
+		if (synthesis.estCost !== void 0) requireNonNegativeNumber(synthesis.estCost, "orchestrate synthesis.estCost");
+	}
 	const spec = opts.budget;
 	if (spec === void 0) return;
 	if (spec.capUsd !== void 0) requireNonNegativeNumber(spec.capUsd, "orchestrate budget.capUsd");
@@ -14063,7 +14348,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 			},
 			[kTerminalTool]: {
 				name: FINISH_TOOL_NAME,
-				...validationSpec === void 0 ? {} : { validate: validateFinish }
+				...validationSpec === void 0 || opts?.synthesis !== void 0 ? {} : { validate: validateFinish }
 			},
 			...(() => {
 				const priorCancelledRoot = internals.replayer.snapshot().filter((entry) => entry.kind === "agent" && entry.scope === callingState.scope && entry.status === "cancelled" && entry.checkpointRef !== void 0).at(-1);
@@ -14140,6 +14425,96 @@ function makeOrchestratorWorkflow(goal, opts) {
 			};
 		};
 		/**
+		* The post-fan-in synthesis invocation (RV-211): a FRESH agent entry
+		* with role 'synthesize' on the finish-only toolset (a distinct
+		* toolsetHash, the reserved-finalizer precedent), its prompt derived
+		* deterministically from the goal, the journaled coordination draft,
+		* and the settled child digest, so a resume replays it by identity
+		* with zero paid calls. Runs strictly AFTER the acceptance verdict
+		* (a rejected run never pays for synthesis) and owns the finish
+		* validators when they are configured. Failure posture: with
+		* validators the run fails typed (the validated path is mandatory);
+		* without them the run falls back to the draft under a journaled
+		* decision and a warn log, never silently.
+		*/
+		const runSynthesis = async (draft) => {
+			const spec = opts?.synthesis;
+			if (spec === void 0) return draft;
+			await recoveryDone;
+			const finishOnly = buildOrchestratorTools(orchestratorRuntime, fullCardText).filter((tool) => tool.name === FINISH_TOOL_NAME);
+			const settledDigests = [...records.values()].filter((record) => record.settled !== void 0).sort((a, b) => a.spawnOrdinal - b.spawnOrdinal).map((record) => digestOf(record, record.settled));
+			const draftJson = JSON.stringify(draft ?? null);
+			const digestJson = JSON.stringify(settledDigests);
+			const prompt = [
+				"You are the synthesis invocation of an orchestrated run. Compose the FINAL result of the run from the goal, the coordination draft, and the settled child evidence below by calling finish({ result }) EXACTLY once. Preserve the evidence and citations the draft relies on; do not invent findings. No other tool exists.",
+				...spec.instructions === void 0 ? [] : [spec.instructions],
+				...finishValidationPromptLines(validationSpec),
+				`GOAL: ${goal}`,
+				`DRAFT: ${draftJson}`,
+				`DIGEST: ${digestJson}`
+			].join("\n");
+			internals.events.emit({
+				type: "log",
+				level: "debug",
+				msg: "orchestrator synthesis context",
+				data: {
+					children: settledDigests.length,
+					draftChars: draftJson.length,
+					digestChars: digestJson.length,
+					promptChars: prompt.length,
+					perChild: settledDigests.map((entry) => ({
+						nodeId: entry.nodeId,
+						chars: JSON.stringify(entry).length
+					}))
+				}
+			}, callingState.spanId);
+			const synthesisState = { ...callingState };
+			if (orchestratorAccount !== void 0) synthesisState.budgetScope = orchestratorAccount;
+			const synthesisBreak = validationSpec === void 0 ? void 0 : validationAbort.signal;
+			if (synthesisBreak !== void 0) synthesisState.signal = callingState.signal === void 0 ? synthesisBreak : AbortSignal.any([callingState.signal, synthesisBreak]);
+			const synthesisOpts = {
+				role: "synthesize",
+				result: "full",
+				tools: finishOnly,
+				limits: spec.limits ?? { maxTurns: 4 },
+				...spec.model === void 0 ? {} : { model: spec.model },
+				...spec.effort === void 0 ? {} : { effort: spec.effort },
+				...spec.estCost === void 0 ? {} : { estCost: spec.estCost },
+				[kTerminalTool]: {
+					name: FINISH_TOOL_NAME,
+					...validationSpec === void 0 ? {} : { validate: validateFinish }
+				}
+			};
+			const synthesized = await runtime.runInScope(synthesisState, () => ctx.agent(prompt, synthesisOpts));
+			if (validationTermination !== void 0) throw validationTermination;
+			if (synthesized.status === "ok") return synthesized.output;
+			if (validationSpec !== void 0) throw new FailRunError(`the synthesis invocation terminated with status '${synthesized.status}'` + (synthesized.errorMessage === void 0 ? "" : `: ${synthesized.errorMessage}`) + "; finish validators are configured, so the unvalidated draft cannot stand", { data: {
+				source: "orchestrator_synthesis",
+				status: synthesized.status,
+				turnsUsed: synthesized.turns
+			} });
+			const fallbackKey = deriverV2.deriveKey({ kind: "orchestrator-synthesis-fallback" });
+			if (!internals.replayer.snapshot().some((entry) => entry.kind === "decision" && entry.key === fallbackKey)) await internals.replayer.appendSinglePhase({
+				scope: callingState.scope,
+				key: fallbackKey,
+				kind: "decision",
+				status: "ok",
+				spanId: internals.spans.mint(callingState.spanId),
+				site: "orchestrator-synthesis",
+				value: {
+					decisionType: "orchestrator_synthesis_fallback",
+					status: synthesized.status,
+					turnsUsed: synthesized.turns
+				}
+			});
+			internals.events.emit({
+				type: "log",
+				level: "warn",
+				msg: `the synthesis invocation terminated with status '${synthesized.status}'; falling back to the coordination draft (journaled decision 'orchestrator_synthesis_fallback')`
+			}, callingState.spanId);
+			return draft;
+		};
+		/**
 		* The settle at the cap: the JOURNALED cap decision drives the policy
 		* branch (its `fallback` field froze budget.atCap when the cap
 		* tripped), so a crash between the decision and its effect rolls the
@@ -14173,7 +14548,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 		if (validationTermination !== void 0) throw validationTermination;
 		if (orchestratorAccount !== void 0) internals.cost.orchestrator.spentUsd = internals.budget.accountView(orchestratorAccount)?.spentUsd ?? 0;
 		if (result.status !== "ok") throw new ConfigError(`the orchestrator agent terminated with status '${result.status}'` + (result.errorMessage === void 0 ? "" : `: ${result.errorMessage}`));
-		if (opts?.acceptance === void 0) return result.output;
+		if (opts?.acceptance === void 0) return await runSynthesis(result.output);
 		const acceptanceKey = "acceptance";
 		const priorAcceptance = internals.replayer.snapshot().find((entry) => entry.kind === "decision" && entry.scope === callingState.scope && entry.key === acceptanceKey);
 		let decision;
@@ -14217,7 +14592,7 @@ function makeOrchestratorWorkflow(goal, opts) {
 			} });
 		}
 		return {
-			result: result.output,
+			result: await runSynthesis(result.output),
 			completion: decision.completion,
 			childStatusCounts: decision.childStatusCounts,
 			degradedReasons: decision.degradedReasons
@@ -14539,6 +14914,54 @@ function reduceInvocationTable(events) {
 		totalCostUsd
 	};
 }
+function reduceCriticalPath(events) {
+	let runStart;
+	let runEnd;
+	const startBySpan = /* @__PURE__ */ new Map();
+	let lastWorkerEnd;
+	let workerSpans = 0;
+	let synthesisMs = 0;
+	for (const event of events) {
+		const at = Date.parse(event.ts);
+		if (!Number.isFinite(at)) continue;
+		switch (event.type) {
+			case "run:start":
+				runStart ??= at;
+				break;
+			case "run:end":
+				runEnd = at;
+				break;
+			case "agent:start":
+				startBySpan.set(event.spanId, {
+					role: event.role,
+					at
+				});
+				break;
+			case "agent:end": {
+				const started = startBySpan.get(event.spanId);
+				if (started === void 0) break;
+				if (started.role === "synthesize") synthesisMs += Math.max(0, at - started.at);
+				else if (started.role !== "orchestrate") {
+					workerSpans += 1;
+					lastWorkerEnd = lastWorkerEnd === void 0 ? at : Math.max(lastWorkerEnd, at);
+				}
+				break;
+			}
+			default: break;
+		}
+	}
+	const path = {
+		synthesisMs,
+		workerSpans
+	};
+	if (runStart !== void 0 && runEnd !== void 0) path.runWallMs = Math.max(0, runEnd - runStart);
+	if (runEnd !== void 0 && lastWorkerEnd !== void 0) path.postFanInMs = Math.max(0, runEnd - lastWorkerEnd);
+	if (path.runWallMs !== void 0 && path.runWallMs > 0) {
+		if (path.postFanInMs !== void 0) path.postFanInShare = path.postFanInMs / path.runWallMs;
+		path.synthesisShare = synthesisMs / path.runWallMs;
+	}
+	return path;
+}
 //#endregion
 //#region src/l0/run-id.ts
 /**
@@ -15666,4 +16089,4 @@ function createSandboxBridge(ctx, options) {
 	};
 }
 //#endregion
-export { AWAIT_SCHEMA, AdmissionController, AdmissionRejectedError, AgentCallError, BUDGET_ABORT_REASON, BudgetExhaustedError, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, ConfigError, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_CHILD_RESULT_PAGE_CHARS, DEFAULT_CITATION_PATTERN, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_EVIDENCE_MIN_SHARE, DEFAULT_FINISH_MAX_REPAIRS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DedupIndex, DeterminismError, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EVENT_SEGMENT_STRIDE, EscalationDecisionAbortedError, EventBus, ExternalRegistry, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailRunError, FileModelKnowledgeStore, FileTranscriptStore, GET_CHILD_RESULT_SCHEMA, GET_CHILD_RESULT_TOOL_NAME, GitWorktreeProvider, INBOX_PROPOSAL_TTL_DAYS, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, InvalidResolutionError, JournalCompatibilityError, JournalMatcher, JournalMissError, JournalOrderViolation, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, KeyedLimiter, KnowledgeCasError, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LeaseHeldError, LineageIndex, MASKED_SECRET, MAX_CHILD_RESULT_PAGE_CHARS, MAX_DEPTH_CEILING, ModelRetry, NoProgressDetector, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OrchestratorCapConfigError, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, PlanInvariantError, READ_CHILD_ARTIFACT_SCHEMA, READ_CHILD_ARTIFACT_TOOL_NAME, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, RUN_SETTLE_DECISION_TYPE, ReplayPlanHashMismatch, Replayer, ResolutionArbiter, ResolutionFold, RulvarError, RunBudget, SANDBOX_AGENT_OPT_KEYS, SPAWN_AGENT_SCHEMA, SandboxError, ScriptRejected, Semaphore, SpanRegistry, TOOL_NAME_PATTERN, TerminationAccount, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, assertFencedWrites, atCompactionThreshold, auditRun, auditRuns, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileVerifiedLayer, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, evidencePreservedValidator, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hasFencedWrites, hasMetaLookup, hashRunArgs, hashRunOutput, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lastRunSettle, lexShellCommand, liftRetainedParts, lineageWeightOf, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, mergeUsageLimits, metaMatchesFilter, minMatchesValidator, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, readRunMeta, readTerminationInit, reconcileRunMeta, reduceInvocationTable, registryKeyRing, remeasureQueue, replayDisposition, requiredFieldsValidator, requiredSectionsValidator, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTerminalText, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, selectStructuredOutputTier, shouldCompact, snapshotUsage, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateRetryPolicy, validateSchemaSpec, validateTerminationLimits, validateUsageLimits, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };
+export { AWAIT_SCHEMA, AdmissionController, AdmissionRejectedError, AgentCallError, BUDGET_ABORT_REASON, BudgetExhaustedError, CANCEL_AGENT_SCHEMA, CHECKPOINT_FORMAT_V1, CLAIM_STATEMENT_MAX_CHARS, CLAIM_TTL_DAYS, COMPACTION_SUMMARY_PREFIX, CURRENT_HASH_VERSION, ConfigError, DEFAULT_CHILD_BUDGET_FRACTION, DEFAULT_CHILD_RESULT_PAGE_CHARS, DEFAULT_CITATION_PATTERN, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_ESCALATION_LIMITS, DEFAULT_EVIDENCE_MIN_SHARE, DEFAULT_FINISH_MAX_REPAIRS, DEFAULT_FLAT_RESERVE_USD, DEFAULT_MAX_CHILDREN_PER_NODE, DEFAULT_MAX_DEPTH, DEFAULT_MAX_OSCILLATIONS_PER_KEY, DEFAULT_MAX_PINNED_WORKTREES, DEFAULT_MAX_REVISIONS_PER_RUN, DEFAULT_MAX_TOTAL_SPAWNS, DEFAULT_MAX_TURNS, DEFAULT_MODEL_RETRY_ATTEMPTS, DEFAULT_NO_PROGRESS_TURNS, DEFAULT_PER_RUN_CONCURRENCY, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DEFAULT_SYNTHESIS_MAX_TURNS, DedupIndex, DeterminismError, EMIT_RESULT_TOOL, EMPTY_SCHEMA_HASH, EMPTY_TOOLSET_HASH, ESCALATE_TOOL_NAME, ESCALATION_REPORT_SCHEMA, ESCALATION_REQUEST_SCHEMA, EVENT_SEGMENT_STRIDE, EscalationDecisionAbortedError, EventBus, ExternalRegistry, FINALIZE_SYNTHESIS_INSTRUCTION, FINISH_SCHEMA, FINISH_TOOL_NAME, FailRunError, FileModelKnowledgeStore, FileTranscriptStore, GET_CHILD_RESULT_SCHEMA, GET_CHILD_RESULT_TOOL_NAME, GitWorktreeProvider, INBOX_PROPOSAL_TTL_DAYS, InMemoryStore, InMemoryTranscriptStore, InProcessRunner, InvalidResolutionError, JournalCompatibilityError, JournalMatcher, JournalMissError, JournalOrderViolation, JsonlFileStore, KB_ACTIVE_CLAIMS_CAP, KB_CARD_RENDER_BUDGET_CHARS, KeyedLimiter, KnowledgeCasError, LARGE_VALUE_WARN_BYTES, LEGACY_LTID_PREFIX, LEGACY_SIGNATURE_INPUTS, LINEAGE_SIG_VERSION, LeaseHeldError, LineageIndex, MASKED_SECRET, MAX_CHILD_RESULT_PAGE_CHARS, MAX_DEPTH_CEILING, ModelRetry, NoProgressDetector, NonSerializableValueError, ORCHESTRATE_WORKFLOW_NAME, OrchestratorCapConfigError, PARALLEL_AGENTS_SCHEMA, ParallelSiteCounter, PlanInvariantError, READ_CHILD_ARTIFACT_SCHEMA, READ_CHILD_ARTIFACT_TOOL_NAME, ROLE_EFFORT_DEFAULTS, ROOT_ACCOUNT, ROOT_SCOPE, RUN_PROFILES, RUN_SETTLE_DECISION_TYPE, ReplayPlanHashMismatch, Replayer, ResolutionArbiter, ResolutionFold, RulvarError, RunBudget, SANDBOX_AGENT_OPT_KEYS, SPAWN_AGENT_SCHEMA, SandboxError, ScriptRejected, Semaphore, SpanRegistry, TOOL_NAME_PATTERN, TerminationAccount, WAIT_FOR_EVENTS_SCHEMA, WAIT_FOR_EVENTS_TOOL_NAME, WAKE_SUMMARY_RENDER_BUDGET_CHARS, admissionReserveUsd, affordableOutputTokens, agentErrorFromWire, agentErrorToWire, agentResultWire, agentScope, applyClaimOps, applyStructuredOutputTier, approachSigCoarse, approachSigOf, archiveDeprecatedModelOps, assertFencedWrites, atCompactionThreshold, auditRun, auditRuns, buildAbandonFold, buildAdapterRegistry, buildCostReport, buildDeriverRegistry, buildOrchestratorTools, buildTerminationInitValue, buildToolContext, canRideLoopTurn, canonicalIsolationTag, canonicalizeLadder, canonicalizeSchema, capIssues, capsHashOf, checkFloors, checkpointRefFor, childCoveragePrefix, claimExpired, claimExpiry, claimIssues, claimOpIssues, classifyAgentError, classifyAttemptOutcome, collectDeclaredLadders, compactMessages, compilePermissionChain, compilePermissionPreset, compileVerifiedLayer, costReportFromJournal, countsAgainstLimit, createCanonicalIdMinter, createCtx, createEngine, createSandboxBridge, currentOnlyKeyRing, decodeCheckpoint, defineWorkflow, deriveContentKey, deriverV1, deriverV2, digestOf, dispositionHook, emptyDigestBlocks, emptyToolset, encodeCheckpoint, entryUsageSlices, escalateTool, evaluatePermission, evaluateReuse, evidencePreservedValidator, executeWorkflow, exhaustionCodeOf, extractCandidate, failoverTriggerOf, fallbackTriggerOf, filterClaimsForRun, finalizeFires, foldTermination, formatRePrompt, formatScopePath, hasFencedWrites, hasMetaLookup, hashRunArgs, hashRunOutput, hashWorkflowBody, hashWorkflowSource, identityJcs, isEscalated, isSchemaPairSpec, isStandardSchemaSpec, isStrictCompatibleSchema, kMaxOf, knowledgeHash, ladderLengthOf, ladderRungChoice, lastRunSettle, lexShellCommand, liftRetainedParts, lineageWeightOf, makeOrchestratorWorkflow, maskSecrets, maskSecretsDeep, maskSecretsJson, matchArgvPattern, matchShellCommand, mcp, mergeUsageLimits, metaMatchesFilter, minMatchesValidator, modelEpochOf, modelKnowledgeCard, modelSpecIdentity, needsSeparateExtract, nextFailover, nodeLinkKey, normalizeApproachTag, normalizeEntry, normalizeFallbacks, orchestrate, parallelScope, parseModelRef, parseScopePath, phiInitialOf, pipelineScope, planNodeScope, priceEntryUsage, priceUsdOf, profileCard, profileRegistrySnapshotHash, projectHistory, projectIdentity, projectToJsonSchema, proposalStatement, providerOf, readRunMeta, readTerminationInit, reconcileRunMeta, reduceCriticalPath, reduceInvocationTable, registryKeyRing, remeasureQueue, replayDisposition, requiredFieldsValidator, requiredSectionsValidator, resolveModelInvocation, resolvePricing, resolveToolset, retryClassOf, retryDelayMs, roleConfiguredInRouting, roundOneDisposition, runAgent, runProfile, sanitizeTerminalText, sanitizeTokenCount, sanitizeUsage, sanitizeUsageDelta, scanJournalCompatibility, schemaHash, schemaHashOfSpec, selectStructuredOutputTier, shouldCompact, snapshotUsage, spawnDepthOf, summarizeInstruction, summarizeOutput, terminationConfigDrift, tierWithinCaps, toApprovalDecision, toJournalValue, tool, toolContract, toolsetHash, ttlState, usageViolations, validateEditorialCommit, validateEntryShape, validateEscalationLimits, validateEscalationReport, validateRetryPolicy, validateSchemaSpec, validateTerminationLimits, validateUsageLimits, workflowScope, workflowSourceRef, wrapJournalStore, wrapTranscriptStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.51.0",
+  "version": "1.53.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",