@rulvar/core 1.59.2 → 1.59.3

package/dist/index.d.ts

@@ -4094,8 +4094,14 @@ interface ToolRuntime {
   * toolset holds any non-inprocess tool; the ctx layer mints the tool
   * span and idempotency key and wires the provider. A throw becomes the
   * call's error tool result exactly like an inprocess execute throw.
-  */
-  executeExternal?: (def: ToolDef, args: Json) => Promise<unknown>;
+  *
+  * `ordinal` is the call's 1-based position in this agent invocation's
+  * tool loop (checkpoint-stable across suspension and crash resume); the
+  * ctx layer folds it with the agent entry's seq into the idempotency
+  * key, so two separate calls with identical arguments do not collide
+  * while an at-least-once retry of one call keeps its key (P0.4).
+  */
+  executeExternal?: (def: ToolDef, args: Json, ordinal: number) => Promise<unknown>;
 }
 /** One serving target of a phase: the primary or a failover fallback. */
 interface PhaseTarget {

package/dist/index.js

@@ -10402,7 +10402,7 @@ async function executeToolCall(options) {
 	try {
 		let value;
 		if (def.executor === "inprocess") value = await def.execute(validation.value, runtime.contextFor(call.name));
-		else if (runtime.executeExternal !== void 0) value = await runtime.executeExternal(def, validation.value);
+		else if (runtime.executeExternal !== void 0) value = await runtime.executeExternal(def, validation.value, options.ordinal);
 		else return finish({ error: `tool '${call.name}' declares executor '${def.executor}' but no executor is registered` }, "error");
 		const serialized = toJournalValue(value === void 0 ? null : value, `tool '${call.name}'`);
 		options.retryCounts.delete(call.name);
@@ -10829,6 +10829,7 @@ async function runAgent(options) {
 				runtime,
 				retryCounts: modelRetryCounts,
 				maxModelRetries: options.modelRetryAttempts ?? 2,
+				ordinal: toolCallsUsed,
 				...events === void 0 ? {} : { events },
 				...gateAudit === void 0 ? {} : { audit: gateAudit },
 				now
@@ -13170,15 +13171,30 @@ function setLongTimeout(onDue, dueAtMs, now = Date.now) {
 */
 /**
 * Derives the idempotency key for one isolated tool dispatch. The key is
-* a pure function of the run, the tool name, and the JCS-canonical
-* arguments, so the same logical call always yields the same key
-* (byte-identical reruns dedupe) and distinct calls never collide. The
-* key never enters run identity; it exists only for the provider's own
-* side-effect deduplication.
+* a pure function of the run, the LOGICAL INVOCATION (the seq of the
+* containing agent's journal entry plus that call's ordinal within the
+* agent's tool loop), the tool name, and the JCS-canonical arguments.
+*
+* The logical-invocation component is what makes the key both stable and
+* distinguishing (v1.59.x review P0.4): the agent-entry seq and the
+* per-agent tool-call ordinal are journal- and checkpoint-stable, so a
+* crash-and-resume re-dispatch of the SAME logical call (the at-least-
+* once window between execution and the turn checkpoint) reuses the same
+* dispatch entry and the restored ordinal, and therefore the same key;
+* while two SEPARATE calls in one run, even with byte-identical
+* arguments, occupy different ordinals and never collide. Without it two
+* intended effects sharing arguments would fold into one under external
+* deduplication.
+*
+* The key never enters run identity (it is absent from every content key
+* and toolset hash); it exists only for the provider's own side-effect
+* deduplication.
 */
-function deriveExecIdempotencyKey(runId, tool, args) {
+function deriveExecIdempotencyKey(runId, agentSeq, ordinal, tool, args) {
 	const canonical = jcsSerialize({
 		runId,
+		agentSeq,
+		ordinal,
 		tool,
 		args
 	});
@@ -13980,7 +13996,8 @@ function createCtx(internals, rootWorkflow) {
 			};
 			if (internals.executors !== void 0) {
 				const executors = internals.executors;
-				toolRuntime.executeExternal = async (def, args) => {
+				const agentSeq = running.seq;
+				toolRuntime.executeExternal = async (def, args, ordinal) => {
 					const tag = def.executor;
 					const provider = executors[tag];
 					if (provider === void 0) throw new ConfigError(`no executor registered for '${def.executor}'; register one via createEngine({ executors }) (https://docs.rulvar.com/guide/isolated-executor)`);
@@ -13994,7 +14011,7 @@ function createCtx(internals, rootWorkflow) {
 							runId: internals.runId,
 							spanId: toolSpanId,
 							agentType,
-							idempotencyKey: deriveExecIdempotencyKey(internals.runId, def.name, args),
+							idempotencyKey: deriveExecIdempotencyKey(internals.runId, agentSeq, ordinal, def.name, args),
 							signal: toolSignal,
 							log: (level, msg, data) => internals.events.emit(data === void 0 ? {
 								type: "log",

package/package.json

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