@dxos/agent-runtime 0.13.0 → 0.14.0

package/dist/lib/chunk-AgentService.mjs

@@ -22,10 +22,11 @@ import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 import * as Struct from "effect/Struct";
 import { AiService, Model, OpaqueToolkit } from "@dxos/ai";
-import { ProcessManager } from "@dxos/compute-runtime";
+import { OperationProcess } from "@dxos/compute-runtime";
 import * as Credential from "@dxos/compute/Credential";
 import * as McpServer from "@dxos/compute/McpServer";
 import * as Operation from "@dxos/compute/Operation";
+import * as OperationHandlerSet from "@dxos/compute/OperationHandlerSet";
 import * as StorageService from "@dxos/compute/StorageService";
 import * as Trace from "@dxos/compute/Trace";
 import { AccessToken } from "@dxos/link";
@@ -196,12 +197,13 @@ var AgentProcess = (options) => Operation.makeDurable({
 		Operation.Service,
 		Registry.Service,
 		StorageService.StorageService,
-		ProcessManager.ProcessOperationInvoker.Service,
+		Process.ManagerService,
+		OperationHandlerSet.OperationHandlerProvider,
 		AiService.AiService,
 		Credential.CredentialsService
 	],
 	rpcs: HarnessControl
-}, (ctx) => Effect.gen(function* () {
+}).pipe(Operation.withDurableHandler((ctx) => Effect.gen(function* () {
 	const chatDxn = Annotation.getDictionary(ctx.params.annotations, Process.TargetAnnotation).pipe(Option.getOrUndefined);
 	if (chatDxn == null) return yield* Effect.die(/* @__PURE__ */ new Error("Agent executable requires spawn options.target set to a Chat DXN."));
 	const chat = yield* Database.resolve(chatDxn, Chat.Chat).pipe(Effect.orDie);
@@ -240,23 +242,32 @@ var AgentProcess = (options) => Operation.makeDurable({
 	yield* reconcileAlarmWith(startupPending);
 	const strategy = Option.fromNullishOr(options.delegationStrategy);
 	let delegations = [...yield* DelegationsCell.get];
+	let asyncHooks = [...yield* AsyncHooksCell.get];
+	const untrackedExits = /* @__PURE__ */ new Set();
 	const model = chat.session?.model ?? options.defaultModel;
 	const requestModelLayer = AiService.languageModel(DXN.getName(model ?? Model.claudeSonnet5.id), { provider: options.provider });
-	const operationInvoker = yield* ProcessManager.ProcessOperationInvoker.Service;
+	const childServices = yield* Effect.context();
 	const runEndRequestHooks = Effect.gen(function* () {
 		yield* SkillHooks.runHooks({
 			skills: session.getSkills(),
 			phase: "end-request",
-			invoke: (operation, input) => Effect.gen(function* () {
-				const exit = yield* (yield* operationInvoker.invokeFiber(operation, input, {
+			invoke: (operation, input, hook) => Effect.gen(function* () {
+				const handle = yield* Process.spawn(OperationProcess.make(operation), input, {
 					environment: { conversation: Obj.getURI(feed) },
 					traceMeta: { conversation: Ref.make(feed) }
-				})).await;
-				if (Exit.isFailure(exit)) return yield* Effect.failCause(exit.cause);
-			}).pipe(Effect.asVoid, Effect.orDie)
+				});
+				if (hook.async) {
+					if (untrackedExits.delete(handle.pid)) return;
+					asyncHooks.push(handle.pid);
+					yield* AsyncHooksCell.set(asyncHooks);
+					return;
+				}
+				yield* Process.awaitOutput(handle);
+			}).pipe(Effect.provide(childServices), Effect.asVoid, Effect.orDie)
 		});
 	});
 	let turnRan = false;
+	let endHooksFired = asyncHooks.length > 0;
 	const unseenWriteIds = /* @__PURE__ */ new Set();
 	let unseenWriteWakes = 0;
 	const pendingWork = (state) => isAgentWorkPending({
@@ -271,39 +282,60 @@ var AgentProcess = (options) => Operation.makeDurable({
 		for (const pid of dropReportedToolResults(toolResults, (pid) => toolCallManager.isReported(pid))) log("drop tool result reported within its turn", { pid }, {
 			"~LogMeta": "~LogMeta",
 			F: __dxlog_file$1,
-			L: 364,
+			L: 400,
 			S: this
 		});
 		if (pendingWork(state)) {
 			yield* reportSleeping(state);
 			return;
 		}
-		if (!turnRan) {
+		if (!turnRan && !endHooksFired) {
 			log("agent idle before its first turn, staying resident", void 0, {
 				"~LogMeta": "~LogMeta",
 				F: __dxlog_file$1,
-				L: 375,
+				L: 411,
 				S: this
 			});
 			return;
 		}
-		yield* runEndRequestHooks;
-		const after = yield* sessionStore.loadPending(feed);
-		if (pendingWork(after)) {
-			log("agent work enqueued by end-request hook, continuing", void 0, {
+		if (!endHooksFired) {
+			endHooksFired = true;
+			yield* runEndRequestHooks;
+			const after = yield* sessionStore.loadPending(feed);
+			if (pendingWork(after)) {
+				log("agent work enqueued by end-request hook, continuing", void 0, {
+					"~LogMeta": "~LogMeta",
+					F: __dxlog_file$1,
+					L: 422,
+					S: this
+				});
+				yield* reconcileAlarmWith(after);
+				yield* reportSleeping(after);
+				return;
+			}
+		}
+		if (asyncHooks.length > 0) {
+			log("awaiting background end-request hooks", { count: asyncHooks.length }, {
 				"~LogMeta": "~LogMeta",
 				F: __dxlog_file$1,
-				L: 384,
+				L: 432,
+				S: this
+			});
+			return;
+		}
+		if (options.resident) {
+			log("agent work complete, staying resident", void 0, {
+				"~LogMeta": "~LogMeta",
+				F: __dxlog_file$1,
+				L: 437,
 				S: this
 			});
-			yield* reconcileAlarmWith(after);
-			yield* reportSleeping(after);
 			return;
 		}
 		log("agent work complete, succeeding", void 0, {
 			"~LogMeta": "~LogMeta",
 			F: __dxlog_file$1,
-			L: 390,
+			L: 441,
 			S: this
 		});
 		ctx.succeed();
@@ -315,7 +347,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 				log.info("discarding queue entries left by a previous process", { count: startupPending.pendingMessages.length }, {
 					"~LogMeta": "~LogMeta",
 					F: __dxlog_file$1,
-					L: 403,
+					L: 454,
 					S: this
 				});
 				yield* Effect.forEach(startupPending.pendingMessages, (message) => sessionStore.ack(feed, message), { discard: true });
@@ -347,7 +379,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 			log("agent onInput received", { backlog: toolResults.length }, {
 				"~LogMeta": "~LogMeta",
 				F: __dxlog_file$1,
-				L: 432,
+				L: 483,
 				S: this
 			});
 			const message = makeInputMessage(input);
@@ -358,7 +390,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 			log("agent onInput enqueued to feed", void 0, {
 				"~LogMeta": "~LogMeta",
 				F: __dxlog_file$1,
-				L: 438,
+				L: 489,
 				S: this
 			});
 		}),
@@ -366,15 +398,16 @@ var AgentProcess = (options) => Operation.makeDurable({
 			log("agent onAlarm fired", { backlog: toolResults.length }, {
 				"~LogMeta": "~LogMeta",
 				F: __dxlog_file$1,
-				L: 442,
+				L: 493,
 				S: this
 			});
 			markWork("agent.wake");
-			yield* Trace.emitRequestPhase("preparing");
+			const announced = toolResults.length > 0 || unseenWriteIds.size > 0;
+			if (announced) yield* Trace.emitRequestPhase("preparing");
 			for (const pid of dropReportedToolResults(toolResults, (pid) => toolCallManager.isReported(pid))) log.info("skip tool result that was reported synchronously", { pid }, {
 				"~LogMeta": "~LogMeta",
 				F: __dxlog_file$1,
-				L: 451,
+				L: 506,
 				S: this
 			});
 			const toolResult = toolResults.shift();
@@ -384,7 +417,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 				log("agent onAlarm handling", { tag: toolResult._tag }, {
 					"~LogMeta": "~LogMeta",
 					F: __dxlog_file$1,
-					L: 459,
+					L: 514,
 					S: this
 				});
 				prompt = toolResultPrompt(toolResult);
@@ -411,7 +444,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 					}, {
 						"~LogMeta": "~LogMeta",
 						F: __dxlog_file$1,
-						L: 491,
+						L: 546,
 						S: this
 					});
 					unseenWriteIds.delete(message.id);
@@ -428,7 +461,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 						log.warn("agent self-wake budget spent, dropping alarm", { wakes: selfWakes }, {
 							"~LogMeta": "~LogMeta",
 							F: __dxlog_file$1,
-							L: 504,
+							L: 559,
 							S: this
 						});
 						yield* sessionStore.ack(feed, dueAlarm);
@@ -447,7 +480,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 					}, {
 						"~LogMeta": "~LogMeta",
 						F: __dxlog_file$1,
-						L: 515,
+						L: 570,
 						S: this
 					});
 					dequeued = dueAlarm;
@@ -467,7 +500,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 					}, {
 						"~LogMeta": "~LogMeta",
 						F: __dxlog_file$1,
-						L: 533,
+						L: 588,
 						S: this
 					});
 					yield* ctx.setAlarm(UNSEEN_WRITE_RETRY_MS);
@@ -479,7 +512,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 					}, {
 						"~LogMeta": "~LogMeta",
 						F: __dxlog_file$1,
-						L: 544,
+						L: 599,
 						S: this
 					});
 					yield* reconcileAlarmWith(state);
@@ -488,7 +521,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 					log("agent onAlarm empty queue", {}, {
 						"~LogMeta": "~LogMeta",
 						F: __dxlog_file$1,
-						L: 551,
+						L: 606,
 						S: this
 					});
 					yield* reconcileAlarmWith(state);
@@ -496,18 +529,19 @@ var AgentProcess = (options) => Operation.makeDurable({
 					return;
 				}
 			}
+			if (!announced) yield* Trace.emitRequestPhase("preparing");
 			const [mcpServers] = yield* Effect.all([loadSpaceMcpServers(), Effect.gen(function* () {
 				if (dequeued !== void 0) yield* sessionStore.markInFlight(feed, dequeued);
 				log("begin request", { prompt }, {
 					"~LogMeta": "~LogMeta",
 					F: __dxlog_file$1,
-					L: 570,
+					L: 629,
 					S: this
 				});
 				log("trace agent request begin", void 0, {
 					"~LogMeta": "~LogMeta",
 					F: __dxlog_file$1,
-					L: 571,
+					L: 630,
 					S: this
 				});
 				yield* Trace.write(Trace.AgentRequestBegin, {});
@@ -529,10 +563,11 @@ var AgentProcess = (options) => Operation.makeDurable({
 			log("end request", void 0, {
 				"~LogMeta": "~LogMeta",
 				F: __dxlog_file$1,
-				L: 605,
+				L: 664,
 				S: this
 			});
 			turnRan = true;
+			endHooksFired = false;
 			yield* ToolResultsCell.set(toolResults);
 			if (dequeued !== void 0) {
 				yield* sessionStore.ack(feed, dequeued);
@@ -555,7 +590,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 					}, {
 						"~LogMeta": "~LogMeta",
 						F: __dxlog_file$1,
-						L: 626,
+						L: 686,
 						S: this
 					});
 					yield* Trace.write(Trace.DelegationSpawned, {
@@ -576,15 +611,29 @@ var AgentProcess = (options) => Operation.makeDurable({
 			log("childEvent", { event }, {
 				"~LogMeta": "~LogMeta",
 				F: __dxlog_file$1,
-				L: 653,
+				L: 713,
 				S: this
 			});
+			if (event._tag === "exited" && asyncHooks.includes(event.pid)) {
+				asyncHooks = asyncHooks.filter((pid) => pid !== event.pid);
+				yield* AsyncHooksCell.set(asyncHooks);
+				const exit = yield* (yield* Process.ManagerService).attach(event.pid).pipe(Effect.flatMap(Process.awaitOutput), Effect.exit);
+				if (Exit.isFailure(exit)) log.warn("background end-request hook failed", { pid: event.pid }, {
+					"~LogMeta": "~LogMeta",
+					F: __dxlog_file$1,
+					L: 721,
+					S: this
+				});
+				yield* maybeComplete;
+				return;
+			}
 			if (event._tag === "exited") {
 				const delegation = delegations.find((delegation) => delegation.pid === event.pid);
 				if (delegation) {
 					delegations = delegations.filter((other) => other.pid !== event.pid);
 					yield* DelegationsCell.set(delegations);
-					const exit = yield* (yield* (yield* ProcessManager.ProcessOperationInvoker.Service).attachFiber(event.pid).pipe(Effect.orDie)).await;
+					const child = yield* (yield* Process.ManagerService).attach(event.pid);
+					const exit = yield* Process.awaitOutput(child).pipe(Effect.exit);
 					const result = Exit.isSuccess(exit) ? resultPreview(exit.value) : void 0;
 					yield* Trace.write(Trace.DelegationCompleted, {
 						taskId: delegation.id,
@@ -608,7 +657,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 							}, {
 								"~LogMeta": "~LogMeta",
 								F: __dxlog_file$1,
-								L: 685,
+								L: 757,
 								S: this
 							});
 							yield* Trace.write(Trace.DelegationSpawned, {
@@ -625,25 +674,22 @@ var AgentProcess = (options) => Operation.makeDurable({
 					}, {
 						"~LogMeta": "~LogMeta",
 						F: __dxlog_file$1,
-						L: 692,
+						L: 764,
 						S: this
 					});
 					yield* maybeComplete;
 				} else if (toolCallManager.isToolCall(event.pid)) {
-					const attachExit = yield* (yield* ProcessManager.ProcessOperationInvoker.Service).attachFiber(event.pid).pipe(Effect.exit);
-					if (Exit.isFailure(attachExit)) {
-						if (toolCallManager.isToolCall(event.pid) || toolResults.some((item) => item.pid === event.pid) || toolCallManager.isReported(event.pid)) {
-							log.verbose("childEvent skipped (process gone, result already handled)", { pid: event.pid }, {
-								"~LogMeta": "~LogMeta",
-								F: __dxlog_file$1,
-								L: 705,
-								S: this
-							});
-							return;
-						}
-						return yield* Effect.failCause(attachExit.cause).pipe(Effect.orDie);
+					const attachExit = yield* (yield* Process.ManagerService).attach(event.pid).pipe(Effect.exit);
+					if (Exit.isFailure(attachExit) && isToolResultHandled(toolResults, event.pid, (pid) => toolCallManager.isReported(pid))) {
+						log.verbose("childEvent skipped (process gone, result already handled)", { pid: event.pid }, {
+							"~LogMeta": "~LogMeta",
+							F: __dxlog_file$1,
+							L: 775,
+							S: this
+						});
+						return;
 					}
-					const result = yield* attachExit.value.await.pipe(Effect.orDie).pipe(Effect.map(Exit.match({
+					const result = yield* (Exit.isFailure(attachExit) ? Effect.failCause(attachExit.cause) : Process.awaitOutput(attachExit.value)).pipe(Effect.exit, Effect.map(Exit.match({
 						onSuccess: (value) => ({
 							_tag: "tool_result",
 							pid: event.pid,
@@ -664,7 +710,7 @@ var AgentProcess = (options) => Operation.makeDurable({
 					}, {
 						"~LogMeta": "~LogMeta",
 						F: __dxlog_file$1,
-						L: 730,
+						L: 803,
 						S: this
 					});
 					yield* ToolResultsCell.set(toolResults);
@@ -672,19 +718,22 @@ var AgentProcess = (options) => Operation.makeDurable({
 					log("agent onChildEvent alarm scheduled", { depth: toolResults.length }, {
 						"~LogMeta": "~LogMeta",
 						F: __dxlog_file$1,
-						L: 733,
+						L: 806,
 						S: this
 					});
-				} else log.verbose("childEvent ignored non-tool call and not a delegation", { pid: event.pid }, {
-					"~LogMeta": "~LogMeta",
-					F: __dxlog_file$1,
-					L: 735,
-					S: this
-				});
+				} else {
+					log.verbose("childEvent ignored non-tool call and not a delegation", { pid: event.pid }, {
+						"~LogMeta": "~LogMeta",
+						F: __dxlog_file$1,
+						L: 808,
+						S: this
+					});
+					untrackedExits.add(event.pid);
+				}
 			}
 		})
 	};
-}));
+})));
 var ToolResultEvent = Schema.TaggedStruct("tool_result", {
 	pid: Process.ID,
 	result: Schema.Unknown,
@@ -700,6 +749,8 @@ var Delegation = Schema.Struct({
 	id: Schema.String
 }).mapFields(Struct.map(Schema.mutableKey));
 var DelegationsCell = StorageService.cell(Schema.fromJsonString(Schema.Array(Delegation).pipe(Schema.mutable)), "delegations").pipe(StorageService.withDefault(() => []));
+/** Pids of background ({@link Skill.Hook.async}) end-request hooks the process is waiting on. */
+var AsyncHooksCell = StorageService.cell(Schema.fromJsonString(Schema.Array(Process.ID).pipe(Schema.mutable)), "asyncHooks").pipe(StorageService.withDefault(() => []));
 /**
 * Ids of queue entries this process has ACKED, held until the ack is visible in the feed read.
 *
@@ -777,7 +828,7 @@ var ToolCallManager = class {
 					log("reconcile queued tool result", { pid: item.pid }, {
 						"~LogMeta": "~LogMeta",
 						F: __dxlog_file$1,
-						L: 890,
+						L: 971,
 						S: this
 					});
 				}
@@ -789,6 +840,11 @@ var ToolCallManager = class {
 /** True while the agent still has queued work, a pending alarm, subprocesses, or undelivered tool results. */
 var isAgentWorkPending = ({ toolResults, pendingMessages, pendingAlarms, delegations, toolCallManager }) => toolResults.length > 0 || pendingMessages.length > 0 || pendingAlarms.length > 0 || delegations.length > 0 || toolCallManager.hasPendingToolResults();
 /**
+* Whether a tool call's result is already accounted for — queued for the next turn or delivered to the
+* agent — so a finished child that can no longer be reattached needs no answer of its own.
+*/
+var isToolResultHandled = (queue, pid, isReported) => queue.some((item) => item.pid === pid) || isReported(pid);
+/**
 * Discards tool results at the head of the queue whose values already reached the agent.
 *
 * A tool that returned inside its turn is reported synchronously AND left queued; after a reload the
@@ -838,7 +894,7 @@ var wakeUpPrompt = (firedAt, message, budget) => {
 	].filter((line) => line != null).join("\n");
 };
 var ToolExecutionService = ({ enableBackgrounding, backgroundThreshold = Duration.seconds(1), toolCallManager, feed }) => Layer.unwrap(Effect.gen(function* () {
-	const operationInvoker = yield* ProcessManager.ProcessOperationInvoker.Service;
+	const childServices = yield* Effect.context();
 	return makeToolExecutionService({ invoke: (tool, input) => Effect.gen(function* () {
 		const operationDef = getOperationFromTool(tool).pipe(Option.getOrThrow);
 		log("invoking operation", {
@@ -847,37 +903,37 @@ var ToolExecutionService = ({ enableBackgrounding, backgroundThreshold = Duratio
 		}, {
 			"~LogMeta": "~LogMeta",
 			F: __dxlog_file$1,
-			L: 1024,
+			L: 1117,
 			S: this
 		});
-		const fiber = yield* operationInvoker.invokeFiber(operationDef, input, {
+		const handle = yield* Process.spawn(OperationProcess.make(operationDef), input, {
 			environment: { conversation: Obj.getURI(feed) },
 			traceMeta: { conversation: Ref.make(feed) }
 		});
 		markWork("tool.spawned");
-		yield* toolCallManager.beginCall(fiber.pid);
+		yield* toolCallManager.beginCall(handle.pid);
 		markWork("tool.call-recorded");
 		log("invoked operation", {
 			operationDef,
 			input,
-			fiber
+			pid: handle.pid
 		}, {
 			"~LogMeta": "~LogMeta",
 			F: __dxlog_file$1,
-			L: 1036,
+			L: 1129,
 			S: this
 		});
-		const awaitWithReport = fiber.await.pipe(Effect.tap(() => toolCallManager.markAsReported(fiber.pid)));
-		const result = enableBackgrounding ? yield* awaitWithReport.pipe(Effect.timeout(backgroundThreshold), Effect.catchTag("TimeoutError", () => Effect.succeed(Exit.succeed(toolIsRunningInBackgroundResponse(fiber.pid))))) : yield* awaitWithReport;
+		const awaitWithReport = Process.awaitOutput(handle).pipe(Effect.exit, Effect.tap(() => toolCallManager.markAsReported(handle.pid)));
+		const result = enableBackgrounding ? yield* awaitWithReport.pipe(Effect.timeout(backgroundThreshold), Effect.catchTag("TimeoutError", () => Effect.succeed(Exit.succeed(toolIsRunningInBackgroundResponse(handle.pid))))) : yield* awaitWithReport;
 		markWork("tool.settled");
 		log("result", { result }, {
 			"~LogMeta": "~LogMeta",
 			F: __dxlog_file$1,
-			L: 1048,
+			L: 1144,
 			S: this
 		});
 		return yield* result;
-	}) });
+	}).pipe(Effect.provide(childServices)) });
 }));
 var AsynchronousExectionToolkit = class extends Toolkit.make(Tool.make("poll-tools", {
 	description: trim`
@@ -900,12 +956,16 @@ var AsynchronousExectionToolkit = class extends Toolkit.make(Tool.make("poll-too
 	})
 })) {};
 var AsynchronousExectionToolkitLayer = AsynchronousExectionToolkit.toLayer(Effect.gen(function* () {
-	const invoker = yield* ProcessManager.ProcessOperationInvoker.Service;
+	const manager = yield* Process.ManagerService;
 	return { "poll-tools": ({ ids, wait, timeout = 1e4 }) => Effect.gen(function* () {
-		return yield* Effect.forEach(ids, (pid) => invoker.attachFiber(Process.ID.make(pid)).pipe(Effect.flatMap((_) => _.await), Effect.timeout(Duration.millis(timeout)), Effect.flatMap(Exit.match({
-			onSuccess: (value) => Effect.succeed(toolResultResponse(pid, value)),
-			onFailure: (cause) => Effect.succeed(toolErrorResponse(pid, Cause.pretty(cause)))
-		})), Effect.catchTag("ProcessNotFoundError", () => Effect.succeed(`Process not found: ${pid}`)), Effect.catchTag("TimeoutError", () => Effect.succeed(`Process still running: ${pid}`))));
+		return yield* Effect.forEach(ids, (pid) => Effect.gen(function* () {
+			const attached = yield* manager.attach(Process.ID.make(pid)).pipe(Effect.exit);
+			if (Exit.isFailure(attached)) return `Process not found: ${pid}`;
+			return yield* Process.awaitOutput(attached.value).pipe(Effect.exit, Effect.timeout(Duration.millis(timeout)), Effect.map(Exit.match({
+				onSuccess: (value) => toolResultResponse(pid, value),
+				onFailure: (cause) => toolErrorResponse(pid, Cause.pretty(cause))
+			})), Effect.catchTag("TimeoutError", () => Effect.succeed(`Process still running: ${pid}`)));
+		}));
 	}) };
 }));
 /**
@@ -981,17 +1041,39 @@ var layer = (opts) => Layer.effect(AgentService.AgentService, Effect.gen(functio
 		defaultModel: opts?.defaultModel,
 		provider: provider ?? opts?.provider,
 		enableToolBackgrounding: opts?.enableToolBackgrounding,
-		delegationStrategy: opts?.delegationStrategy
+		delegationStrategy: opts?.delegationStrategy,
+		resident: opts?.resident
 	});
+	/**
+	* The process a chat runs on: the one its session names, or ours. A name nothing contributed
+	* (its plugin was removed) falls back to ours rather than leaving the chat unable to run.
+	*/
+	const executableFor = (chat, provider) => {
+		const key = chat.session?.process;
+		if (key === void 0 || key === "org.dxos.testing.process.agent") return makeExecutable(provider);
+		const definition = opts?.processes?.().find((candidate) => candidate.key === key);
+		if (!definition) {
+			log.warn("agent process not contributed; running the default", { key }, {
+				"~LogMeta": "~LogMeta",
+				F: __dxlog_file,
+				L: 201,
+				S: this
+			});
+			return makeExecutable(provider);
+		}
+		return definition;
+	};
 	const service = {
 		getSession: (chat, options) => Effect.suspend(() => lockFor(chat.id).withPermits(1)(Effect.gen(function* () {
 			const provider = options?.provider ?? opts?.provider;
 			const model = chat.session?.model;
 			const instructions = chat.instructions?.uri;
 			const location = options?.location ?? "local";
+			const executable = executableFor(chat, provider);
+			if (location === "edge" && executable.key !== "org.dxos.testing.process.agent") return yield* Effect.die(/* @__PURE__ */ new Error(`Agent process ${executable.key} runs only locally, but the chat asked for edge.`));
 			const cached = sessionCache.get(chat.id);
 			if (cached) {
-				if (cached.model === model && cached.provider === provider && cached.instructions === instructions && cached.location === location && !Process.isTerminal(cached.handle.status.state)) return cached.session;
+				if (cached.model === model && cached.provider === provider && cached.instructions === instructions && cached.location === location && cached.process === executable.key && !Process.isTerminal(cached.handle.status.state)) return cached.session;
 				if (!Process.isTerminal(cached.handle.status.state)) yield* cached.handle.terminate();
 				sessionCache.delete(chat.id);
 			}
@@ -1000,7 +1082,6 @@ var layer = (opts) => Layer.effect(AgentService.AgentService, Effect.gen(functio
 			const parsedEchoUri = EID.tryParse(target);
 			const spaceId = parsedEchoUri ? EID.getSpaceId(parsedEchoUri) : void 0;
 			const processLocation = locationFor(options?.location, spaceId);
-			const executable = makeExecutable(provider);
 			let activeProcess = (yield* processManager.handles({
 				target,
 				key: executable.key,
@@ -1040,6 +1121,7 @@ var layer = (opts) => Layer.effect(AgentService.AgentService, Effect.gen(functio
 				provider,
 				instructions,
 				location,
+				process: executable.key,
 				handle,
 				session
 			});
@@ -1047,27 +1129,41 @@ var layer = (opts) => Layer.effect(AgentService.AgentService, Effect.gen(functio
 		}))),
 		hydrate: Effect.fnUntraced(function* () {
 			sessionCache.clear();
+			const contributed = (opts?.processes?.() ?? []).filter(({ key }) => key !== AGENT_PROCESS_KEY);
 			const executable = makeExecutable();
-			const agents = [...yield* processManager.handles({ key: AGENT_PROCESS_KEY }), ...(yield* Effect.forEach([...remoteSpaces], (space) => processManager.handles({
-				key: AGENT_PROCESS_KEY,
-				location: {
-					kind: "edge",
-					space
-				}
-			}))).flat()];
+			const agents = [
+				...(yield* processManager.handles({ key: AGENT_PROCESS_KEY })).map((agent) => ({
+					agent,
+					executable
+				})),
+				...(yield* Effect.forEach(contributed, (definition) => processManager.handles({ key: definition.key }).pipe(Effect.map((agents) => agents.map((agent) => ({
+					agent,
+					executable: definition
+				})))))).flat(),
+				...(yield* Effect.forEach([...remoteSpaces], (space) => processManager.handles({
+					key: AGENT_PROCESS_KEY,
+					location: {
+						kind: "edge",
+						space
+					}
+				}))).flat().map((agent) => ({
+					agent,
+					executable
+				}))
+			];
 			log("agent hydrate", { count: agents.length }, {
 				"~LogMeta": "~LogMeta",
 				F: __dxlog_file,
-				L: 207,
+				L: 231,
 				S: this
 			});
-			for (const agent of agents) yield* agent.hydrate(executable).pipe(Effect.catchCause((cause) => Effect.sync(() => log.warn("agent hydrate skipped", {
+			for (const { agent, executable } of agents) yield* agent.hydrate(executable).pipe(Effect.catchCause((cause) => Effect.sync(() => log.warn("agent hydrate skipped", {
 				pid: agent.pid,
 				cause: Cause.pretty(cause)
 			}, {
 				"~LogMeta": "~LogMeta",
 				F: __dxlog_file,
-				L: 213,
+				L: 237,
 				S: this
 			}))));
 		})
@@ -1102,7 +1198,7 @@ var makeSession = (process, chat, feed, releaseSession, isFinished, resubmit) =>
 	running: Atom.make((get) => get(process.statusAtom).state === Process.State.RUNNING || get(process.statusAtom).state === Process.State.HYBERNATING),
 	waitForCompletion: () => process.runUntilSettled(),
 	terminate: () => process.terminate().pipe(Effect.tap(() => Effect.sync(releaseSession))),
-	subscribeEphemeral: () => process.subscribeEphemeral()
+	subscribeEphemeral: (options) => process.subscribeEphemeral(options)
 });
 //#endregion
 export { AgentProcess as a, __exportAll as c, AgentInput as i, layer as n, makeInputMessage as o, AGENT_PROCESS_KEY as r, makeAiSessionTurnProducer as s, AgentService_exports as t };