@fishwithcat/dsh-agent 0.0.0-stage → 0.2.2-alpha.2

package/lib/index.js

@@ -0,0 +1,917 @@
+import { Service, getTraceable, symbols } from "@deepseek-ai/cordis";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { isPromise } from "node:util/types";
+import { scopeTarget } from "@deepseek-ai/dsh-scope";
+import { brandNumber } from "@deepseek-ai/dsh-brand";
+import { z } from "zod";
+import { AssistantStreamAccumulator, boundContextSummary, createUserMessage } from "@deepseek-ai/dsh-llm";
+import { ReasoningEffortId } from "@deepseek-ai/dsh-llm/brand";
+//#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 @deepseek-ai/dsh-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/projection.js
+const sessionSeqSchema = z.number().int().nonnegative().transform(brandNumber);
+/** Host projection of agent turn and step boundaries. */
+const turnBoundaryProjectionDefinition = {
+	key: "turnBoundary",
+	stateVersion: 2,
+	stateSchema: z.object({
+		openTurnStartSeq: sessionSeqSchema.nullable(),
+		lastStepStartSeq: sessionSeqSchema.nullable(),
+		lastStepBoundary: z.object({
+			kind: z.union([z.literal("start"), z.literal("end")]),
+			seq: sessionSeqSchema
+		}).nullable(),
+		lastTurn: z.number().int().nonnegative()
+	}),
+	init: () => ({
+		openTurnStartSeq: null,
+		lastStepStartSeq: null,
+		lastStepBoundary: null,
+		lastTurn: 0
+	}),
+	apply: (state, event) => {
+		switch (event.type) {
+			case "turn/start": return {
+				...state,
+				openTurnStartSeq: event.seq,
+				lastTurn: event.data.turn
+			};
+			case "turn/end": return {
+				...state,
+				openTurnStartSeq: null
+			};
+			case "step/start": return {
+				...state,
+				lastStepStartSeq: event.seq,
+				lastStepBoundary: {
+					kind: "start",
+					seq: event.seq
+				}
+			};
+			case "step/end": return {
+				...state,
+				lastStepBoundary: {
+					kind: "end",
+					seq: event.seq
+				}
+			};
+			default: return state;
+		}
+	}
+};
+//#endregion
+//#region lib/types/assistant-stream-state.js
+/**
+* Process-local assistant-attempt state retained for reconnecting presentation
+* consumers. This fold is independent of any transport: the Web follow stream,
+* the terminal watch stream, and other local viewers share it.
+* @module @deepseek-ai/dsh-agent/assistant-stream-state
+*/
+const EMPTY_BASELINE = { revision: 0 };
+/**
+* Folds dense Agent frames into the latest process-local attempt and
+* materializes one shared immutable reconnect baseline per accepted revision.
+*/
+var AssistantStreamState = class {
+	activeAttempt;
+	revision = 0;
+	snapshotValue = EMPTY_BASELINE;
+	dirty = false;
+	/**
+	* Fold one trusted frame from the current attached Agent lifecycle.
+	* @param frame - next dense process-local Assistant frame.
+	* @param durableCursor - last committed Session seq when this frame was observed.
+	*/
+	accept(frame, durableCursor) {
+		if (frame.type === "start" && frame.revision === 1 && this.revision !== 0) {
+			this.activeAttempt = void 0;
+			this.revision = 0;
+		}
+		if (frame.revision !== this.revision + 1) {
+			this.activeAttempt = void 0;
+			this.revision = frame.revision;
+			this.dirty = true;
+			return;
+		}
+		this.revision = frame.revision;
+		switch (frame.type) {
+			case "start":
+				this.activeAttempt = {
+					attemptId: frame.attemptId,
+					startedAfterSeq: durableCursor,
+					turn: frame.turn,
+					step: frame.step,
+					stream: new AssistantStreamAccumulator(),
+					nextIndex: 0
+				};
+				break;
+			case "chunk": {
+				const attempt = this.activeAttempt;
+				if (attempt === void 0 || attempt.attemptId !== frame.attemptId || frame.index !== attempt.nextIndex) {
+					this.activeAttempt = void 0;
+					break;
+				}
+				attempt.stream.push({
+					time: frame.time,
+					chunk: frame.chunk
+				});
+				attempt.nextIndex += 1;
+				break;
+			}
+			case "end":
+				this.activeAttempt = void 0;
+				break;
+		}
+		this.dirty = true;
+	}
+	/**
+	* Read the cached reconnect baseline, materializing it after a state change.
+	* @returns the identity-stable baseline for the latest accepted revision.
+	*/
+	snapshot() {
+		if (!this.dirty) return this.snapshotValue;
+		this.snapshotValue = {
+			revision: this.revision,
+			...this.activeAttempt === void 0 ? {} : { activeAttempt: {
+				attemptId: this.activeAttempt.attemptId,
+				startedAfterSeq: this.activeAttempt.startedAfterSeq,
+				turn: this.activeAttempt.turn,
+				step: this.activeAttempt.step,
+				nextIndex: this.activeAttempt.nextIndex,
+				stream: this.activeAttempt.stream.snapshot()
+			} }
+		};
+		this.dirty = false;
+		return this.snapshotValue;
+	}
+};
+//#endregion
+//#region lib/types/model-selection.js
+/**
+* Build a detached selection, omitting an absent effort.
+* @param provider - provider route.
+* @param model - provider-owned model id.
+* @param reasoningEffort - explicit effort; omission follows adapter defaults.
+* @returns a detached selection.
+*/
+function toSelection(provider, model, reasoningEffort) {
+	return {
+		provider,
+		model,
+		...reasoningEffort === void 0 ? {} : { reasoningEffort }
+	};
+}
+/**
+* Compare provider and model without comparing reasoning effort.
+* @param left - first selection.
+* @param right - second selection.
+* @returns whether both selections name the same route.
+*/
+function sameRoute(left, right) {
+	return left.provider === right.provider && left.model === right.model;
+}
+/**
+* Compare complete selections, treating absent effort as its own value.
+* @param left - first selection, or no recorded selection.
+* @param right - second selection, or no recorded selection.
+* @returns whether both selections agree.
+*/
+function sameModelSelection(left, right) {
+	return left === right || left !== null && right !== null && sameRoute(left, right) && left.reasoningEffort === right.reasoningEffort;
+}
+/** Selection a recorded request used, omitting an effort the adapter defaulted. */
+function selectionOfHeader({ config, adapterDefaults }) {
+	return toSelection(config.provider, config.model, adapterDefaults?.reasoningEffort === true ? void 0 : config.reasoningEffort);
+}
+const selectionSchema = z.object({
+	provider: z.string().min(1),
+	model: z.string().min(1),
+	reasoningEffort: z.string().min(1).transform(ReasoningEffortId).exactOptional()
+}).nullable();
+/**
+* Session selection fold: recorded selections become
+* the pending choice, and each request header retires a matching one.
+*/
+const modelSelectionProjectionDefinition = {
+	key: "modelSelection",
+	stateVersion: 3,
+	stateSchema: z.object({
+		lastUsed: selectionSchema,
+		pending: selectionSchema
+	}),
+	init: () => ({
+		lastUsed: null,
+		pending: null
+	}),
+	apply: (state, event) => {
+		if (event.type === "model/selection") return sameModelSelection(state.pending, event.data) ? state : {
+			...state,
+			pending: event.data
+		};
+		if (event.type !== "request/header") return state;
+		const lastUsed = selectionOfHeader(event.data.header);
+		const pending = sameModelSelection(state.pending, lastUsed) ? null : state.pending;
+		return sameModelSelection(state.lastUsed, lastUsed) && pending === state.pending ? state : {
+			lastUsed,
+			pending
+		};
+	},
+	wire: {
+		viewSchema: z.object({
+			lastUsed: selectionSchema,
+			next: selectionSchema
+		}),
+		view: (state) => ({
+			lastUsed: state.lastUsed,
+			next: state.pending ?? state.lastUsed
+		})
+	}
+};
+/**
+* Read and record one Agent's model choices without resolving adapter defaults.
+* @param readState - driver-owned reader for this Session's selection projection.
+* @param session - Session receiving durable model selections.
+* @param options - live route fallback until a selection or request is recorded.
+*/
+var AgentModel = class {
+	readState;
+	session;
+	options;
+	constructor(readState, session, options) {
+		this.readState = readState;
+		this.session = session;
+		this.options = options;
+	}
+	current() {
+		const recorded = this.recordedSelection();
+		if (recorded !== null) return { ...recorded };
+		const { provider, model, reasoningEffort } = this.options;
+		return provider && model ? toSelection(provider, model, reasoningEffort) : void 0;
+	}
+	select(selection) {
+		if (sameModelSelection(this.recordedSelection(), selection)) return;
+		this.session.append("model/selection", toSelection(selection.provider, selection.model, selection.reasoningEffort));
+	}
+	recordedSelection() {
+		const state = this.readState();
+		return state.pending ?? state.lastUsed;
+	}
+};
+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}`)
+		}
+	});
+}
+/**
+* Append a model-switch notice when the step's fixed route differs from the
+* last request header. Effort-only changes and empty no-request decisions add
+* no notice; a failure before header persistence repeats it on the next step.
+* Install in the selected Agent's unpublished setup scope.
+* @param agentCtx - The selected Agent's scoped context.
+* @returns Disposer for the scoped pre-step listener.
+*/
+function installModelSelection(agentCtx) {
+	return agentCtx.on("agent/pre-step", async ({ agent, messages, signal, step, modelSelection }, 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 previous = agent.session.requestHeader()?.config;
+		if (previous === void 0 || modelSelection.provider === previous.provider && modelSelection.model === previous.model) return decision;
+		return {
+			...decision,
+			messages: [...decision.messages, modelSwitchNotice(previous, modelSelection)]
+		};
+	}, { prepend: true });
+}
+//#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 @deepseek-ai/dsh-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/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 @deepseek-ai/dsh-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 @deepseek-ai/dsh-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}
+* (`@deepseek-ai/dsh-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 {
+	static inject = ["sessionProjections"];
+	turnBoundaryProjectionHandle;
+	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",
+				resource: "session",
+				hostTypeSymbol: "@deepseek-ai/dsh-agent#Agent",
+				wireTypeSymbol: "@deepseek-ai/dsh-session/types#SessionId",
+				resolve: (sessionId) => this.get(sessionId)
+			});
+			typeCtx.typert.contexts.registerHost("agent", {
+				wire: "agentId",
+				wireTypeSymbol: "@deepseek-ai/dsh-session/types#SessionId",
+				resource: "session",
+				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));
+	}
+	async [Service.init]() {
+		this.turnBoundaryProjectionHandle = await this.ctx.sessionProjections.register(turnBoundaryProjectionDefinition);
+	}
+	/**
+	* Read the turn and step positions recorded in a Session.
+	* @param session - Session whose committed events are read.
+	* @returns the current turn and step positions; do not mutate the returned value.
+	*/
+	turnBoundaryOf(session) {
+		return this.turnBoundaryProjectionHandle.stateOf(session);
+	}
+	/**
+	* 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 { AgentModel, AgentRegistry, AgentRegistry as default, AssistantStreamState, agentCarrier, agentEvents, assembleContextFor, emitAgentEvent, foldConsumedWork, installModelSelection, modelSelectionProjectionDefinition };