@xopcai/xopc 0.0.369 → 0.0.370

package/dist/src/agent/embedded/codemode-extension.js

@@ -0,0 +1,232 @@
+import { isCodemodeCoreRead } from "../tools/codemode-permissions.js";
+import { getXopcToolMetadata } from "./tool-metadata.js";
+import { withDataToolPermissions } from "../tools/dataBatch.js";
+import { retainCodemodeOutput } from "./codemode-output.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createCodemodeExtension } from "@earendil-works/pi-coding-agent";
+//#region src/agent/embedded/codemode-extension.ts
+const MAX_STORE_BYTES = 64 * 1024;
+const MAX_SOURCE_BYTES = 64 * 1024;
+/** Public pi extension, restricted to core reads and the current xopc turn policy. */
+function createXopcCodemodeExtension(policy, tools, getSession) {
+	const allowed = new Set(tools.filter((tool) => isCodemodeCoreRead(tool) || getXopcToolMetadata(tool)?.external?.readOnly === true).map((tool) => tool.name));
+	const isAllowed = (name) => allowed.has(name) || name.startsWith("mcp__") || [
+		"list_mcp_resources",
+		"list_mcp_resource_templates",
+		"read_mcp_resource"
+	].includes(name);
+	const inlineReads = tools.filter(isCodemodeCoreRead).map((tool) => tool.name);
+	const execution = new AsyncLocalStorage();
+	const original = createCodemodeExtension({
+		mode: "on",
+		models: false
+	});
+	const contextFor = (id, name, args) => {
+		const session = getSession();
+		const assistantMessage = session?.agent.state.messages.findLast((message) => message.role === "assistant");
+		if (!session || assistantMessage?.role !== "assistant") throw new Error("Codemode needs an active xopc turn");
+		return {
+			assistantMessage,
+			toolCall: {
+				type: "toolCall",
+				id,
+				name,
+				arguments: args
+			},
+			args,
+			context: {
+				messages: session.agent.state.messages,
+				tools: session.agent.state.tools
+			}
+		};
+	};
+	return (pi) => {
+		pi.on("tool_call", async (event) => {
+			if (!event.parentToolCallId) return;
+			const active = execution.getStore();
+			if (!active || active.parentId !== event.parentToolCallId || !isAllowed(event.toolName)) return {
+				block: true,
+				reason: "Codemode tool is not authorized"
+			};
+			active.signal.throwIfAborted();
+			return getSession()?.agent.beforeToolCall?.(contextFor(event.toolCallId, event.toolName, event.input), active.signal);
+		});
+		pi.on("tool_result", async (event) => {
+			if (!event.parentToolCallId) return;
+			const active = execution.getStore();
+			if (!active || active.parentId !== event.parentToolCallId) return {
+				content: [{
+					type: "text",
+					text: "Codemode execution is no longer active"
+				}],
+				isError: true
+			};
+			try {
+				return await getSession()?.agent.afterToolCall?.({
+					...contextFor(event.toolCallId, event.toolName, event.input),
+					result: {
+						content: event.content,
+						details: event.details,
+						structuredContent: event.structuredContent,
+						usage: event.usage
+					},
+					isError: event.isError
+				}, active.signal);
+			} catch {
+				return {
+					content: [{
+						type: "text",
+						text: "Codemode result policy failed"
+					}],
+					details: {},
+					isError: true
+				};
+			}
+		});
+		return original({
+			...pi,
+			appendEntry(customType, data) {
+				if (customType !== "codemode-store") throw new Error("Unsupported Codemode entry");
+				const active = execution.getStore();
+				if (!active || active.signal.aborted) throw new Error("Codemode execution is no longer active");
+				if (Buffer.byteLength(JSON.stringify(data)) > MAX_STORE_BYTES) throw new Error("Codemode store writes exceed 64 KiB");
+				const state = Object.create(null);
+				const apply = (value) => {
+					const writes = value;
+					for (const key of writes.delete ?? []) delete state[key];
+					Object.assign(state, writes.set ?? {});
+				};
+				for (const entry of active.ctx.sessionManager.getBranch()) if (entry.type === "custom" && entry.customType === customType) apply(entry.data);
+				apply(data);
+				if (Object.keys(state).length > 64 || Buffer.byteLength(JSON.stringify(state)) > MAX_STORE_BYTES) throw new Error("Codemode store exceeds 64 keys or 64 KiB");
+				pi.appendEntry(customType, data);
+			},
+			registerTool(definition) {
+				const prepare = definition.prepareLoadout;
+				pi.registerTool({
+					...definition,
+					prepareLoadout(loadout) {
+						const changes = prepare?.({
+							...loadout,
+							callable: loadout.callable.filter((tool) => isAllowed(tool.name))
+						});
+						return {
+							...changes,
+							descriptions: {
+								...changes?.descriptions,
+								codemode: `${changes?.descriptions?.codemode ?? definition.description}\n\nCore reads: ${inlineReads.join(", ") || "(none)"}. Host-approved deferred reads and native MCP tools can be found with searchTools(). Host limits: ${policy.timeoutMs}ms, ${policy.maxConcurrentCalls} concurrent calls, ${policy.maxCalls} calls, ${policy.maxOutputTokens} estimated output tokens. Store: 64 keys / 64 KiB. Models APIs are unavailable.`
+							}
+						};
+					},
+					async execute(id, params, signal, onUpdate, ctx) {
+						if (!ctx) throw new Error("Codemode needs an active session");
+						const input = params;
+						if (Buffer.byteLength(input.code) > MAX_SOURCE_BYTES) throw new Error("Codemode source exceeds 64 KiB");
+						const source = boundCodemodeSource(input.code, policy);
+						const deadline = AbortSignal.timeout(policy.timeoutMs);
+						const budgetAbort = new AbortController();
+						const combined = AbortSignal.any([
+							deadline,
+							budgetAbort.signal,
+							...signal ? [signal] : []
+						]);
+						let calls = 0;
+						let running = 0;
+						const waiting = /* @__PURE__ */ new Set();
+						const boundedContext = {
+							...ctx,
+							tools: ctx.tools.filter((tool) => isAllowed(tool.name)),
+							async executeTool(name, args, options) {
+								if (!isAllowed(name)) throw new Error(`Codemode tool ${name} is not authorized`);
+								if (++calls > policy.maxCalls) {
+									const error = /* @__PURE__ */ new Error(`Codemode exceeds ${policy.maxCalls} calls`);
+									budgetAbort.abort(error);
+									throw error;
+								}
+								const callSignal = options?.signal ? AbortSignal.any([combined, options.signal]) : combined;
+								while (running >= policy.maxConcurrentCalls) {
+									callSignal.throwIfAborted();
+									await new Promise((resolve) => {
+										const wake = () => {
+											waiting.delete(wake);
+											callSignal.removeEventListener("abort", wake);
+											resolve();
+										};
+										waiting.add(wake);
+										callSignal.addEventListener("abort", wake, { once: true });
+									});
+								}
+								callSignal.throwIfAborted();
+								running++;
+								try {
+									return await execution.run({
+										parentId: id,
+										signal: callSignal,
+										ctx
+									}, () => ctx.executeTool(name, args, {
+										...options,
+										signal: callSignal
+									}));
+								} finally {
+									running--;
+									waiting.values().next().value?.();
+								}
+							}
+						};
+						return execution.run({
+							parentId: id,
+							signal: combined,
+							ctx
+						}, () => withDataToolPermissions(allowed, async () => {
+							const result = await definition.execute(id, {
+								...params,
+								code: source
+							}, combined, onUpdate, boundedContext);
+							const details = result.details;
+							let outputPath;
+							if (details.fullOutputPath) try {
+								outputPath = await retainCodemodeOutput(ctx.cwd, details.fullOutputPath);
+							} catch {}
+							let remaining = policy.maxOutputTokens * 4;
+							const link = outputPath ? `Full Codemode output: ${outputPath}\n` : "";
+							const retainedLink = link.length <= remaining ? link : "";
+							remaining -= retainedLink.length;
+							const content = result.content.flatMap((block) => {
+								if (block.type === "image") {
+									if (block.data.length > remaining) return [];
+									remaining -= block.data.length;
+									return [block];
+								}
+								const text = block.text.replace(/\[Full output: [^\n]+\]/g, "").slice(0, remaining);
+								remaining -= text.length;
+								return text ? [{
+									type: "text",
+									text
+								}] : [];
+							});
+							details.fullOutputPath = outputPath;
+							return {
+								...result,
+								content: [...retainedLink ? [{
+									type: "text",
+									text: retainedLink
+								}] : [], ...content]
+							};
+						}));
+					}
+				});
+			}
+		});
+	};
+}
+function boundCodemodeSource(source, policy) {
+	const match = /^\s*\/\/\s*@options:\s*([^\r\n]*)(?:\r?\n|$)/.exec(source);
+	const options = match ? JSON.parse(match[1]) : {};
+	const clamp = (value, limit) => typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.min(Math.floor(value), limit) : limit;
+	return `// @options: ${JSON.stringify({
+		timeout_ms: clamp(options.timeout_ms, policy.timeoutMs),
+		max_output_tokens: clamp(options.max_output_tokens, policy.maxOutputTokens)
+	})}\n${match ? source.slice(match[0].length) : source}`;
+}
+//#endregion
+export { boundCodemodeSource, createXopcCodemodeExtension };

