@xopcai/xopc 0.0.368 → 0.0.370

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>;

package/dist/src/agent/embedded/session-runner.js

@@ -1,15 +1,28 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { isCodemodeCoreRead } from "../tools/codemode-permissions.js";
+import { deferredToolContract, getXopcToolMetadata } from "./tool-metadata.js";
+import { abortEmbeddedRun } from "./runs.js";
 import { guardSessionManager } from "./session-tool-result-guard.js";
 import { transformUserMessageForPersistence } from "../inbound/attachment-pipeline.js";
 import { createEmbeddedModelRuntime, resolveEmbeddedProviderApiKeySync } from "./model-runtime.js";
 import { wrapStreamFnForXopcExtensions } from "./xopc-stream-bridge.js";
 import { xopcToolsToDefinitions } from "./xopc-tools-bridge.js";
-import { applySystemPromptOverrideToSession } from "./system-prompt-override.js";
+import { createXopcCodemodeExtension } from "./codemode-extension.js";
+import { TOOL_DISCOVERY_STATE, createXopcToolSearchExtension } from "./tool-search-extension.js";
+import { getNativePiAgentDir } from "../mcp/native-mcp.js";
+import { join } from "node:path";
 import { createHash } from "node:crypto";
-import { DefaultResourceLoader, SettingsManager, createAgentSession, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { DefaultResourceLoader, SettingsManager, createAgentSession, createMcpExtension } from "@earendil-works/pi-coding-agent";
 //#region src/agent/embedded/session-runner.ts
 init_logger();
+const toolContract = (tool) => JSON.stringify([
+	tool.name,
+	tool.parameters,
+	tool.description,
+	isCodemodeCoreRead(tool),
+	getXopcToolMetadata(tool)
+]);
 const log = createLogger("EmbeddedSessionRunner");
 const DEFAULT_IDLE_TTL_MS = 5 * 6e4;
 function providerCredentialRevision(providerId) {
@@ -26,7 +39,9 @@ function buildEmbeddedRunnerFingerprint(input) {
 		[...input.toolContracts].sort().join("\0"),
 		input.systemPrompt,
 		input.thinkingLevel,
-		input.credentialRevision
+		input.credentialRevision,
+		JSON.stringify(input.codemode ?? null),
+		JSON.stringify(input.mcp ?? null)
 	].join("\0")).digest("base64url");
 }
 function isEmbeddedSessionRunnerEnabled() {
@@ -41,7 +56,10 @@ function getEmbeddedSessionRunnerIdleTtlMs() {
 	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_IDLE_TTL_MS;
 }
 function createEmbeddedSettingsManager(cwd) {
-	const sm = SettingsManager.inMemory({ compaction: { enabled: false } });
+	const sm = SettingsManager.inMemory({
+		compaction: { enabled: false },
+		retry: { enabled: false }
+	});
 	sm.setCompactionEnabled(false);
 	return sm;
 }
@@ -49,6 +67,10 @@ function createEmbeddedSettingsManager(cwd) {
 * Owns the per-runtime pool of pi `AgentSession` runners.
 */
 var EmbeddedSessionRunnerPool = class {
+	shutdowns = /* @__PURE__ */ new Set();
+	async drainShutdowns() {
+		await Promise.allSettled([...this.shutdowns]);
+	}
 	pool = /* @__PURE__ */ new Map();
 	isEnabledFn;
 	getIdleTtlMsFn;
@@ -69,8 +91,7 @@ var EmbeddedSessionRunnerPool = class {
 		};
 	}
 	resetForTest() {
-		for (const entry of this.pool.values()) this.clearIdleTimer(entry);
-		this.pool.clear();
+		this.evictAll("test_reset");
 		this.stats = {
 			acquires: 0,
 			reuses: 0,
@@ -93,10 +114,12 @@ var EmbeddedSessionRunnerPool = class {
 			workspaceDir: params.workspaceDir,
 			modelRef: params.modelRef,
 			toolNames: params.tools.map((t) => t.name),
-			toolContracts: params.tools.map((tool) => JSON.stringify([tool.name, tool.parameters])),
+			toolContracts: params.tools.map(toolContract),
 			systemPrompt: params.systemPrompt,
 			thinkingLevel: params.thinkingLevel ?? "medium",
-			credentialRevision: providerCredentialRevision(params.model.provider)
+			credentialRevision: providerCredentialRevision(params.model.provider),
+			codemode: params.codemode,
+			mcp: params.mcp
 		});
 		const reuseEnabled = this.isEnabledFn();
 		const existing = this.pool.get(params.runtimeId);
@@ -108,7 +131,6 @@ var EmbeddedSessionRunnerPool = class {
 			entry.lastUsedAt = Date.now();
 			reused = true;
 			this.stats.reuses += 1;
-			applySystemPromptOverrideToSession(entry.session, params.systemPrompt);
 			entry.session.agent.streamFunction = entry.baseStreamFn;
 			log.debug({ runtimeId: params.runtimeId }, "Reusing pooled embedded session runner");
 		} else {
@@ -148,11 +170,33 @@ var EmbeddedSessionRunnerPool = class {
 	}
 	disposePooledRunner(runtimeId, entry, reason) {
 		this.clearIdleTimer(entry);
+		for (const release of entry.releaseInvalidations) release();
 		this.pool.delete(runtimeId);
 		this.stats.evictions += 1;
-		try {
-			entry.piSm.flushPendingToolResults?.();
-		} catch {}
+		const shutdown = Promise.resolve(entry.session.abort?.()).catch((err) => {
+			log.warn({
+				err,
+				runtimeId
+			}, "Embedded runner abort failed");
+		}).then(async () => {
+			try {
+				await entry.session.extensionRunner?.emit({
+					type: "session_shutdown",
+					reason: "quit"
+				});
+			} finally {
+				try {
+					entry.piSm.flushPendingToolResults?.();
+				} finally {
+					entry.session.dispose?.();
+				}
+			}
+		}).catch((err) => log.warn({
+			err,
+			runtimeId
+		}, "Embedded runner disposal failed"));
+		this.shutdowns.add(shutdown);
+		shutdown.finally(() => this.shutdowns.delete(shutdown));
 		log.debug({
 			runtimeId,
 			reason
@@ -163,17 +207,46 @@ var EmbeddedSessionRunnerPool = class {
 		const settingsManager = createEmbeddedSettingsManager(workspaceDir);
 		const piSm = guardSessionManager(params.transcriptRuntime.openSessionManager(workspaceDir), {
 			conversationId: params.transcriptRuntime.persistent ? runtimeId : void 0,
+			persistCustomTypes: ["codemode-store", TOOL_DISCOVERY_STATE],
 			contextWindowTokens: model.contextWindow ?? 128e3,
 			transformMessageForPersistence: params.transcriptRuntime.persistent ? (message) => transformUserMessageForPersistence(runtimeId, message) : void 0
 		});
 		const toolDefs = xopcToolsToDefinitions(tools);
-		const toolNames = tools.map((t) => t.name);
+		const toolNames = tools.filter((tool) => getXopcToolMetadata(tool)?.exposure !== "deferred").map((tool) => tool.name);
+		const discoveryState = piSm.getBranch().findLast((entry) => entry.type === "custom" && entry.customType === "xopc-tool-discovery");
+		const saved = discoveryState?.type === "custom" ? discoveryState.data : void 0;
+		const restored = new Map((saved?.loaded ?? []).map((tool) => [tool.name, tool.contract]));
+		toolNames.push(...tools.filter((tool) => getXopcToolMetadata(tool)?.exposure === "deferred" && restored.get(tool.name) === deferredToolContract(tool)).map((tool) => tool.name));
+		let boundSession;
+		const mcp = params.mcp;
+		const hasMcp = Boolean(mcp?.servers.length);
+		const usesMcpCodemode = mcp?.servers.some((server) => server.config.enabled !== false && [server.config.exposure ?? "codemode", ...Object.values(server.config.toolExposure ?? {})].includes("codemode"));
+		const codemode = params.codemode?.enabled ? params.codemode : usesMcpCodemode ? {
+			enabled: true,
+			timeoutMs: 6e4,
+			maxConcurrentCalls: 4,
+			maxCalls: 32,
+			maxOutputTokens: 4e3
+		} : void 0;
+		if (codemode) toolNames.push("codemode");
+		const discovery = hasMcp || tools.some((tool) => getXopcToolMetadata(tool)?.exposure === "deferred");
+		if (discovery) toolNames.push("tool_search");
 		const modelRuntime = await createEmbeddedModelRuntime(model.provider);
 		const resourceLoader = new DefaultResourceLoader({
 			cwd: workspaceDir,
-			agentDir: getAgentDir(),
+			agentDir: getNativePiAgentDir(),
 			settingsManager,
-			noContextFiles: true
+			systemPrompt,
+			noContextFiles: true,
+			noExtensions: true,
+			extensionFactories: [
+				...codemode ? [createXopcCodemodeExtension(codemode, tools, () => boundSession)] : [],
+				...discovery ? [createXopcToolSearchExtension(tools)] : [],
+				...mcp ? [createMcpExtension({
+					loadConfig: () => mcp,
+					logPath: join(getNativePiAgentDir(), "mcp.log")
+				})] : []
+			]
 		});
 		await resourceLoader.reload();
 		const { session } = await createAgentSession({
@@ -185,10 +258,11 @@ var EmbeddedSessionRunnerPool = class {
 			modelRuntime,
 			resourceLoader,
 			noTools: "builtin",
-			customTools: toolDefs,
-			tools: toolNames
+			customTools: toolDefs
 		});
-		applySystemPromptOverrideToSession(session, systemPrompt);
+		boundSession = session;
+		session.setActiveToolsByName(toolNames);
+		if (codemode || discovery || mcp) await session.bindExtensions({});
 		const baseStreamFn = wrapStreamFnForXopcExtensions(session.agent.streamFunction);
 		session.agent.streamFunction = baseStreamFn;
 		return {
@@ -197,18 +271,29 @@ var EmbeddedSessionRunnerPool = class {
 				transcriptId,
 				workspaceDir,
 				modelRef: params.modelRef,
-				toolNames,
-				toolContracts: tools.map((tool) => JSON.stringify([tool.name, tool.parameters])),
+				toolNames: tools.map((tool) => tool.name),
+				toolContracts: tools.map(toolContract),
 				systemPrompt,
 				thinkingLevel: thinkingLevel ?? "medium",
-				credentialRevision: providerCredentialRevision(model.provider)
+				credentialRevision: providerCredentialRevision(model.provider),
+				codemode: params.codemode,
+				mcp: params.mcp
 			}),
 			session,
 			piSm,
 			settingsManager,
 			baseStreamFn,
 			lastUsedAt: Date.now(),
-			idleTimer: null
+			idleTimer: null,
+			releaseInvalidations: tools.flatMap((tool) => {
+				const subscribe = getXopcToolMetadata(tool)?.subscribeInvalidation;
+				if (!subscribe) return [];
+				return [subscribe(() => {
+					if (this.pool.get(runtimeId)?.session !== session) return;
+					abortEmbeddedRun(runtimeId);
+					this.evict(runtimeId, "external_tool_catalog_changed");
+				})];
+			})
 		};
 	}
 };
@@ -228,5 +313,8 @@ function evictAllEmbeddedSessionRunners(reason = "dispose_all") {
 function acquireEmbeddedSessionRunner(params) {
 	return defaultEmbeddedSessionRunnerPool.acquire(params);
 }
+function drainEmbeddedSessionRunnerShutdowns() {
+	return defaultEmbeddedSessionRunnerPool.drainShutdowns();
+}
 //#endregion
-export { EmbeddedSessionRunnerPool, acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, defaultEmbeddedSessionRunnerPool, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, isEmbeddedSessionRunnerEnabled, resetEmbeddedSessionRunnerForTest };
+export { EmbeddedSessionRunnerPool, acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, defaultEmbeddedSessionRunnerPool, drainEmbeddedSessionRunnerShutdowns, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, isEmbeddedSessionRunnerEnabled, resetEmbeddedSessionRunnerForTest };

package/dist/src/agent/embedded/session-tool-result-guard.d.ts

@@ -28,6 +28,7 @@ export type BeforeMessageWriteHookResult = {
     message?: AgentMessage;
 } | undefined;
 export interface ToolResultGuardOptions {
+    persistCustomTypes?: readonly string[];
     /** Optional session key for transcript update broadcasts. */
     conversationId?: string;
     /** Optional transform applied to any message before persistence. */
@@ -93,6 +94,7 @@ export declare function guardSessionManager(sessionManager: SessionManager, opts
     missingToolResultText?: string;
     allowedToolNames?: Iterable<string>;
     transformMessageForPersistence?: (message: AgentMessage) => AgentMessage;
+    persistCustomTypes?: readonly string[];
 }): GuardedPiTranscriptManager;
 /**
  * Recover the original (un-guarded) appendMessage for a session manager.

package/dist/src/agent/embedded/session-tool-result-guard.js

@@ -32,6 +32,7 @@ function guardSessionManager(sessionManager, opts) {
 	if (typeof sessionManager.flushPendingToolResults === "function") return sessionManager;
 	const result = installSessionToolResultGuard(sessionManager, {
 		conversationId: opts?.conversationId,
+		persistCustomTypes: opts?.persistCustomTypes,
 		transformMessageForPersistence: opts?.transformMessageForPersistence,
 		allowSyntheticToolResults: opts?.allowSyntheticToolResults,
 		missingToolResultText: opts?.missingToolResultText,
@@ -287,6 +288,22 @@ var ToolResultGuard = class {
 	attach() {
 		const bound = this.guardedAppend.bind(this);
 		this.sessionManager.appendMessage = bound;
+		if (this.opts.conversationId && this.opts.persistCustomTypes?.length) {
+			const appendCustom = this.sessionManager.appendCustomEntry.bind(this.sessionManager);
+			this.sessionManager.appendCustomEntry = (customType, data) => {
+				const id = appendCustom(customType, data);
+				if (this.opts.persistCustomTypes?.includes(customType)) emitSessionTranscriptUpdate({
+					conversationId: this.opts.conversationId,
+					customEntry: {
+						customType,
+						data,
+						timestamp: (/* @__PURE__ */ new Date()).toISOString()
+					},
+					messageId: id
+				});
+				return id;
+			};
+		}
 	}
 	setActiveTurnId(turnId) {
 		this.activeTurnId = normalizeOptionalString(turnId) ?? null;

package/dist/src/agent/embedded/subscribe-session.js

@@ -2,15 +2,21 @@ import { extractTextContent } from "../context/workspace.js";
 //#region src/agent/embedded/subscribe-session.ts
 function subscribeEmbeddedSessionEvents(session, onEvent, onAgentEvent) {
 	return session.subscribe((event) => {
+		if (event.type === "agent_settled") {
+			onEvent({
+				type: "agent_end",
+				aborted: event.aborted
+			});
+			return;
+		}
 		const base = event;
+		const parent = "parentToolCallId" in event && event.parentToolCallId ? { parentToolCallId: event.parentToolCallId } : {};
 		onAgentEvent?.(base);
 		switch (base.type) {
 			case "agent_start":
 				onEvent({ type: "agent_start" });
 				break;
-			case "agent_end":
-				onEvent({ type: "agent_end" });
-				break;
+			case "agent_end": break;
 			case "message_start": {
 				const m = base.message;
 				onEvent({
@@ -40,6 +46,7 @@ function subscribeEmbeddedSessionEvents(session, onEvent, onAgentEvent) {
 				const t = base;
 				onEvent({
 					type: "tool_execution_start",
+					...parent,
 					toolName: t.toolName,
 					toolCallId: t.toolCallId,
 					args: t.args
@@ -50,10 +57,12 @@ function subscribeEmbeddedSessionEvents(session, onEvent, onAgentEvent) {
 				const t = base;
 				onEvent({
 					type: "tool_execution_end",
+					...parent,
 					toolName: t.toolName,
 					toolCallId: t.toolCallId,
 					isError: t.isError,
-					result: t.result
+					result: t.result,
+					durationMs: t.durationMs
 				});
 				break;
 			}
@@ -61,6 +70,7 @@ function subscribeEmbeddedSessionEvents(session, onEvent, onAgentEvent) {
 				const t = base;
 				onEvent({
 					type: "tool_execution_update",
+					...parent,
 					toolName: t.toolName,
 					toolCallId: t.toolCallId,
 					args: t.args,

package/dist/src/agent/embedded/tool-metadata.d.ts

@@ -0,0 +1,15 @@
+import type { AgentTool, BeforeToolCallContext } from '@earendil-works/pi-agent-core';
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
+export type XopcToolMetadata = Pick<ToolDefinition, 'exposure' | 'namespace' | 'annotations' | 'outputSchema'> & {
+    external?: {
+        toolRef: string;
+        revision: string;
+        readOnly: boolean;
+    };
+    subscribeInvalidation?: (listener: () => void) => () => void;
+};
+export declare function setXopcToolMetadata(tool: AgentTool, metadata: XopcToolMetadata): AgentTool;
+export declare function getXopcToolMetadata(tool: AgentTool): XopcToolMetadata | undefined;
+export declare function deferredToolContract(tool: AgentTool): string;
+/** Deferred declarations retain the policy identity of the existing external gateway. */
+export declare function externalPolicyContext(context: BeforeToolCallContext, tools: readonly AgentTool[]): BeforeToolCallContext;

package/dist/src/agent/embedded/tool-metadata.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+//#region src/agent/embedded/tool-metadata.ts
+const metadataKey = Symbol("xopc.sdkToolMetadata");
+function setXopcToolMetadata(tool, metadata) {
+	return Object.assign(tool, { [metadataKey]: metadata });
+}
+function getXopcToolMetadata(tool) {
+	return Reflect.get(tool, metadataKey);
+}
+function deferredToolContract(tool) {
+	return createHash("sha256").update(JSON.stringify([
+		tool.name,
+		tool.description,
+		tool.parameters,
+		getXopcToolMetadata(tool)
+	])).digest("base64url");
+}
+/** Deferred declarations retain the policy identity of the existing external gateway. */
+function externalPolicyContext(context, tools) {
+	const tool = tools.find((candidate) => candidate.name === context.toolCall.name);
+	const external = tool && getXopcToolMetadata(tool)?.external;
+	if (!external) return context;
+	const args = {
+		...external,
+		arguments: context.args
+	};
+	return {
+		...context,
+		args,
+		toolCall: {
+			...context.toolCall,
+			name: "xopc_tool_execute",
+			arguments: args
+		}
+	};
+}
+//#endregion
+export { deferredToolContract, externalPolicyContext, getXopcToolMetadata, setXopcToolMetadata };

package/dist/src/agent/embedded/tool-search-extension.d.ts

@@ -0,0 +1,5 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import { type ExtensionFactory } from '@earendil-works/pi-coding-agent';
+export declare const TOOL_DISCOVERY_STATE = "xopc-tool-discovery";
+/** xopc deliberately excludes pi system declarations from SQLite; retain only discovery state. */
+export declare function createXopcToolSearchExtension(tools: readonly AgentTool[]): ExtensionFactory;