@qilin-agent/agent 0.0.0-stage → 3.1.3

package/lib/index.js

@@ -0,0 +1,700 @@
+import { Service, getTraceable, symbols } from "@qilin-agent/kylin";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { isPromise } from "node:util/types";
+import { scopeTarget } from "@qilin-agent/scope";
+import { boundContextSummary, createUserMessage } from "@qilin-agent/llm";
+//#region lib/types/archive-admission.js
+/**
+* The `turn` family of the Workspace registry's archive admission: whether a
+* Session's own Agent is inside a turn, and its cancel when the Session is
+* archived with its work. Installed by the registry's constructor, so it
+* answers for every Agent the registry publishes.
+*
+* @module @qilin-agent/agent
+*/
+/**
+* Answer `workspace/session-activity` with the `turn` family while the
+* Session's Agent is running (a turn waiting for an approval or an answer
+* included), and `workspace/session-stop` by cancelling that turn the way
+* the user's own stop does — `agent.cancel({ kind: 'user' })`, but without
+* the stop button's `keepInbox`, so queued input is discarded with a logged
+* inbox splice instead of waking the archived Session later. Nothing is
+* awaited to settlement. Both listeners live as long as `ctx`'s fiber.
+* @param ctx - the registry's registration context.
+* @param lookup - the registry's live-Agent lookup by Session id.
+*/
+function installTurnArchiveAdmission(ctx, lookup) {
+	ctx.on("workspace/session-activity", async ({ sessionId }, next) => {
+		const running = lookup(sessionId)?.status === "running";
+		const rest = await next();
+		if (!running) return rest;
+		return [{ kind: "turn" }, ...rest];
+	});
+	ctx.on("workspace/session-stop", ({ sessionId }) => {
+		const agent = lookup(sessionId);
+		if (agent?.status === "running") agent.cancel({ kind: "user" });
+	});
+}
+//#endregion
+//#region lib/types/consumed-work.js
+/**
+* How one agent log accounts for the work it consumed.
+*
+* The turn and step vocabulary alone cannot answer this. A turn that stops
+* before its first step leaves a `turn/end` shaped exactly like the balanced
+* no-op turns a rejection or an empty claim produces, so reading turns in
+* isolation either credits cut-short work as finished or convicts every no-op.
+* The missing fact is the inbox's own record: {@link Inbox} logs each mutation
+* with `removedCount` and marks a cancellation `outcome: 'canceled'`, which
+* separates a turn claiming its input from work being dropped unrun.
+*
+* @module @qilin-agent/agent/consumed-work
+*/
+/**
+* Whether a turn that consumed input but never reached a step ends in a way
+* that accounts for that input. Only a `completed` end does not: it had
+* nothing left to run once its claim was rewritten away. A `blocked` end is
+* that input's ending too — the pre-step rejection that produced it discarded
+* the claimed messages, so the work it took will never run.
+* @param reason - the turn's recorded ending.
+* @returns whether the ending accounts for the input the turn took.
+*/
+function accountsForClaim(reason) {
+	switch (reason.kind) {
+		case "completed": return false;
+		case "blocked":
+		case "aborted":
+		case "interrupted":
+		case "error": return true;
+		/* v8 ignore next 5 -- unreachable: `max-tokens` requires a step and short-circuits
+		* before this call; `forked` exists only in constructor seed history, while production
+		* callers fold an operation-owned suffix. `TurnEndReasonMap` is merge-extensible, so a
+		* backend-added variant cannot be listed; an unnameable ending over consumed input must
+		* not read as success. */
+		default: return true;
+	}
+}
+/**
+* Fold one agent log, or an owned suffix of one, into its account of consumed
+* work. Single pass, and every input is the log itself: no caller has to sample
+* live state before cancelling, so a cancellation issued by anyone — the owner's
+* teardown, an ancestor's interrupt, an unloading plugin — reads the same.
+* @param events - the log, or an owned suffix, to fold.
+* @returns the accounting turn when one closed, and whether work was dropped unrun after it.
+*/
+function foldConsumedWork(events) {
+	const stepped = /* @__PURE__ */ new Set();
+	const claimed = /* @__PURE__ */ new Set();
+	let open;
+	let end;
+	let droppedUnrun = false;
+	for (const event of events) switch (event.type) {
+		case "turn/start":
+			open = event.data.turn;
+			break;
+		case "step/start":
+			stepped.add(event.data.turn);
+			break;
+		case "agent/inbox/spliced": {
+			const { removedCount, outcome, inserted } = event.data;
+			if (removedCount === void 0) break;
+			if (outcome === "canceled") droppedUnrun ||= inserted.length === 0;
+			else if (open !== void 0) claimed.add(open);
+			break;
+		}
+		case "turn/end": {
+			const { turn, reason } = event.data;
+			open = void 0;
+			if (stepped.delete(turn) || claimed.delete(turn) && accountsForClaim(reason)) {
+				end = event;
+				droppedUnrun = false;
+			}
+			break;
+		}
+		default: break;
+	}
+	return {
+		...end === void 0 ? {} : { end },
+		droppedUnrun
+	};
+}
+//#endregion
+//#region lib/types/model-selection.js
+/**
+* Agent-scoped model selection shared by runtime entry points.
+* @module @qilin-agent/agent/model-selection
+*/
+function sameRoute(left, right) {
+	return left.provider === right.provider && left.model === right.model;
+}
+function routeLabel(route, other) {
+	return route.provider === other.provider ? route.model : `${route.provider}/${route.model}`;
+}
+function modelSwitchNotice(previous, selected) {
+	const from = routeLabel(previous, selected);
+	const to = routeLabel(selected, previous);
+	return createUserMessage({
+		content: [{
+			type: "text",
+			text: `[model changed: assistant turns above this point were generated by ${from}; the session continues with ${to}]`
+		}],
+		source: {
+			kind: "model-selection",
+			form: "notice",
+			summary: boundContextSummary(`${from} → ${to}`)
+		}
+	});
+}
+/**
+* Couple one mutable selection to Agent-scoped prompt assembly and request routing.
+* Prompt assembly snapshots the selected model before delegating, then applies
+* its provider/model pair and effort to request config so a
+* concurrent switch takes effect on a later step instead of splitting the two
+* surfaces. An absent selected effort clears any inherited effort, restoring
+* the selected model's provider/default behavior.
+*
+* A provider/model change appends a durable user-role notice to the next
+* admitted request. It compares the assembled selection with the latest
+* request header; effort-only changes and empty no-request decisions add no
+* notice. Failure before header persistence repeats the notice on the next
+* request.
+*
+* @param agentCtx - The selected Agent's scoped context.
+* @param selection - Mutable selection owned by the calling entry point.
+* @returns Disposer for all scoped waterfall listeners.
+*/
+function installModelSelection(agentCtx, selection) {
+	const disposeAssembly = agentCtx.on("system-prompt/assemble", async (_assembly, _context, next) => {
+		const selected = selection.current;
+		const assembled = await next();
+		selection.assembled = selected;
+		if (selected === void 0) return assembled;
+		return {
+			...assembled,
+			variables: {
+				...assembled.variables,
+				provider: selected.provider,
+				model: selected.model
+			}
+		};
+	});
+	const disposeRequest = agentCtx.on("agent/request", async (_payload, next) => {
+		const resolved = await next();
+		const selected = selection.assembled;
+		if (selected === void 0) return resolved;
+		const { reasoningEffort: _inheritedEffort, ...withoutInheritedEffort } = resolved;
+		return {
+			...withoutInheritedEffort,
+			provider: selected.provider,
+			model: selected.model,
+			...selected.reasoningEffort === void 0 ? {} : { reasoningEffort: selected.reasoningEffort }
+		};
+	});
+	const disposeNotice = agentCtx.on("agent/pre-step", async ({ agent, messages, signal, step }, next) => {
+		const decision = await next();
+		if (decision.kind === "reject" || signal.aborted) return decision;
+		if (decision.messages.length === 0 && (step === 1 || messages.length > 0)) return decision;
+		const selected = selection.assembled;
+		const previous = agent.session.requestHeader()?.config;
+		if (selected === void 0 || previous === void 0 || sameRoute(selected, previous)) return decision;
+		return {
+			...decision,
+			messages: [...decision.messages, modelSwitchNotice(previous, selected)]
+		};
+	}, { prepend: true });
+	return () => {
+		disposeAssembly();
+		disposeRequest();
+		disposeNotice();
+	};
+}
+//#endregion
+//#region lib/types/dispatch.js
+/**
+* Agent-scoped dispatch and prompt assembly helpers. The fused dispatcher
+* {@link agentEvents} couples the agent subject to its scope carrier, so the
+* scope key and the payload's `agent` cannot diverge; repeat dispatchers (the
+* loop driver) build it once in the agent's constructor and reuse it.
+* @module @qilin-agent/agent/dispatch
+*/
+/**
+* Build the fused scope carrier for one agent subject.
+*
+* The carrier is a stateless routing object. {@link agentEvents} accepts an
+* existing carrier, so callers that dispatch repeatedly for the same agent
+* (the loop driver) build it once in the agent's constructor and reuse it,
+* keeping hot-path dispatches allocation-free.
+* @param agent - the subject agent and scope key.
+* @returns the carrier passed as the event dispatcher `this` value.
+*/
+function agentCarrier(agent) {
+	return scopeTarget(agent, agent);
+}
+/**
+* Build a dispatcher that couples the agent subject to its scope carrier.
+* @param ctx - the context to dispatch through (any context of the app).
+* @param agent - the subject agent; also the scope-carrier key.
+* @param carrier - the scope carrier to dispatch through; defaults to
+* {@link agentCarrier} for the agent. Pass a constructor-built carrier to
+* avoid rebuilding it for every dispatch.
+* @returns the fused dispatcher.
+*/
+function agentEvents(ctx, agent, carrier = agentCarrier(agent)) {
+	const fused = (payload) => ({
+		...payload,
+		agent
+	});
+	return {
+		emit(name, payload) {
+			const args = [
+				carrier,
+				name,
+				fused(payload)
+			];
+			const callbacks = ctx.events.dispatch("emit", args);
+			for (const callback of callbacks) try {
+				const returned = callback(...args);
+				Promise.resolve(returned).catch((error) => {
+					ctx.logger.warn(`agent event "${name}" listener rejected: ${String(error)}`);
+				});
+			} catch (error) {
+				ctx.logger.warn(`agent event "${name}" listener threw: ${String(error)}`);
+			}
+		},
+		async serial(name, payload) {
+			const serial = ctx.serial;
+			return await serial(carrier, name, fused(payload));
+		},
+		waterfall(name, payload, ...rest) {
+			const waterfall = ctx.waterfall;
+			return waterfall(carrier, name, fused(payload), ...rest);
+		}
+	};
+}
+/**
+* Emit one contained agent notification without allocating a retained dispatcher.
+* @param ctx - the context to dispatch through.
+* @param agent - the subject agent and scope key.
+* @param name - the agent-subject event to emit.
+* @param payload - the event's payload fields; `agent` is injected.
+*/
+function emitAgentEvent(ctx, agent, name, payload) {
+	agentEvents(ctx, agent).emit(name, payload);
+}
+/**
+* Build the prompt assembly context with agent and scope set together, so
+* agent-scoped prompt and tool contributions cannot be silently omitted.
+* @param agent - the agent the assembly is for.
+* @param signal - the current turn's explicit control signal, when assembly belongs to a turn.
+* @returns the context to pass to `assemble()`.
+*/
+function assembleContextFor(agent, signal) {
+	return {
+		agent,
+		scope: agent,
+		...signal === void 0 ? {} : { signal }
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Agent service: live registry, factory delegation, and process-local
+* initiator scope. Concrete creation and driving belong to the loop.
+*
+* @module @qilin-agent/agent
+*/
+/** Thrown when create/resume is called before an agent factory is registered. */
+const NO_FACTORY_MESSAGE = "no agent factory registered (load an agent-loop plugin)";
+const NO_INITIATOR_MESSAGE = "no initiating agent is active";
+const DISPOSED_INITIATOR_MESSAGE = "agent initiator scope is disposed";
+/**
+* Agent service (`ctx.agents`): tracks live agents and carries the initiating
+* Agent through one process-local asynchronous driver chain. Agent *creation*
+* is provided by whichever plugin implements the {@link AgentFactory}
+* (`@qilin-agent/agent-loop`), registered via {@link setFactory}.
+*
+* Initiator methods provide same-process causal attribution only. Ambient
+* presence is neither liveness proof nor authorization; subjects and owners
+* remain explicit, as does identity at worker, process, persistence, and wire
+* boundaries. Returned Promise boundaries drain during teardown, except a
+* nested lineage that starts an owning-fiber unload is excluded from its own drain.
+*/
+var AgentRegistry = class extends Service {
+	store = /* @__PURE__ */ new Map();
+	factory;
+	initiators = new AsyncLocalStorage();
+	initiatorRuns = new AsyncLocalStorage();
+	initiatorState = "active";
+	activeInitiatorRuns = 0;
+	initiatorDrain;
+	initiatorDisposal;
+	constructor(ctx) {
+		super(ctx, "agents");
+		ctx.inject(["typert"], (typeCtx) => {
+			typeCtx.typert.lookups.register("agent", {
+				parameter: "agent",
+				wire: "agentId",
+				hostTypeSymbol: "@qilin-agent/agent#Agent",
+				wireTypeSymbol: "@qilin-agent/session/types#SessionId",
+				resolve: (sessionId) => this.get(sessionId)
+			});
+			typeCtx.typert.contexts.registerHost("agent", {
+				wire: "agentId",
+				wireTypeSymbol: "@qilin-agent/session/types#SessionId",
+				resolve: (sessionId) => this.get(sessionId)?.ctx
+			});
+		});
+		ctx.on("internal/status", (fiber) => {
+			if (fiber.state === 5 && this.hasLifecycleAncestor(fiber)) this.closeInitiators();
+		});
+		ctx.effect(function* () {
+			yield () => this.disposeInitiators();
+			yield () => {
+				this.closeInitiators();
+			};
+		}.bind(this), "agents.initiatorLifecycle()");
+		installTurnArchiveAdmission(ctx, (sessionId) => this.get(sessionId));
+	}
+	/**
+	* Read the Agent that initiated the inherited asynchronous driver chain.
+	* Use this optional form for logging, tracing, metrics, or host attribution
+	* that also supports agentless calls. When a parent creates a child, setup
+	* reports the causal parent while the setup callback's Agent parameter
+	* identifies the child.
+	* @returns the inherited Agent, or `undefined` outside an initiator boundary
+	*   and inside an explicit clearing boundary.
+	* @throws when this service instance has been disposed.
+	*/
+	currentInitiator() {
+		this.assertInitiatorsReadable();
+		return this.initiators.getStore();
+	}
+	/**
+	* Read the initiating Agent and fail when no initiator boundary is active.
+	* Use this for private helpers contractually below a driver, or for a
+	* deployment-owned outbound request whose contract forbids agentless calls.
+	* Generic or direct-call paths use optional lookup or explicit request fields.
+	* @returns the inherited Agent.
+	* @throws when no initiator is active or this service instance has been disposed.
+	*/
+	requireInitiator() {
+		const agent = this.currentInitiator();
+		if (agent === void 0) throw new Error(NO_INITIATOR_MESSAGE);
+		return agent;
+	}
+	/**
+	* Run an operation with one exact Agent as its process-local initiator. The
+	* exact synchronous value or Promise returned by the operation is preserved.
+	* Custom drivers and test harnesses wrap their complete returned foreground
+	* lifetime.
+	* A queue or wire receiver may establish this boundary only after validating
+	* explicit identity and resolving the exact live Agent; this method does neither.
+	* Detached work remains owned by the subsystem that starts it.
+	* @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
+	* @param operation - synchronous or asynchronous operation to invoke.
+	* @returns the exact value returned by `operation`.
+	* @throws when the initiator scope is closing/disposed, or when `operation` throws.
+	*/
+	withInitiator(agent, operation) {
+		return this.runWithInitiator(agent, operation);
+	}
+	/**
+	* Run an operation inside a boundary that hides any inherited initiating
+	* Agent. The exact synchronous value or Promise is preserved.
+	* Use this while creating lazy shared timers, queue pumps, pool maintenance,
+	* watchers, or exporters so they do not inherit the first Agent that happens
+	* to initialize them. It clears only initiator attribution, not explicit
+	* fields, and does not own or drain detached resources.
+	* @param operation - synchronous or asynchronous operation to invoke without an initiator.
+	* @returns the exact value returned by `operation`.
+	* @throws when the initiator scope is closing/disposed, or when `operation` throws.
+	*/
+	withoutInitiator(operation) {
+		return this.runWithInitiator(void 0, operation);
+	}
+	/**
+	* Register the agent-creation factory (the loop calls this on construction,
+	* effect-scoped). A traced Cordis service is canonicalized to its concrete
+	* target; each create/resume call is then traced through that caller's
+	* context so ownership follows the caller without stacking proxy layers.
+	* Throws if a factory is already registered. Returns the disposer; on
+	* dispose the factory slot is cleared.
+	* @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
+	* @returns the disposer that clears the factory slot. The exact
+	*   Cordis effect disposer (single-shot): composite (generator) effects may
+	*   yield it directly — exact identity nests the teardown in order.
+	*/
+	setFactory(factory) {
+		return this.ctx.effect(() => {
+			if (this.factory !== void 0) throw new Error("an agent factory is already registered");
+			const target = factory[symbols.original] ?? factory;
+			this.factory = { target };
+			return () => {
+				this.factory = void 0;
+			};
+		}, "agents.setFactory()");
+	}
+	/** Return the active creation factory. */
+	requireFactory() {
+		if (this.factory === void 0) throw new Error(NO_FACTORY_MESSAGE);
+		return this.factory;
+	}
+	/**
+	* Create and publish a new agent through the registered factory.
+	* Distinct from {@link register} (which records an already-constructed
+	* agent): this constructs the agent and its session. Rejects if no factory is
+	* registered or creation/setup fails. The resolved {@link AgentHandle} lets
+	* the owner tear down exactly this agent.
+	* @param options - shared identity, optional live parent, session seed/metadata, and agent options.
+	* @returns the handle after setup, rollback-covered publication, and loop start complete.
+	*/
+	async create(options) {
+		const ownerCtx = this.ctx;
+		const { target } = this.requireFactory();
+		const receiver = getTraceable(ownerCtx, target);
+		return Reflect.apply(target.createAgent, receiver, [ownerCtx, options]);
+	}
+	/**
+	* Load a persisted session and resume an agent on it through the registered
+	* factory. Rejects if no factory is registered; the factory rejects if
+	* session persistence is not configured or persistence/setup fails.
+	* @param options - persisted identity, optional live parent, configuration, and setup.
+	* @returns the handle after setup, rollback-covered publication, and loop start complete.
+	*/
+	async resume(options) {
+		const ownerCtx = this.ctx;
+		const { target } = this.requireFactory();
+		const receiver = getTraceable(ownerCtx, target);
+		return Reflect.apply(target.resume, receiver, [ownerCtx, options]);
+	}
+	/**
+	* Register a live agent with source `startup`. Rejects if the id is already registered or a
+	* serial `agent/created` listener fails. Emits `agent/disposed`
+	* when the calling fiber is disposed — both with the agent's scope carrier
+	* (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
+	* emits are scope-filtered regardless of which context invoked `register`
+	* (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
+	* requires passing the carrier). The entry is a runtime root; factory-backed
+	* creation uses `options.parentAgent` for child ownership. Await the registration before using the agent.
+	* @param agent - the already-constructed agent to record in the store.
+	* @returns the awaitable Cordis effect disposer (single-shot; a repeat call
+	*   returns undefined without awaiting an in-flight teardown). Exact
+	*   identity is load-bearing: a composite (generator) effect that owns a
+	*   teardown ORDER — the agent factory's lifecycle chain — must yield THIS
+	*   function so Cordis nests the unregistration at that yield position;
+	*   yielding a wrapper would leave it disposing as a concurrent sibling on
+	*   owner unload, unregistering the agent (and emitting `agent/disposed`)
+	*   while its final turn is still draining.
+	*/
+	register(agent) {
+		return this.ctx.effect(async function* () {
+			yield this.enter(agent, void 0);
+			await this.announce(agent, "startup");
+		}.bind(this), "agents.register()");
+	}
+	/**
+	* Insert an already-constructed agent without announcing it. This is the
+	* advanced ordered-lifecycle primitive used by the async agent factory: it
+	* first completes setup while the agent is unpublished, then assigns the
+	* returned detach closure into its pre-installed composite teardown before
+	* calling {@link announce}. Ordinary callers use {@link register}.
+	* @param agent - the prepared, unpublished agent.
+	* @param owner - explicitly supplied live runtime owner, or
+	*   undefined for a top-level runtime root. This is runtime ownership, not
+	*   the resumed session's durable parent lineage.
+	* @returns an idempotent closure that removes this exact entry and emits
+	*   `agent/disposed` with listener failures contained. When called from a
+	*   `agent/created` listener, removal and disposal wait until the serial
+	*   creation dispatch settles.
+	*/
+	enter(agent, owner) {
+		const id = agent.id;
+		if (id !== agent.session.id) throw new Error(`agent id "${id}" does not match session id "${agent.session.id}"`);
+		const carrier = scopeTarget(agent, agent);
+		if (this.store.has(id)) throw new Error(`agent "${id}" is already registered`);
+		const entry = {
+			id,
+			agent,
+			owner,
+			carrier,
+			announced: false,
+			announcing: false,
+			detachRequested: false
+		};
+		this.store.set(id, entry);
+		let entered = true;
+		const detach = () => {
+			if (!entered) return;
+			entered = false;
+			if (entry.announcing) {
+				entry.detachRequested = true;
+				return;
+			}
+			this.detachEntered(entry);
+		};
+		return detach;
+	}
+	/** Remove one exact entered agent and emit its paired disposal when announced. */
+	detachEntered(entry) {
+		entry.detachRequested = false;
+		/* v8 ignore next -- enter() rejects replacement while this single-shot detach capability is live. */
+		if (this.store.get(entry.id) !== entry) return;
+		this.store.delete(entry.id);
+		if (!entry.announced) return;
+		this.emitDisposed(entry);
+	}
+	/** Emit the paired disposal edge through the entry's stable carrier. */
+	emitDisposed(entry) {
+		const args = [
+			entry.carrier,
+			"agent/disposed",
+			{ agent: entry.agent }
+		];
+		for (const callback of this.ctx.events.dispatch("emit", args)) try {
+			const returned = callback(...args);
+			Promise.resolve(returned).catch((error) => {
+				this.ctx.logger.warn(`agent "${entry.id}": agent/disposed listener rejected: ${String(error)}`);
+			});
+		} catch (error) {
+			this.ctx.logger.warn(`agent "${entry.id}": agent/disposed listener threw: ${String(error)}`);
+		}
+	}
+	/**
+	* Announce an agent previously inserted with {@link enter}.
+	* @param agent - the live inserted agent to announce.
+	* @param source - fresh creation, resume, clear, or compaction source.
+	* @param signal - optional factory initialization cancellation signal passed to listeners.
+	* @returns completion of the serial creation listeners; a listener failure rejects.
+	* @throws if `agent` is not the exact live registry entry for its id, or its
+	*   creation announcement already began (including a reentrant call from a
+	*   creation listener).
+	*/
+	async announce(agent, source, signal) {
+		const entry = this.store.get(agent.id);
+		if (entry === void 0 || entry.agent !== agent) throw new Error(`agent "${agent.id}" is not live in this registry`);
+		if (entry.announced || entry.announcing) throw new Error(`agent "${entry.id}" was already announced`);
+		entry.announcing = true;
+		entry.announced = true;
+		try {
+			await this.ctx.serial(entry.carrier, "agent/created", {
+				agent: entry.agent,
+				source,
+				...signal === void 0 ? {} : { signal }
+			});
+		} finally {
+			entry.announcing = false;
+			if (entry.detachRequested) this.detachEntered(entry);
+		}
+	}
+	/**
+	* Look up a live agent.
+	* @param id - the shared agent/session id to look up.
+	* @returns the agent, or undefined when no live agent has that id.
+	*/
+	get(id) {
+		return this.store.get(id)?.agent;
+	}
+	/**
+	* Test whether a live agent was created through one exact parent agent's
+	* scoped context. Runtime ownership is independent of durable session
+	* lineage and remains unambiguous when unrelated providers reuse an id.
+	* @param id - the candidate child agent's shared agent/session id.
+	* @param owner - the expected runtime creator agent.
+	* @returns true only while the exact child entry is live under that owner.
+	*/
+	isOwnedBy(id, owner) {
+		return this.store.get(id)?.owner === owner;
+	}
+	/**
+	* All live agents, in registration order.
+	* @returns a fresh array; mutating it does not affect the registry.
+	*/
+	list() {
+		return [...this.store.values()].map((entry) => entry.agent);
+	}
+	/**
+	* All live top-level agents in registration order. A top-level agent was
+	* created without an owning agent context; durable session lineage does not
+	* affect this runtime relation, so a resumed fork may still be a root.
+	* @returns a fresh array; mutating it does not affect the registry.
+	*/
+	roots() {
+		return [...this.store.values()].filter((entry) => entry.owner === void 0).map((entry) => entry.agent);
+	}
+	/** Reject new initiator boundaries while inherited continuations drain. */
+	closeInitiators() {
+		if (this.initiatorState === "active") this.initiatorState = "closing";
+	}
+	/** Wait for returned-Promise boundaries, then invalidate retained references. */
+	disposeInitiators() {
+		return this.initiatorDisposal ??= (async () => {
+			this.closeInitiators();
+			this.releaseReentrantInitiatorRuns();
+			if (this.activeInitiatorRuns !== 0) {
+				this.initiatorDrain ??= Promise.withResolvers();
+				await this.initiatorDrain.promise;
+			}
+			this.initiatorState = "disposed";
+			this.initiators.disable();
+			this.initiatorRuns.disable();
+		})();
+	}
+	/** Establish one tracked initiator or clearing boundary. */
+	runWithInitiator(agent, operation) {
+		if (this.initiatorState !== "active") throw new Error(DISPOSED_INITIATOR_MESSAGE);
+		const run = {
+			active: true,
+			parent: this.initiatorRuns.getStore()
+		};
+		this.activeInitiatorRuns += 1;
+		let result;
+		try {
+			result = this.initiatorRuns.run(run, () => this.initiators.run(agent, operation));
+		} catch (error) {
+			this.releaseInitiatorRun(run);
+			throw error;
+		}
+		if (isPromise(result)) try {
+			Promise.prototype.then.call(result, () => {
+				this.releaseInitiatorRun(run);
+			}, () => {
+				this.releaseInitiatorRun(run);
+			});
+		} catch {
+			this.releaseInitiatorRun(run);
+		}
+		else this.releaseInitiatorRun(run);
+		return result;
+	}
+	/** Whether one unloading fiber owns this service's lifecycle. */
+	hasLifecycleAncestor(candidate) {
+		let fiber = this.ctx.fiber;
+		while (true) {
+			if (fiber === candidate) return true;
+			const parent = fiber.parent.fiber;
+			if (parent === fiber) return false;
+			fiber = parent;
+		}
+	}
+	assertInitiatorsReadable() {
+		if (this.initiatorState === "disposed") throw new Error(DISPOSED_INITIATOR_MESSAGE);
+	}
+	/** Exclude the boundary chain that initiated this teardown from its own drain. */
+	releaseReentrantInitiatorRuns() {
+		let run = this.initiatorRuns.getStore();
+		while (run !== void 0) {
+			this.releaseInitiatorRun(run);
+			run = run.parent;
+		}
+	}
+	releaseInitiatorRun(run) {
+		if (!run.active) return;
+		run.active = false;
+		this.activeInitiatorRuns -= 1;
+		if (this.activeInitiatorRuns !== 0) return;
+		this.initiatorDrain?.resolve();
+		this.initiatorDrain = void 0;
+	}
+};
+//#endregion
+export { AgentRegistry, AgentRegistry as default, agentCarrier, agentEvents, assembleContextFor, emitAgentEvent, foldConsumedWork, installModelSelection };