@tangle-network/agent-runtime 0.274.0 → 0.279.0

package/dist/{coordination-driver-B2GTcMvx.js → coordination-driver-BBL_OgRw.js}

@@ -1,4 +1,4 @@
-import { Ai as readCommittedJsonLines, Bi as providerAttemptEvidence, E as failedItems, Ea as unmeteredSpend, En as isTerminalNodeStatus, It as FileResultBlobStore, Lt as FileSpawnJournal, M as withDriverExecutor, Pt as createRouterTranscript, Qi as detachedFrozen, Qt as workerTraceAnalysisStore, Rt as InMemoryResultBlobStore, Tn as isLiveNodeStatus, Zt as parseWorkerToolTraceArtifact, _ as CheckUnavailableError, at as scopeRetainedOwnerResourceReader, ba as promptCacheTokenClasses, c as runTree, gn as createInbox, ha as chargedTokens, i as bestDelivered, ja as withBudgetResources, ji as writeAllBytes, ka as addResourceSpend, ki as prepareJsonlAppend, kt as createExecutorRegistry, o as pickBestDelivered, qn as runBrainLoop, s as runFinalizer, tn as assertValidBudget, ur as errMessage, ut as resolveSpawnResourcePaths, wr as resolveRedactor, x as checkVerdictOf, xn as createPeerMailbox, z as meterRuntimeOwnedProviderAttempt, zt as InMemorySpawnJournal } from "./supervisor-C50SI_Ww.js";
+import { $t as parseWorkerToolTraceArtifact, Ai as readCommittedJsonLines, Bi as providerAttemptEvidence, Bt as InMemoryResultBlobStore, Cn as createPeerMailbox, Dn as isLiveNodeStatus, E as failedItems, Ea as unmeteredSpend, Er as resolveRedactor, It as createRouterTranscript, M as withDriverExecutor, On as isTerminalNodeStatus, Qi as detachedFrozen, Rt as FileResultBlobStore, Vt as InMemorySpawnJournal, Yn as runBrainLoop, _ as CheckUnavailableError, ba as promptCacheTokenClasses, c as runTree, en as workerTraceAnalysisStore, fr as errMessage, ft as resolveSpawnResourcePaths, ha as chargedTokens, i as bestDelivered, ja as withBudgetResources, ji as writeAllBytes, jt as createExecutorRegistry, ka as addResourceSpend, ki as prepareJsonlAppend, o as pickBestDelivered, ot as scopeRetainedOwnerResourceReader, rn as assertValidBudget, s as runFinalizer, vn as createInbox, x as checkVerdictOf, z as meterRuntimeOwnedProviderAttempt, zt as FileSpawnJournal } from "./supervisor-DtlPj9me.js";
 import { f as RuntimeRunStateError, m as ValidationError } from "./errors-DodWX-cb.js";
 import { A as writeWorkerCancellation, M as writeWorkerSteerAcknowledgement, b as workerCancellationsDir, c as readWorkerCancelRequests, d as readWorkerSteerRequests, k as writeRunCancellation, l as readWorkerCancellation, o as readRunCancelRequest, r as claimWorkerSteerDelivery, s as readRunCancellation, u as readWorkerSteerAcknowledgement } from "./run-layout-vwd4SwX_.js";
 import { agentProfileSchema, canonicalCandidateDigest } from "@tangle-network/agent-interface";
@@ -1229,9 +1229,9 @@ function createCoordinationToolsForManager(opts, lifetime) {
 		}
 		return true;
 	};