package/dist/src/agent/embedded/codemode-output.d.ts

@@ -0,0 +1,2 @@
+/** Adopt only pi's own spill file, never a path printed by a script or an MCP server. */
+export declare function retainCodemodeOutput(workspace: string, source: unknown): Promise<string | undefined>;

package/dist/src/agent/embedded/codemode-output.js

@@ -0,0 +1,34 @@
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { constants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { mkdir, open, realpath, writeFile } from "node:fs/promises";
+//#region src/agent/embedded/codemode-output.ts
+/** Adopt only pi's own spill file, never a path printed by a script or an MCP server. */
+async function retainCodemodeOutput(workspace, source) {
+	if (typeof source !== "string" || dirname(source) !== tmpdir() || !/^pi-codemode-[a-f0-9]{16}\.txt$/.test(basename(source))) return;
+	const handle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+	try {
+		const info = await handle.stat();
+		if (!info.isFile() || info.size > 64 * 1024 * 1024) throw new Error("Codemode output file exceeds 64 MiB");
+		const root = await realpath(workspace);
+		const directory = join(root, ".xopc", "codemode-output");
+		await mkdir(directory, {
+			recursive: true,
+			mode: 448
+		});
+		const resolved = await realpath(directory);
+		const location = relative(root, resolved);
+		if (location === ".." || location.startsWith(`..${sep}`) || location.startsWith(sep)) throw new Error("Codemode output directory escapes workspace");
+		const name = `${randomUUID()}.txt`;
+		await writeFile(join(resolved, name), await handle.readFile(), {
+			flag: "wx",
+			mode: 384
+		});
+		return `.xopc/codemode-output/${name}`;
+	} finally {
+		await handle.close();
+	}
+}
+//#endregion
+export { retainCodemodeOutput };

package/dist/src/agent/embedded/external-tool-discovery.d.ts

@@ -0,0 +1,6 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+/** Project the current host directory into pi; pi owns search and declaration loading. */
+export declare function materializeNativeExternalTools(params: {
+    conversationId: string;
+    tools: readonly AgentTool[];
+}): Promise<AgentTool[]>;

package/dist/src/agent/embedded/external-tool-discovery.js

@@ -0,0 +1,60 @@
+import { getEmbeddedExecutionRunId, runWithEmbeddedExecutionSession } from "./execution-context.js";
+import { parseExternalToolRef } from "../external-tools/refs.js";
+import { wrapToolsWithProtection } from "../tools/executor.js";
+import { setXopcToolMetadata } from "./tool-metadata.js";
+import { getExternalToolRegistry } from "../external-tools/tool-registry.js";
+import { createHash } from "node:crypto";
+//#region src/agent/embedded/external-tool-discovery.ts
+/** Project the current host directory into pi; pi owns search and declaration loading. */
+async function materializeNativeExternalTools(params) {
+	const registry = getExternalToolRegistry(params.tools);
+	if (!registry) return [];
+	return runWithEmbeddedExecutionSession(params.conversationId, async () => {
+		const descriptors = await registry.service.catalog(registry.nativeSources);
+		const names = new Set(params.tools.map((tool) => tool.name));
+		const refs = /* @__PURE__ */ new Map();
+		return wrapToolsWithProtection(descriptors.map((descriptor) => {
+			const parsed = parseExternalToolRef(descriptor.toolRef, descriptor.source);
+			if (!parsed) throw new Error("Invalid native tool identity");
+			const suffix = createHash("sha256").update(descriptor.toolRef).digest("hex").slice(0, 12);
+			const prefix = descriptor.source === "endpoint" ? "device" : descriptor.source;
+			const name = `${prefix}__${parsed.toolName.replace(/[^A-Za-z0-9_]/g, "_").slice(0, 40)}_${suffix}`;
+			if (names.has(name)) throw new Error(`Native tool identifier collision: ${name}`);
+			names.add(name);
+			refs.set(name, descriptor.toolRef);
+			return setXopcToolMetadata({
+				name,
+				label: descriptor.title,
+				description: `${descriptor.description}\n${descriptor.summary}`,
+				parameters: descriptor.inputSchema,
+				execute(id, args, signal, update) {
+					return runWithEmbeddedExecutionSession(params.conversationId, () => registry.execute(id, {
+						toolRef: descriptor.toolRef,
+						revision: descriptor.revision,
+						arguments: args,
+						...descriptor.batchRead ? { readOnly: true } : {}
+					}, signal, update), getEmbeddedExecutionRunId());
+				}
+			}, {
+				exposure: descriptor.exposure === "model-only" ? "model-only" : "deferred",
+				namespace: {
+					name: `${prefix}__${createHash("sha256").update(parsed.namespace).digest("hex").slice(0, 12)}`,
+					description: descriptor.source === "endpoint" ? "Tools of the current authorized device" : descriptor.namespace
+				},
+				outputSchema: descriptor.outputSchema,
+				annotations: descriptor.annotations,
+				external: {
+					toolRef: descriptor.toolRef,
+					revision: descriptor.revision,
+					readOnly: descriptor.batchRead === true
+				},
+				...registry.subscribeInvalidation ? { subscribeInvalidation: (listener) => registry.subscribeInvalidation(params.conversationId, descriptor.toolRef, listener) } : {}
+			});
+		}), {
+			...registry.executorConfig,
+			resolveTimeoutMs: (name) => registry.executorConfig?.resolveTimeoutMs?.(refs.get(name) ?? name) ?? registry.executorConfig?.resolveTimeoutMs?.("xopc_tool_execute")
+		});
+	}, getEmbeddedExecutionRunId());
+}
+//#endregion
+export { materializeNativeExternalTools };

package/dist/src/agent/embedded/model-runtime.js

@@ -1,8 +1,9 @@
 import { init_paths, resolveModelsJsonPath } from "../../config/paths.js";
+import { init_register_bundled_oauth_flows, registerBundledOAuthFlows } from "../../providers/register-bundled-oauth-flows.js";
+import { assertCurrentModelProvider, init_provider_policy } from "../../providers/provider-policy.js";
 import { CredentialResolver, init_credentials } from "../../auth/credentials.js";
 import { init_sync_provider_auth, resolveProviderApiKeySync } from "../../auth/sync-provider-auth.js";
 import { XopcModelCredentialStore, init_model_credential_store } from "../../auth/model-credential-store.js";
-import { init_register_bundled_oauth_flows, registerBundledOAuthFlows } from "../../providers/register-bundled-oauth-flows.js";
 import { init_register_runtime_providers, registerRuntimeProviders } from "../../providers/register-runtime-providers.js";
 import { getApiKeySync, init_providers } from "../../providers/index.js";
 import { InMemoryModelsStore } from "@earendil-works/pi-ai";
@@ -15,10 +16,12 @@ init_paths();
 init_providers();
 init_register_bundled_oauth_flows();
 init_register_runtime_providers();
+init_provider_policy();
 function resolveEmbeddedProviderApiKeySync(providerId) {
 	return resolveProviderApiKeySync(providerId) ?? getApiKeySync(providerId);
 }
 async function createEmbeddedModelRuntime(providerId) {
+	assertCurrentModelProvider(providerId);
 	registerBundledOAuthFlows();
 	const resolver = new CredentialResolver();
 	const credentials = new XopcModelCredentialStore(resolver);
@@ -30,7 +33,7 @@ async function createEmbeddedModelRuntime(providerId) {
 	registerRuntimeProviders(modelRuntime);
 	const runtimeProvider = modelRuntime.getProvider(providerId);
 	const storedCredential = await credentials.read(providerId);
-	if (!(runtimeProvider?.auth.oauth && storedCredential?.type === "oauth")) {
+	if (await resolver.resolveApiKeySource(providerId) !== "oauth" || !(runtimeProvider?.auth.oauth && storedCredential?.type === "oauth")) {
 		const key = await resolver.resolveApiKey(providerId) ?? getApiKeySync(providerId);
 		if (key && key !== "extension-managed") await modelRuntime.setRuntimeApiKey(providerId, key);
 	}

package/dist/src/agent/embedded/run-for-session.js

@@ -10,6 +10,7 @@ import { isPersonalConversation } from "../../personal-agent/repository.js";
 import { runWithEmbeddedExecutionSession } from "./execution-context.js";
 import { resolveAgentTurnTimeoutMs } from "../orchestration/run-agent-turn-with-timeout.js";
 import { resolvePromptCachePolicy } from "../../providers/prompt-cache-plan.js";
+import { prepareNativeMcpConfig } from "../mcp/native-mcp.js";
 import { evaluateContextBudget } from "../memory/context-budget.js";
 import { assessContext, recoverContext as recoverContext$1 } from "../memory/context-recovery.js";
 import { resolveCompactionPolicy } from "../memory/compaction-policy.js";
@@ -18,6 +19,7 @@ import { projectTurnOutcome } from "../../session/turn-outcome-projector.js";
 import { voicePresentationPrompt } from "../prompt/voice-presentation.js";
 import { applyStartupContextToUserMessage } from "../reply/apply-turn-user-enrichment.js";
 import { AgentRunSupervisor } from "../orchestration/agent-run-supervisor.js";
+import { materializeNativeExternalTools } from "./external-tool-discovery.js";
 import crypto from "node:crypto";
 //#region src/agent/embedded/run-for-session.ts
 init_src();
@@ -124,7 +126,7 @@ async function runEmbeddedTurnForSessionInner(params) {
 		if (typeof mm.applyResolvedModel === "function") mm.applyResolvedModel(agent, model, modelRef);
 		else await mm.applyModelForSession(agent, conversationId);
 		agentManager.setModelForSession(conversationId, modelRef);
-		const tools = agent.state.tools;
+		const tools = [...agent.state.tools];
 		const turnPolicy = agentManager.createAgentTurnPolicy(conversationId);
 		const systemPrompt = appendDynamicPromptSection([agent.state.systemPrompt ?? "", params.presentation === "voice" ? voicePresentationPrompt : ""].filter(Boolean).join("\n\n"), params.dynamicSystemContext ?? "");
 		const idlePolicy = resolveCompactionPolicy(config);
@@ -164,6 +166,11 @@ async function runEmbeddedTurnForSessionInner(params) {
 		};
 		const thinkingLevel = params.thinkingOverride ?? agent.state.thinkingLevel;
 		const workspaceDir = agentManager.getResolvedWorkspaceForSession(conversationId);
+		tools.push(...await materializeNativeExternalTools({
+			conversationId,
+			tools
+		}));
+		const mcp = config ? await prepareNativeMcpConfig(config, workspaceDir) : void 0;
 		const promptCachePolicy = resolvePromptCachePolicy(config ? resolveEffectiveAgentProfileForSession(conversationId).config.runtime.promptCache : void 0);
 		let userMessageForTurn = userMessage;
 		if (params.applyStartupContext !== false) {
@@ -263,6 +270,8 @@ async function runEmbeddedTurnForSessionInner(params) {
 					tools,
 					systemPrompt,
 					thinkingLevel,
+					codemode: config ? resolveEffectiveAgentProfileForSession(conversationId).config.runtime.codemode : void 0,
+					mcp,
 					promptCachePolicy,
 					compactionPolicy: resolveCompactionPolicy(config),
 					workspaceDir,

package/dist/src/agent/embedded/run-turn.js

@@ -10,6 +10,7 @@ import { setTraceIdentity, traceOperation, traceRun, traceTools } from "../../ob
 import { resolveEffectiveAgentConfigForSession } from "../../config/agent-profile.js";
 import { continuesAfterTool, trackAiUsageStream } from "../../usage/recorder.js";
 import { runWithEmbeddedExecutionSession } from "./execution-context.js";
+import { externalPolicyContext } from "./tool-metadata.js";
 import { isComputerControlActive, isComputerLeaseTool, stopComputerControl } from "../../computer/control-guard.js";
 import { EmbeddedRunConflictError, abortEmbeddedRun, acquireEmbeddedRunLease, queueEmbeddedSteer } from "./runs.js";
 import { lastAssistantPlainText, subscribeEmbeddedSessionEvents } from "./subscribe-session.js";
@@ -282,6 +283,8 @@ async function runXopcEmbeddedTurnInner(params) {
 			model: resolvedModel,
 			modelRef: params.modelRef,
 			tools,
+			codemode: params.codemode,
+			mcp: params.mcp,
 			systemPrompt: [systemPrompt, rootInstructions].filter(Boolean).join("\n\n"),
 			thinkingLevel: configuredThinking ?? thinkingLevel ?? "medium",
 			transcriptRuntime
@@ -529,7 +532,7 @@ async function runXopcEmbeddedTurnInner(params) {
 				reason: "Waiting for the user to answer.",
 				terminate: true
 			};
-			const decision = await params.turnPolicy?.beforeToolCall(context, signal);
+			const decision = await params.turnPolicy?.beforeToolCall(externalPolicyContext(context, tools), signal);
 			if (decision?.block) {
 				policyStopped ||= decision.terminate === true;
 				return decision;
@@ -561,10 +564,13 @@ async function runXopcEmbeddedTurnInner(params) {
 				text: scoped
 			});
 			await params.turnPolicy?.afterToolCall({
-				...context,
+				...externalPolicyContext(context, tools),
 				...checked
 			});
-			return checked;
+			return {
+				...checked.result,
+				isError: checked.isError
+			};
 		};
 		const baseFinishTurn = session.agent.finishTurn;
 		session.agent.finishTurn = async (context, signal) => {
@@ -675,6 +681,7 @@ async function runXopcEmbeddedTurnInner(params) {
 			});
 			if (runAbortSignal.aborted) return {
 				ok: false,
+				retryable: false,
 				errorMessage: "aborted"
 			};
 			if (isAssistantTurnAborted(session.agent)) return {

package/dist/src/agent/embedded/session-runner.d.ts

@@ -1,9 +1,10 @@
 import type { AgentTool } from '@earendil-works/pi-agent-core';
 import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
-import { type AgentSession } from '@earendil-works/pi-coding-agent';
+import { type LoadedMcpConfig, type AgentSession } from '@earendil-works/pi-coding-agent';
 import type { Model, Api } from '@earendil-works/pi-ai';
 import { type GuardedPiTranscriptManager } from './session-tool-result-guard.js';
 import type { EmbeddedTranscriptRuntime } from './transcript-runtime.js';
+import { type CodemodePolicy } from './codemode-extension.js';
 export type EmbeddedRunnerFingerprintInput = {
     transcriptId: string;
     workspaceDir: string;
@@ -13,6 +14,8 @@ export type EmbeddedRunnerFingerprintInput = {
     systemPrompt: string;
     thinkingLevel: string;
     credentialRevision: string;
+    codemode?: CodemodePolicy;
+    mcp?: LoadedMcpConfig;
 };
 export declare function buildEmbeddedRunnerFingerprint(input: EmbeddedRunnerFingerprintInput): string;
 export type AcquireEmbeddedSessionRunnerParams = {
@@ -25,6 +28,8 @@ export type AcquireEmbeddedSessionRunnerParams = {
     systemPrompt: string;
     thinkingLevel: ThinkingLevel;
     transcriptRuntime: EmbeddedTranscriptRuntime;
+    codemode?: CodemodePolicy;
+    mcp?: LoadedMcpConfig;
 };
 export type AcquiredEmbeddedSessionRunner = {
     session: AgentSession;
@@ -51,6 +56,8 @@ export interface EmbeddedSessionRunnerPoolOptions {
  * Owns the per-runtime pool of pi `AgentSession` runners.
  */
 export declare class EmbeddedSessionRunnerPool {
+    private readonly shutdowns;
+    drainShutdowns(): Promise<void>;
     private readonly pool;
     private readonly isEnabledFn;
     private readonly getIdleTtlMsFn;
@@ -72,3 +79,4 @@ export declare function resetEmbeddedSessionRunnerForTest(): void;
 export declare function evictEmbeddedSessionRunner(runtimeId: string, reason?: string): void;
 export declare function evictAllEmbeddedSessionRunners(reason?: string): void;
 export declare function acquireEmbeddedSessionRunner(params: AcquireEmbeddedSessionRunnerParams): Promise<AcquiredEmbeddedSessionRunner>;
+export declare function drainEmbeddedSessionRunnerShutdowns(): Promise<void>;