@rulvar/core 1.50.0 → 1.52.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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.50.0",
+  "version": "1.52.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",