-	const drainSettlement = async () => {
+	const drainSettlement = async (source = "next") => {
 		if (!pendingSettlement) {
-			const settled = await opts.scope.next();
+			const settled = await (source === "next" ? opts.scope.next() : opts.scope.nextResolved());
 			if (!settled) return false;
 			const worker = projectSettled(settled);
 			const run = analystRuns.get(settled.handle.id);
@@ -1862,7 +1862,7 @@ function createCoordinationToolsForManager(opts, lifetime) {
 	const tools = [
 		{
 			name: "spawn_worker",
-			description: "Start a worker the driver will drive. `profile` is the worker or another driver; `task` is what it should do. Reserves budget from the conserved pool and fails closed. Pass an optional `budget` (per-field) to give a hard sub-task more than the default — it merges over the per-worker default; the conserved pool is still the hard fence. When every worker slot is busy, or the pool cannot cover the budget until your running workers return what they hold, the worker is admitted with `status: \"queued\"` and starts on its own when a slot and its budget free — it is never refused for concurrency, so spawn all the work you want done and await_event for the results. A queued worker whose budget never frees settles down as budget-exhausted. Pass a `key` naming the assignment to make it run-once ACROSS restarts: a key that already completed returns the finished result (`resumed: \"completed\"` — no work re-runs, nothing is spent), a key whose prior attempt failed (`down`) spawns fresh and says so (`resumed: \"retried\"`), and a key the process died with IN FLIGHT retries under the same key when the executor provably died with the process (an inline worker — the same `resumed: \"retried\"`, naming the interruption). A key with no terminal receipt whose execution may still exist elsewhere (sandbox, CLI bridge, router) is refused (`error: \"in-doubt\"`) until its exact prior execution is recovered. A key still running is refused (`error: \"duplicate-key\"`). Returns `freeSlots`: how many MORE workers start at once (`null` = no slot bound), and `queued`: how many of your workers wait for a slot. Parallel workers finish the run sooner than one at a time." + (profileTable === void 0 ? "" : " This run has a profiles table: pass `profile` as one of the table's names to run that exact profile, or write a new profile under a name the table does not hold."),
+			description: "Start a worker the driver will drive. `profile` is the worker or another driver; `task` is what it should do. Reserves budget from the conserved pool and fails closed. Pass an optional `budget` (per-field) to give a sub-task more or less than the default — it merges over the per-worker default; the conserved pool is still the hard fence. Each worker reserves its whole budget when it starts, so the pool divided by the per-worker budget is how many run at once: to run a wide team at once, give each worker less. When every worker slot is busy, or the pool cannot cover the budget until your running workers return what they hold, the worker is admitted with `status: \"queued\"` and starts on its own when a slot and its budget free — it is never refused for concurrency, so spawn all the work you want done and await_event for the results. A queued worker whose budget never frees settles down as budget-exhausted. Pass a `key` naming the assignment to make it run-once ACROSS restarts: a key that already completed returns the finished result (`resumed: \"completed\"` — no work re-runs, nothing is spent), a key whose prior attempt failed (`down`) spawns fresh and says so (`resumed: \"retried\"`), and a key the process died with IN FLIGHT retries under the same key when the executor provably died with the process (an inline worker — the same `resumed: \"retried\"`, naming the interruption). A key with no terminal receipt whose execution may still exist elsewhere (sandbox, CLI bridge, router) is refused (`error: \"in-doubt\"`) until its exact prior execution is recovered. A key still running is refused (`error: \"duplicate-key\"`). Returns `freeSlots`: how many MORE workers start at once (`null` = no slot bound), and `queued`: how many of your workers wait for a slot. Parallel workers finish the run sooner than one at a time." + (profileTable === void 0 ? "" : " This run has a profiles table: pass `profile` as one of the table's names to run that exact profile, or write a new profile under a name the table does not hold."),
 			inputSchema: {
 				type: "object",
 				properties: {
@@ -2230,7 +2230,7 @@ function createCoordinationToolsForManager(opts, lifetime) {
 		},
 		{
 			name: "await_event",
-			description: "Wait for and pull the next message a worker, sub-driver, or analyst sent up — the unified inbox. Read a settled artifact with the returned `outputRead` call; the receipt carries its reference, not its bytes. An event is one of: a settled worker output ('settled'), a question needing your answer ('question', from ask_parent / the worker's ask-user), or a trace-analyst finding ('finding', from analyze-on-settle). Pass kinds:['settled'] for just the next finished worker; omit `kinds` to also receive questions and findings. Returns { idle: true } when nothing is queued and no workers are live. If a worker is still running when the wait elapses, returns { pending: true, live: [...] } (the workers still in flight) instead of blocking indefinitely — call await_event again to keep waiting; the settlement is not lost. Every reply carries `freeSlots`: how many more workers you can start right now (`null` = uncapped). A settled worker frees its slot, so `freeSlots > 0` means capacity is sitting idle — spawn into it before waiting again. Each event carries `eventSeq`; pass the ones you have processed in `acknowledge` on a later call. An event delivered to a turn that ends in failure is named again when you are re-entered, until it is acknowledged.",
+			description: "Wait for and pull the next message a worker, sub-driver, or analyst sent up — the unified inbox. Read a settled artifact with the returned `outputRead` call; the receipt carries its reference, not its bytes. An event is one of: a settled worker output ('settled'), a question needing your answer ('question', from ask_parent / the worker's ask-user), or a trace-analyst finding ('finding', from analyze-on-settle). Pass kinds:['settled'] for just the next finished worker; omit `kinds` to also receive questions and findings. Returns { idle: true } when nothing is queued and no workers are live. If a worker is still running when the wait elapses, returns { pending: true, live: [...] } (the workers still in flight) instead of blocking indefinitely — call await_event again to keep waiting; the settlement is not lost. Every reply carries `freeSlots`: how many more workers you can start right now (`null` = uncapped). A settled worker frees its slot, so `freeSlots > 0` means capacity is sitting idle — spawn into it before waiting again. Each event carries `eventSeq`; pass the ones you have processed in `acknowledge` on a later call. An event delivered to a turn that ends in failure is named again when you are re-entered, until it is acknowledged. Pass `max` above 1 to read a whole team at once: the reply is `{ events: [...] }` with the first event it waited for plus every other event already waiting, up to `max`, so a lead of hundreds of workers reads their receipts in a few turns instead of one each.",
 			inputSchema: {
 				type: "object",
 				properties: {
@@ -2249,11 +2249,18 @@ function createCoordinationToolsForManager(opts, lifetime) {
 							minimum: 0
 						},
 						description: "The eventSeq of each earlier event you have now processed."
+					},
+					max: {
+						type: "integer",
+						minimum: 1,
+						description: "Most events to return in one reply. Omit or 1 for one event; above 1 returns `{ events }`."
 					}
 				}
 			},
 			handler: async (raw) => {
 				const args = raw === void 0 ? {} : obj(raw);
+				const max = args.max === void 0 ? 1 : args.max;
+				if (typeof max !== "number" || !Number.isSafeInteger(max) || max < 1) throw new Error("coordination tools: \"max\" must be a positive integer");
 				const k = args.kinds;
 				const kinds = Array.isArray(k) ? k.filter(isAwaitableEventKind) : void 0;
 				if (Array.isArray(args.acknowledge)) {
@@ -2271,26 +2278,64 @@ function createCoordinationToolsForManager(opts, lifetime) {
 						eventSeq: record.seq
 					};
 				};
-				let ev = bus.pullRecord(kinds);
-				if (ev) return {
-					...deliver(ev),
-					freeSlots: freeWorkerSlots()
-				};
-				const raced = await raceDrainWithTimeout(ensureDrain());
-				if (raced === void 0) return {
-					pending: true,
-					live: liveSnapshot(),
-					freeSlots: freeWorkerSlots()
-				};
-				ev = bus.pullRecord(kinds);
-				if (!ev) return {
-					idle: !raced.drained,
-					freeSlots: freeWorkerSlots()
-				};
-				return {
-					...deliver(ev),
-					freeSlots: freeWorkerSlots()
-				};
+				if (max > 1) {
+					const fenceAt = awaitTimeoutMs > 0 ? Date.now() + awaitTimeoutMs / 2 : Infinity;
+					if (!inFlightDrain) {
+						inFlightDrain = (async () => {
+							let drained = false;
+							while (bus.pending(kinds) < max && Date.now() < fenceAt) {
+								if (!await drainSettlement("nextResolved")) break;
+								drained = true;
+							}
+							return drained;
+						})().finally(() => {
+							inFlightDrain = null;
+						});
+						await inFlightDrain;
+					}
+					const events = [];
+					const takeQueued = () => {
+						for (let next = bus.pullRecord(kinds); next; next = bus.pullRecord(kinds)) {
+							events.push(deliver(next));
+							if (events.length >= max) return;
+						}
+					};
+					takeQueued();
+					if (events.length === 0) {
+						const first = await pullOne();
+						if (!("eventSeq" in first)) return first;
+						const { freeSlots: _slots, ...head } = first;
+						events.push(head);
+						takeQueued();
+					}
+					return {
+						events,
+						freeSlots: freeWorkerSlots()
+					};
+				}
+				return pullOne();
+				async function pullOne() {
+					let ev = bus.pullRecord(kinds);
+					if (ev) return {
+						...deliver(ev),
+						freeSlots: freeWorkerSlots()
+					};
+					const raced = await raceDrainWithTimeout(ensureDrain());
+					if (raced === void 0) return {
+						pending: true,
+						live: liveSnapshot(),
+						freeSlots: freeWorkerSlots()
+					};
+					ev = bus.pullRecord(kinds);
+					if (!ev) return {
+						idle: !raced.drained,
+						freeSlots: freeWorkerSlots()
+					};
+					return {
+						...deliver(ev),
+						freeSlots: freeWorkerSlots()
+					};
+				}
 			}
 		},
 		{
@@ -3733,6 +3778,25 @@ function poolStarved(scope, perWorker, preserveOwnerTurns = false) {
 	const resourceStarved = Object.entries(b.resources ?? {}).some(([name, value]) => !value.known || value.remaining <= 0 || !preserveOwnerTurns && value.remaining < (perWorker.resources?.[name]?.limit ?? 0));
 	return tokenStarved || iterationStarved || usdStarved || resourceStarved;
 }
+/** The number of driver turns a manager whose spend Runtime cannot measure may take when no
+*  deadline or dollar cap bounds it. */
+const UNMETERED_DRIVER_TURNS = 16;
+/**
+* Safety guards for a manager's own turns when no deadline bounds them.
+*
+* `poolStarved` lets a manager keep taking turns while its workers run, because those workers hold
+* the pool its turns would otherwise be refused from. With no turn cap and no deadline, a manager
+* waiting on a worker that never settles would take a metered turn per `await_event` fence forever.
+* Money bounds that: a manager that has overdrawn its pool by as much again as the whole pool stops.
+* A brain that reports no usage cannot be bounded by money, so without a deadline or dollar cap it
+* keeps the historical 16-turn bound. A caller's explicit `maxTurns` or a deadline replaces both.
+*/
+function ownTurnsUnbounded(scope, poolTokens, turns, maxTurns) {
+	const b = scope.budget;
+	if (maxTurns !== void 0 || b.deadlineMs > 0) return false;
+	if (poolTokens > 0 && b.tokensLeft < -poolTokens) return true;
+	return !b.tokensKnown && !b.usdCapped && turns > UNMETERED_DRIVER_TURNS;
+}
 /** The absolute wall-clock deadline (when the root set one) has passed. */
 function deadlinePassed(scope, now) {
 	const b = scope.budget;
@@ -4121,7 +4185,7 @@ function driverAgent(opts) {
 		reserved.add(t.name);
 	}
 	if (opts.maxTurns !== void 0 && opts.maxTurns < 0) throw new ValidationError("driverAgent: maxTurns must be >= 0 (0 lifts the turn cap; bounds become the conserved pool + deadline + abort)");
-	const maxTurns = opts.maxTurns ?? 16;
+	const maxTurns = opts.maxTurns ?? 0;
 	const now = opts.now ?? Date.now;
 	const inbox = opts.inbox ?? createInbox();
 	const transcript = opts.transcript ?? createRouterTranscript();
@@ -4222,6 +4286,8 @@ function driverAgent(opts) {
 			});
 			const system = typeof opts.systemPrompt === "function" ? opts.systemPrompt(task) : opts.systemPrompt;
 			const tracker = opts.stopRule ? createProgressTracker({ now }) : void 0;
+			const poolTokens = scope.budget.tokensLeft + scope.budget.reservedTokens;
+			let driverTurns = 0;
 			let progressStopReason;
 			let driverTurn = 0;
 			let driverCall = 0;
@@ -4355,6 +4421,7 @@ function driverAgent(opts) {
 				maxTurns,
 				hooks: {
 					beforeTurn: async (_turn, messages) => {
+						driverTurns += 1;
 						await steerAcknowledger?.pass("turn");
 						acknowledger?.pass("turn");
 						const pending = inbox.drain();
@@ -4365,7 +4432,7 @@ function driverAgent(opts) {
 						transcript.observe(messages);
 					},
 					stopBefore: () => {
-						if (coord.isStopped() || scope.signal.aborted || poolStarved(scope, opts.perWorker, opts.preserveOwnerTurns) || deadlinePassed(scope, now)) return true;
+						if (coord.isStopped() || scope.signal.aborted || poolStarved(scope, opts.perWorker, opts.preserveOwnerTurns) || deadlinePassed(scope, now) || ownTurnsUnbounded(scope, poolTokens, driverTurns, opts.maxTurns)) return true;
 						if (!opts.stopRule || !tracker) return false;
 						const decision = progressStop(tracker, opts.stopRule, coord, scope, now, opts.stallAfterMs);
 						if (!decision.stop) return false;
@@ -4496,4 +4563,4 @@ function safeJson(v) {
 //#endregion
 export { createCoordinationTools as A, applyRunCancellation as C, analystToolGroupNames as D, DEFAULT_AWAIT_EVENT_TIMEOUT_MS as E, questionEscalationTargets as F, createEventBus as I, defaultToolDetectors as L, downMessageRefusalReasons as M, normalizeAnalyzeOnSettle as N, canonicalFindingEvent as O, parseAuthoredAnalystDefinition as P, watchTrace as R, foldCoordinationRecords as S, ANALYST_DEFINITION_BOUNDS as T, renderAnytimeTable as _, allOf as a, withRunContext as b, createProgressTracker as c, progressStop as d, sampleFromSettled as f, plateauLength as g, bestSoFar as h, finalizeBestDelivered as i, createCoordinationToolsForManager as j, coordinationVerbNames as k, noProgressFor as l, areaUnderCurve as m, createSteerAcknowledger as n, allWorkersStalled as o, anytimeReport as p, driverAgent as r, anyOf as s, createCancelAcknowledger as t, plateau as u, createFileRunContext as v, watchRunCancellation as w, FileCoordinationLog as x, createInMemoryRunContext as y };
 
-//# sourceMappingURL=coordination-driver-B2GTcMvx.js.map
+//# sourceMappingURL=coordination-driver-BBL_OgRw.js.map