@tangle-network/agent-runtime 0.107.5 → 0.108.0

package/dist/{supervisor-DTKhF-RV.js → supervisor-B2LzaWRb.js}

@@ -2356,7 +2356,61 @@ function createScope(args) {
 	let meterSeq = 0;
 	const now = args.now ?? Date.now;
 	const unclaimedWaits = new Map((args.resumeFrom?.waits ?? []).map((w) => [w.label, w]));
+	const keyed = /* @__PURE__ */ new Map();
+	for (const [key, prior] of args.resumeFrom?.keys ?? []) if (prior.state === "completed" && prior.settled?.kind === "done") keyed.set(key, {
+		state: "done",
+		id: prior.id,
+		settled: prior.settled
+	});
+	else if (prior.state === "down" && prior.settled?.kind === "down") keyed.set(key, {
+		state: "down",
+		id: prior.id,
+		reason: prior.settled.reason
+	});
+	else keyed.set(key, {
+		state: "in-doubt",
+		id: prior.id
+	});
+	/** Fold a keyed child's terminal settlement back into the registry, so a later spawn with the
+	*  same key resolves to it (done → committed result; down → explicit retry). */
+	const recordKeyedSettlement = (key, settled) => {
+		if (settled.kind === "done") keyed.set(key, {
+			state: "done",
+			id: settled.handle.id,
+			settled
+		});
+		else keyed.set(key, {
+			state: "down",
+			id: settled.handle.id,
+			reason: settled.reason
+		});
+	};
 	function spawn(agent, task, opts) {
+		let prior;
+		if (opts.key !== void 0) {
+			const existing = keyed.get(opts.key);
+			if (existing?.state === "live") return {
+				ok: false,
+				reason: "duplicate-key"
+			};
+			if (existing?.state === "done") return {
+				ok: true,
+				handle: existing.settled.handle,
+				prior: {
+					state: "completed",
+					settled: existing.settled
+				}
+			};
+			if (existing?.state === "down") prior = {
+				state: "retried",
+				priorId: existing.id,
+				reason: existing.reason
+			};
+			else if (existing?.state === "in-doubt") prior = {
+				state: "lost",
+				priorId: existing.id
+			};
+		}
 		if (args.maxDepth !== void 0 && args.depth >= args.maxDepth) return {
 			ok: false,
 			reason: "depth-exceeded"
@@ -2401,6 +2455,7 @@ function createScope(args) {
 				runtime: executor.runtime,
 				budget: opts.budget,
 				label: opts.label,
+				...opts.key !== void 0 ? { key: opts.key } : {},
 				spent: zeroSpend(),
 				settled: void 0,
 				delivered: false,
@@ -2412,11 +2467,16 @@ function createScope(args) {
 				...executor.traceSource ? { readTraceSource: executor.traceSource.bind(executor) } : {}
 			};
 			children.set(id, live);
+			if (opts.key !== void 0) keyed.set(opts.key, {
+				state: "live",
+				id
+			});
 			args.journal.appendEvent(args.root, {
 				kind: "spawned",
 				id,
 				parent: args.parentId,
 				label: opts.label,
+				...opts.key !== void 0 ? { key: opts.key } : {},
 				budget: opts.budget,
 				runtime: executor.runtime,
 				seq: ordinal,
@@ -2446,7 +2506,8 @@ function createScope(args) {
 			});
 			return {
 				ok: true,
-				handle
+				handle,
+				...prior ? { prior } : {}
 			};
 		} catch (err) {
 			args.pool.reconcile(reservation.ticket, zeroSpend());
@@ -2465,7 +2526,9 @@ function createScope(args) {
 			const seq = cursorSeq++;
 			const settlement = chosen.resolved;
 			if (!settlement) throw new ValidationError(`scope.next: child '${chosen.id}' won the settle race without a resolved value`);
-			return finalizeSettlement(chosen, settlement, seq, args, now);
+			const delivered = await finalizeSettlement(chosen, settlement, seq, args, now);
+			if (chosen.key !== void 0) recordKeyedSettlement(chosen.key, delivered);
+			return delivered;
 		}
 	}
 	async function nextResolved() {
@@ -2476,7 +2539,9 @@ function createScope(args) {
 			const settlement = await pick.settled;
 			if (pick.delivered) continue;
 			pick.delivered = true;
-			return finalizeSettlement(pick, settlement, cursorSeq++, args, now);
+			const delivered = await finalizeSettlement(pick, settlement, cursorSeq++, args, now);
+			if (pick.key !== void 0) recordKeyedSettlement(pick.key, delivered);
+			return delivered;
 		}
 	}
 	function send(nodeId, msg) {
@@ -2679,7 +2744,9 @@ function createScope(args) {
 	const resume = args.resumeFrom ? {
 		settled: args.resumeFrom.settled,
 		view: args.resumeFrom.view,
-		waits: args.resumeFrom.waits
+		waits: args.resumeFrom.waits,
+		keys: args.resumeFrom.keys,
+		priorSpend: args.resumeFrom.priorSpend
 	} : void 0;
 	return {
 		spawn,
@@ -3506,6 +3573,108 @@ function createBudgetPool(root, now = Date.now) {
 	};
 }
 //#endregion
+//#region src/runtime/supervise/finalizer.ts
+/**
+* `SupervisorFinalizer` — the pluggable last step of a driver run: how the settled-worker ledger
+* becomes the run's output. `bestDelivered` (the default) returns the single highest-scoring
+* DELIVERED child's output; `collectDelivered` returns every verified distinct output with its
+* provenance — the shape a panel of disagreeing evaluators, a Pareto set, or a competing-hypotheses
+* record needs. A custom finalizer plugs in through `DriverAgentOptions.finalizer` /
+* `SuperviseOptions.finalizer`.
+*
+* THE INVARIANT the seam enforces, not merely documents: a finalizer operates on structurally
+* DELIVERED outputs only — children that settled `done` AND passed their completion oracle
+* (`valid === true`). `runFinalizer` materializes exactly those into `ctx.delivered`, and the
+* `ctx.blobs` reader it hands over refuses any `outRef` that is not a delivered child's result
+* (fail loud). An undelivered or invalid child is visible in `ctx.allSettled` as METADATA — a
+* finalizer can record the disagreement — but its prose is unreachable and it can never become
+* (or be folded into) the output. Returning `undefined` means "nothing deliverable": the
+* supervisor types it a no-winner, never a best-effort coercion.
+*
+* @experimental
+*/
+/**
+* The tree that describes the WHOLE run: this process's live nodes plus, on a resumed run, the
+* committed nodes of the prior process(es). Node ids are assigned by the journal and unique across
+* processes, so the union needs no reconciliation. `inFlight`/`waiting` stay the LIVE counts — a
+* prior process's in-flight node died with it and is not in flight now.
+*
+* Without this, a resumed run reports spend for work whose nodes are missing from its own tree.
+* On a run that never resumed there is nothing to merge and the live view is returned unchanged.
+*/
+function runTree(scope) {
+	const live = scope.view;
+	const prior = scope.resume?.view;
+	if (prior === void 0) return live;
+	const liveIds = new Set(live.nodes.map((n) => n.id));
+	const carried = prior.nodes.filter((n) => !liveIds.has(n.id));
+	if (carried.length === 0) return live;
+	return {
+		...live,
+		nodes: [...carried, ...live.nodes]
+	};
+}
+/** The single argmax both the default finalizer and `finalizeBestDelivered` share: highest
+*  score wins, missing scores count 0, ties keep the earliest ledger entry. */
+function pickBestDelivered(delivered) {
+	let best;
+	for (const w of delivered) if (best === void 0 || (w.score ?? 0) > (best.score ?? 0)) best = w;
+	return best;
+}
+/** Keep-best under the completion oracle — the DEFAULT finalizer and the exact behavior every
+*  existing caller had: the highest-scoring delivered child's output, `undefined` when nothing
+*  delivered (or the best delivered child carries no artifact). */
+const bestDelivered = (ctx) => pickBestDelivered(ctx.delivered)?.out;
+/**
+* Every verified distinct output, highest score first — the shape for competing hypotheses, a
+* Pareto front, or a recorded evaluator split (three judges 2:1 → both outputs survive, with
+* provenance, instead of the minority report being erased). Distinct by `outRef` (content
+* address), so identical outputs collapse to one entry. `undefined` when nothing delivered —
+* an empty collection is a no-winner, not a winner wrapping `[]`.
+*/
+const collectDelivered = (ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	const distinct = [...ctx.delivered].sort((a, b) => (b.score ?? 0) - (a.score ?? 0)).filter((w) => {
+		if (w.outRef === void 0 || seen.has(w.outRef)) return false;
+		seen.add(w.outRef);
+		return true;
+	}).map((w) => ({
+		id: w.id,
+		score: w.score,
+		outRef: w.outRef,
+		out: w.out
+	}));
+	return distinct.length > 0 ? distinct : void 0;
+};
+/**
+* Run a finalizer over a settled-worker ledger under the delivered-only invariant: filter the
+* ledger to structurally delivered children, materialize their outputs, and hand the finalizer a
+* blob reader that throws on any ref outside that set. This is the one call site both driver arms
+* (the in-process tool-loop and the MCP-mounted harness) finalize through.
+*/
+async function runFinalizer(finalizer, args) {
+	const deliveredRows = args.settled.filter((w) => w.status === "done" && w.valid === true);
+	const deliveredRefs = /* @__PURE__ */ new Set();
+	for (const w of deliveredRows) if (w.outRef !== void 0) deliveredRefs.add(w.outRef);
+	return finalizer({
+		delivered: await Promise.all(deliveredRows.map(async (w) => ({
+			id: w.id,
+			...w.score !== void 0 ? { score: w.score } : {},
+			...w.outRef !== void 0 ? {
+				outRef: w.outRef,
+				out: await args.blobs.get(w.outRef)
+			} : {}
+		}))),
+		allSettled: args.settled,
+		tree: args.tree,
+		blobs: { get: (outRef) => {
+			if (!deliveredRefs.has(outRef)) throw new ValidationError(`finalizer: outRef '${outRef}' is not a DELIVERED child's result — a finalizer may only operate on outputs that settled done and passed their completion oracle`);
+			return args.blobs.get(outRef);
+		} },
+		budget: args.budget
+	});
+}
+//#endregion
 //#region src/runtime/supervise/supervisor.ts
 /**
 *
@@ -3542,6 +3711,32 @@ function createBudgetPool(root, now = Date.now) {
 *
 * @experimental
 */
+/**
+* The keyed assignments a prior journal proves: every `spawned` event carrying a `key`, resolved
+* against the replayed settlements. A key spawned more than once (a retry chain) resolves to its
+* LATEST attempt — iterate in ordinal order so later spawns overwrite earlier ones. A spawned
+* event with no matching settlement is `in-doubt`: the process died with it in flight.
+*/
+function keyedAssignments(events, settled) {
+	const byId = new Map(settled.map((s) => [s.handle.id, s]));
+	const keys = /* @__PURE__ */ new Map();
+	const spawns = events.filter((ev) => ev.kind === "spawned").sort((a, b) => a.seq - b.seq);
+	for (const ev of spawns) {
+		if (ev.key === void 0) continue;
+		const s = byId.get(ev.id);
+		keys.set(ev.key, s === void 0 ? {
+			id: ev.id,
+			label: ev.label,
+			state: "in-doubt"
+		} : {
+			id: ev.id,
+			label: ev.label,
+			state: s.kind === "done" ? "completed" : "down",
+			settled: s
+		});
+	}
+	return keys;
+}
 /** Highest `seq` among events matching `pred`, or `-1` when none match (so a resumed scope's
 *  first new ordinal/seq is 0 — the same start a fresh scope uses). */
 function maxSeqOf(events, pred) {
@@ -3561,15 +3756,19 @@ function createSupervisor() {
 		const prior = opts.resume === true ? await opts.journal.loadTree(opts.runId) : void 0;
 		const resuming = prior !== void 0 && prior.length > 0;
 		let resumeFrom;
-		if (resuming) resumeFrom = {
-			settled: await replaySpawnTree(opts.journal, opts.blobs, opts.runId),
-			view: materializeTreeView(prior),
-			maxSpawnOrdinal: maxSeqOf(prior, (ev) => ev.kind === "spawned"),
-			maxCursorSeq: maxSeqOf(prior, (ev) => ev.kind === "settled" || ev.kind === "cancelled" || ev.kind === "woken"),
-			maxWaitOrdinal: maxSeqOf(prior, (ev) => ev.kind === "waiting"),
-			waits: pendingWaits(prior)
-		};
-		else {
+		if (resuming) {
+			const settled = await replaySpawnTree(opts.journal, opts.blobs, opts.runId);
+			resumeFrom = {
+				settled,
+				view: materializeTreeView(prior),
+				maxSpawnOrdinal: maxSeqOf(prior, (ev) => ev.kind === "spawned"),
+				maxCursorSeq: maxSeqOf(prior, (ev) => ev.kind === "settled" || ev.kind === "cancelled" || ev.kind === "woken"),
+				maxWaitOrdinal: maxSeqOf(prior, (ev) => ev.kind === "waiting"),
+				waits: pendingWaits(prior),
+				keys: keyedAssignments(prior, settled),
+				priorSpend: sumSpendFromEvents(prior)
+			};
+		} else {
 			await opts.journal.beginTree(opts.runId, new Date(now()).toISOString());
 			await opts.journal.appendEvent(opts.runId, {
 				kind: "spawned",
@@ -3629,7 +3828,7 @@ function createSupervisor() {
 			if (opts.signal) opts.signal.removeEventListener("abort", onCallerAbort);
 			if (attached) attached.unbind();
 		}
-		const tree = scope.view;
+		const tree = runTree(scope);
 		if (actOutcome.ok) {
 			pool.assertNoOpenTickets();
 			const out = actOutcome.out;
@@ -3766,6 +3965,12 @@ function poolExhausted(pool, opts) {
 async function spentFromJournal(journal, root) {
 	const events = await journal.loadTree(root);
 	if (events === void 0) throw new RuntimeRunStateError(`supervisor: spawn tree '${root}' is missing from the journal after run (corrupted log)`);
+	return sumSpendFromEvents(events);
+}
+/** Per-channel sum over a journaled event list: `settled` = spawned-child work (reconciled);
+*  `metered` = driver inference (re-homed up the tree, so a single root-tree pass already
+*  includes every nested driver's inference). */
+function sumSpendFromEvents(events) {
 	const childWork = {
 		iterations: 0,
 		tokens: {
@@ -3821,6 +4026,6 @@ function isNonEmptySpend(s) {
 	return s.iterations > 0 || s.tokens.input > 0 || s.tokens.output > 0 || s.usd > 0 || s.ms > 0;
 }
 //#endregion
-export { removeWorktree as A, routerToolLoop as C, runWorktreeHarness as D, runWorktreeChecks as E, parseCodexTokenUsage as M, runLocalHarness as N, captureWorktreeDiff as O, CodexExecutionDiagnosticError as P, routerChatWithUsage as S, runSettledCommand as T, defineRuntimeHooks as _, createScope as a, routerBrain as b, isWaitOutcome as c, validateWaitSpec as d, waitUntil as f, composeRuntimeHooks as g, readWorkerProgress as h, withDriverExecutor as i, harnessInvocation as j, createWorktree as k, pollFor as l, createActivityLog as m, createBudgetPool as n, settledToIteration as o, DEFAULT_STALL_AFTER_MS as p, spendFromUsageEvents as r, createWaitProbes as s, createSupervisor as t, timerAt as u, notifyRuntimeDecisionPoint as v, runBrainLoop as w, routerChatWithTools as x, notifyRuntimeHookEvent as y };
+export { runSettledCommand as A, notifyRuntimeDecisionPoint as C, routerChatWithUsage as D, routerChatWithTools as E, removeWorktree as F, harnessInvocation as I, parseCodexTokenUsage as L, runWorktreeHarness as M, captureWorktreeDiff as N, routerToolLoop as O, createWorktree as P, runLocalHarness as R, defineRuntimeHooks as S, routerBrain as T, waitUntil as _, runFinalizer as a, readWorkerProgress as b, spendFromUsageEvents as c, settledToIteration as d, createWaitProbes as f, validateWaitSpec as g, timerAt as h, pickBestDelivered as i, runWorktreeChecks as j, runBrainLoop as k, withDriverExecutor as l, pollFor as m, bestDelivered as n, runTree as o, isWaitOutcome as p, collectDelivered as r, createBudgetPool as s, createSupervisor as t, createScope as u, DEFAULT_STALL_AFTER_MS as v, notifyRuntimeHookEvent as w, composeRuntimeHooks as x, createActivityLog as y, CodexExecutionDiagnosticError as z };
 
-//# sourceMappingURL=supervisor-DTKhF-RV.js.map
+//# sourceMappingURL=supervisor-B2LzaWRb.js.map