@xopcai/xopc 0.0.285 → 0.0.291

package/dist/src/agent/agent-manager.js

@@ -7,16 +7,17 @@ import { getInteractionState } from "../storage/sqlite/interaction-state-reposit
 import { getSessionMetadata } from "../storage/sqlite/session-repository.js";
 import "../storage/sqlite/index.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
-import { applyConfigOverrides } from "../config/runtime-overrides.js";
 import { expandWorkspacePathString, init_workspace_path } from "../config/workspace-path.js";
 import { init_agent_scope, resolveAgentProfileDir } from "./agent-scope.js";
-import { init_session_key, parseSessionKey } from "../routing/session-key.js";
-import { resolveEffectiveAgentProfile, resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { init_paths, resolveBundledSkillsDir } from "../config/paths.js";
-import { init_sync_provider_auth, resolveProviderApiKeySync } from "../auth/sync-provider-auth.js";
 import { CredentialResolver, init_credentials } from "../auth/credentials.js";
+import { getConversationRouting } from "../storage/sqlite/conversation-repository.js";
+import { init_session_key } from "../routing/session-key.js";
+import { init_sync_provider_auth, resolveProviderApiKeySync } from "../auth/sync-provider-auth.js";
 import { getApiKeySync, getDefaultModelSync, init_providers, resolveModel } from "../providers/index.js";
 import { createExtensionAwareStreamFn } from "../providers/extension-stream-bridge.js";
+import { applyConfigOverrides } from "../config/runtime-overrides.js";
+import { resolveEffectiveAgentProfile, resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { extractTextContent } from "./context/workspace.js";
 import { buildExecutionScopeContextForPrompt } from "./context/execution-scope.js";
 import { clearBootstrapSnapshot } from "./bootstrap/bootstrap-cache.js";
@@ -25,7 +26,7 @@ import { loadProjectAgentsContextFile } from "./bootstrap/project-agents-context
 import { getEmbeddedExecutionRunId } from "./embedded/execution-context.js";
 import { parseExternalToolRef } from "./external-tools/refs.js";
 import { mcpToolPolicyId } from "./mcp/bundle-mcp-policy.js";
-import { disposeAllSessionMcpRuntimes, retireSessionMcpRuntimeForSessionKey } from "./mcp/bundle-mcp-runtime.js";
+import { disposeAllSessionMcpRuntimes, retireSessionMcpRuntimeForConversationId } from "./mcp/bundle-mcp-runtime.js";
 import { createSkillConfigManager, isSkillEnabled, resolveSkillConfig } from "./skills/config.js";
 import { isValidSkillEnvVarName } from "./skills/required-env-vars.js";
 import { resolveWorkspaceSkillsDir, resolveWorkspaceSkillsLockPath } from "./skills/workspace-skills-dir.js";
@@ -138,7 +139,7 @@ var AgentManager = class {
 		});
 		this.executionContext = new ExecutionContextCoordinator({
 			getConfig: () => this.config.config,
-			getAccessForSession: (sessionKey) => resolveUserContextSessionAccess(this.config.config, sessionKey),
+			getAccessForSession: (conversationId) => resolveUserContextSessionAccess(this.config.config, conversationId),
 			getWorkspaceIdForSession: (sk) => this.getResolvedWorkspaceForSession(sk),
 			getProjectIdForSession: (sk) => getSessionMetadata(sk)?.projectId
 		});
@@ -154,8 +155,8 @@ var AgentManager = class {
 			}, `Credential cache pre-warm failed: ${em}`);
 		});
 	}
-	isUserContextEnabledForSession(sessionKey) {
-		return resolveUserContextSessionAccess(this.config.config, sessionKey).userModel;
+	isUserContextEnabledForSession(conversationId) {
+		return resolveUserContextSessionAccess(this.config.config, conversationId).userModel;
 	}
 	computeBaseWorkspacePath() {
 		const cfg = this.config.config;
@@ -166,27 +167,27 @@ var AgentManager = class {
 	* Workspace root for inbound attachments / side effects for this session's agent id.
 	* Uses in-memory session workspace overrides when the session has a persisted `workingDirectoryOverride`.
 	*/
-	getResolvedWorkspaceForSession(sessionKey) {
+	getResolvedWorkspaceForSession(conversationId) {
 		const cfg = this.config.config;
-		const fromMap = this.sessionWorkspaceOverrides.get(sessionKey);
+		const fromMap = this.sessionWorkspaceOverrides.get(conversationId);
 		if (fromMap !== void 0) return fromMap;
-		return resolveEffectiveAgentProfileForSession(cfg, sessionKey).resolvedWorkspacePath;
+		return resolveEffectiveAgentProfileForSession(cfg, conversationId).resolvedWorkspacePath;
 	}
-	getWorkspaceRuntimeForSession(sessionKey) {
-		const profile = resolveEffectiveAgentProfileForSession(this.config.config, sessionKey);
-		const resolvedPath = sessionKey ? this.getResolvedWorkspaceForSession(sessionKey) : this.baseWorkspacePath;
+	getWorkspaceRuntimeForSession(conversationId) {
+		const profile = resolveEffectiveAgentProfileForSession(this.config.config, conversationId);
+		const resolvedPath = conversationId ? this.getResolvedWorkspaceForSession(conversationId) : this.baseWorkspacePath;
 		return this.workspaceRuntimes.getOrCreate(resolvedPath, profile.agentId);
 	}
 	getCurrentWorkspaceRuntime() {
-		return this.getWorkspaceRuntimeForSession(this.config.getCurrentContext?.()?.sessionKey);
+		return this.getWorkspaceRuntimeForSession(this.config.getCurrentContext?.()?.conversationId);
 	}
 	/**
 	* Sync in-memory workspace override from session config (after load or PATCH).
 	* Pass `null` to clear when the session has no `workingDirectoryOverride` on disk.
 	*/
-	setSessionWorkspaceOverride(sessionKey, absolutePath) {
-		if (absolutePath === null || absolutePath === "") this.sessionWorkspaceOverrides.delete(sessionKey);
-		else this.sessionWorkspaceOverrides.set(sessionKey, absolutePath);
+	setSessionWorkspaceOverride(conversationId, absolutePath) {
+		if (absolutePath === null || absolutePath === "") this.sessionWorkspaceOverrides.delete(conversationId);
+		else this.sessionWorkspaceOverrides.set(conversationId, absolutePath);
 	}
 	pickDefaultModelRef() {
 		const cfg = this.mergedConfig();
@@ -238,8 +239,8 @@ var AgentManager = class {
 			bus: this.config.bus,
 			toolExecutorConfig: { resolveTimeoutMs: (toolName) => {
 				const config = this.mergedConfig();
-				const sessionKey = this.config.getCurrentContext?.()?.sessionKey;
-				return resolveEffectiveAgentProfileForSession(config, sessionKey).config.tools[toolName]?.timeoutMs;
+				const conversationId = this.config.getCurrentContext?.()?.conversationId;
+				return resolveEffectiveAgentProfileForSession(config, conversationId).config.tools[toolName]?.timeoutMs;
 			} },
 			getConfig: () => this.mergedConfig(),
 			getPrimaryModel: () => this.resolveModelStringToModel(this.pickDefaultModelRef()),
@@ -258,8 +259,8 @@ var AgentManager = class {
 			getWorkflowRunService: this.config.getWorkflowRunService,
 			getSkillIndexingContext: () => {
 				const ctx = this.config.getCurrentContext?.();
-				if (!ctx?.sessionKey) return void 0;
-				const inst = this.agents.get(ctx.sessionKey);
+				if (!ctx?.conversationId) return void 0;
+				const inst = this.agents.get(ctx.conversationId);
 				if (!inst) return void 0;
 				return {
 					registeredToolNames: inst.registeredToolNames,
@@ -271,13 +272,13 @@ var AgentManager = class {
 			},
 			getSkillPassthroughEnvVarNames: () => {
 				const ctx = this.config.getCurrentContext?.();
-				if (!ctx?.sessionKey) return [];
-				return [...this.agents.get(ctx.sessionKey)?.skillEnvPassthroughKeys ?? []];
+				if (!ctx?.conversationId) return [];
+				return [...this.agents.get(ctx.conversationId)?.skillEnvPassthroughKeys ?? []];
 			},
 			registerSkillEnvPassthrough: (names) => {
 				const ctx = this.config.getCurrentContext?.();
-				if (!ctx?.sessionKey) return;
-				const inst = this.agents.get(ctx.sessionKey);
+				if (!ctx?.conversationId) return;
+				const inst = this.agents.get(ctx.conversationId);
 				if (!inst) return;
 				for (const n of names) if (isValidSkillEnvVarName(n)) inst.skillEnvPassthroughKeys.add(n.trim());
 			},
@@ -288,26 +289,26 @@ var AgentManager = class {
 	getMemoryManager() {
 		return this.getCurrentWorkspaceRuntime().memoryManager;
 	}
-	getMemoryManagerForSession(sessionKey) {
-		return this.getWorkspaceRuntimeForSession(sessionKey).memoryManager;
+	getMemoryManagerForSession(conversationId) {
+		return this.getWorkspaceRuntimeForSession(conversationId).memoryManager;
 	}
 	/** Build the bounded, policy-filtered context used for this model turn. */
-	prepareUserTurnContext(userMessage, sessionKey, turnId) {
-		return this.executionContext.prepare(userMessage, sessionKey, turnId);
+	prepareUserTurnContext(userMessage, conversationId, turnId) {
+		return this.executionContext.prepare(userMessage, conversationId, turnId);
 	}
 	/** Capture durable structured user context after a completed turn. */
-	async afterAgentTurn(sessionKey, userPlainText, turnId) {
-		if (!this.isUserContextEnabledForSession(sessionKey)) return void 0;
-		const parsed = parseSessionKey(sessionKey);
+	async afterAgentTurn(conversationId, userPlainText, turnId) {
+		if (!this.isUserContextEnabledForSession(conversationId)) return void 0;
+		const parsed = getConversationRouting(conversationId);
 		if (parsed && parsed.peerKind !== "direct") return void 0;
-		const instance = this.agents.get(sessionKey);
+		const instance = this.agents.get(conversationId);
 		if (!instance) return void 0;
 		return runTurnUserModelCapture({
-			sessionKey,
+			conversationId,
 			turnId,
 			userText: userPlainText,
 			mainAgent: instance.agent,
-			workspaceId: this.getResolvedWorkspaceForSession(sessionKey),
+			workspaceId: this.getResolvedWorkspaceForSession(conversationId),
 			getConfig: () => this.mergedConfig()
 		});
 	}
@@ -315,40 +316,40 @@ var AgentManager = class {
 	* Call once per user turn before the main embedded agent turn.
 	* Delegates to {@link BackgroundReviewCoordinator}.
 	*/
-	beginBackgroundReviewUserTurn(sessionKey) {
-		if (!this.agents.get(sessionKey) || !this.isUserContextEnabledForSession(sessionKey)) return;
-		this.backgroundReview.beginUserTurn(sessionKey);
+	beginBackgroundReviewUserTurn(conversationId) {
+		if (!this.agents.get(conversationId) || !this.isUserContextEnabledForSession(conversationId)) return;
+		this.backgroundReview.beginUserTurn(conversationId);
 	}
 	/** After a successful main turn, may run a quiet follow-up for context review and skills. */
-	scheduleBackgroundReviewAfterUserTurn(sessionKey) {
-		const inst = this.agents.get(sessionKey);
-		if (!inst || !this.isUserContextEnabledForSession(sessionKey)) return;
+	scheduleBackgroundReviewAfterUserTurn(conversationId) {
+		const inst = this.agents.get(conversationId);
+		if (!inst || !this.isUserContextEnabledForSession(conversationId)) return;
 		this.backgroundReview.scheduleAfterUserTurn({
-			sessionKey,
+			conversationId,
 			agent: inst.agent,
-			lastAssistantText: this.getLastAssistantContent(sessionKey),
-			workspaceId: this.getResolvedWorkspaceForSession(sessionKey)
+			lastAssistantText: this.getLastAssistantContent(conversationId),
+			workspaceId: this.getResolvedWorkspaceForSession(conversationId)
 		});
 	}
 	/**
 	* Expand `/skill:name` user text into the full skill block for the current turn (WebChat, channels).
 	*/
 	expandSkillUserText(text) {
-		const sessionKey = (this.config.getCurrentContext?.())?.sessionKey;
-		const inst = sessionKey ? this.agents.get(sessionKey) : void 0;
-		return this.getWorkspaceRuntimeForSession(sessionKey).skillManager.expandCommand(text, {
+		const conversationId = (this.config.getCurrentContext?.())?.conversationId;
+		const inst = conversationId ? this.agents.get(conversationId) : void 0;
+		return this.getWorkspaceRuntimeForSession(conversationId).skillManager.expandCommand(text, {
 			skillAllowlist: inst?.effectiveProfile.skillsAllowlist,
 			registeredToolNames: inst?.registeredToolNames
 		});
 	}
-	prepareSkillTurn(sessionKey, text) {
-		this.getOrCreateAgent(sessionKey);
-		const inst = this.agents.get(sessionKey);
+	prepareSkillTurn(conversationId, text) {
+		this.getOrCreateAgent(conversationId);
+		const inst = this.agents.get(conversationId);
 		if (!text.includes("/skill:")) return {
 			text,
 			activatedCapabilityNames: this.activeCapabilityNames(inst)
 		};
-		const rt = this.getWorkspaceRuntimeForSession(sessionKey);
+		const rt = this.getWorkspaceRuntimeForSession(conversationId);
 		const options = {
 			skillAllowlist: inst?.effectiveProfile.skillsAllowlist,
 			registeredToolNames: inst?.registeredToolNames
@@ -371,11 +372,11 @@ var AgentManager = class {
 			activatedCapabilityNames: [...new Set([...this.activeCapabilityNames(inst), ...turnOnlyCapabilities])]
 		};
 	}
-	async withSkillCapabilities(sessionKey, capabilityNames, run) {
+	async withSkillCapabilities(conversationId, capabilityNames, run) {
 		const requested = [...new Set(capabilityNames.map((name) => name.trim()).filter(Boolean))];
 		if (requested.length === 0) return run();
-		this.getOrCreateAgent(sessionKey);
-		const inst = this.agents.get(sessionKey);
+		this.getOrCreateAgent(conversationId);
+		const inst = this.agents.get(conversationId);
 		if (!inst) return run();
 		const activatedTools = this.toolsFactory.createCapabilityTools(requested, { disabledTools: inst.effectiveProfile.tools.denied });
 		const existingNames = new Set(inst.registeredToolNames);
@@ -397,19 +398,19 @@ var AgentManager = class {
 	}
 	buildSystemPromptForInstance(instance, registeredToolNames = instance.registeredToolNames, activeCapabilityNames = this.activeCapabilityNames(instance)) {
 		const cfg = this.config.config;
-		const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(instance.sessionKey);
+		const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(instance.conversationId);
 		const rt = this.workspaceRuntimes.getOrCreate(resolvedWorkspacePath, instance.effectiveProfile.agentId);
-		const contextFiles = this.resolveContextFilesForSession(instance.sessionKey, instance.effectiveProfile);
+		const contextFiles = this.resolveContextFilesForSession(instance.conversationId, instance.effectiveProfile);
 		const modelRef = instance.effectiveProfile.primaryModelRef?.trim() || this.defaultModel;
 		const thinkingLevel = instance.agent.state.thinkingLevel ?? this.config.thinkingLevel ?? "medium";
 		return rt.systemPromptBuilder.build(contextFiles, {
-			externalMemoryInstructions: this.buildExternalMemoryInstructions(instance.sessionKey, rt),
+			externalMemoryInstructions: this.buildExternalMemoryInstructions(instance.conversationId, rt),
 			workspaceOverride: resolvedWorkspacePath,
 			profileMarkdownPathRoot: resolveAgentProfileDir(cfg, instance.effectiveProfile.agentId),
 			customInstructions: instance.effectiveProfile.customInstructions,
 			skillAllowlist: instance.effectiveProfile.skillsAllowlist,
 			registeredToolNames,
-			sessionKey: instance.sessionKey,
+			conversationId: instance.conversationId,
 			modelRef,
 			agentId: instance.effectiveProfile.agentId,
 			thinkingLevel,
@@ -447,7 +448,7 @@ var AgentManager = class {
 			return false;
 		}
 	}
-	resolveContextFilesForSession(sessionKey, profile, excludeHeartbeat) {
+	resolveContextFilesForSession(conversationId, profile, excludeHeartbeat) {
 		const cfg = this.config.config;
 		const profileDir = resolveAgentProfileDir(cfg, profile.agentId);
 		const heartbeatEnabled = cfg.gateway?.heartbeat?.includeSystemPromptSection ?? false;
@@ -455,12 +456,12 @@ var AgentManager = class {
 		const { contextFiles } = resolveBootstrapContextSync({
 			profileDir,
 			config: cfg,
-			sessionKey,
+			conversationId,
 			excludeHeartbeat: excludeHeartbeat ?? !heartbeatEnabled,
 			contextInjection
 		});
 		const shouldAppendProjectContext = contextInjection === "always" || contextInjection === "continuation-skip" && contextFiles.length > 0;
-		const workspaceDir = this.getResolvedWorkspaceForSession(sessionKey);
+		const workspaceDir = this.getResolvedWorkspaceForSession(conversationId);
 		if (shouldAppendProjectContext && this.isProjectWorkspaceTrusted(workspaceDir)) {
 			const projectAgentsFile = loadProjectAgentsContextFile(workspaceDir);
 			if (projectAgentsFile) contextFiles.push(projectAgentsFile);
@@ -482,6 +483,7 @@ var AgentManager = class {
 			directoryId,
 			name: s.name,
 			description: s.description,
+			...s.localizations ? { localizations: s.localizations } : {},
 			category: s.category,
 			source: s.source,
 			origin: s.origin.id,
@@ -499,8 +501,8 @@ var AgentManager = class {
 	getSkillCatalogSnapshot() {
 		const skillsConfig = createSkillConfigManager(resolveStateDir()).load();
 		const lock = loadSkillsLock();
-		const sessionKey = this.config.getCurrentContext?.()?.sessionKey;
-		const workspaceDir = sessionKey ? this.getResolvedWorkspaceForSession(sessionKey) : this.baseWorkspacePath;
+		const conversationId = this.config.getCurrentContext?.()?.conversationId;
+		const workspaceDir = conversationId ? this.getResolvedWorkspaceForSession(conversationId) : this.baseWorkspacePath;
 		const workspaceLock = loadSkillsLock(resolveWorkspaceSkillsLockPath(workspaceDir));
 		const rt = this.getCurrentWorkspaceRuntime();
 		return {
@@ -569,12 +571,12 @@ var AgentManager = class {
 		const profile = resolveEffectiveAgentProfile(this.config.config, agentId);
 		return this.buildAgentSkillAvailability(profile, profile.resolvedWorkspacePath);
 	}
-	getSessionSkillAvailability(sessionKey) {
-		const profile = resolveEffectiveAgentProfileForSession(this.config.config, sessionKey);
-		return this.buildAgentSkillAvailability(profile, this.getResolvedWorkspaceForSession(sessionKey), this.agents.get(sessionKey)?.registeredToolNames);
+	getSessionSkillAvailability(conversationId) {
+		const profile = resolveEffectiveAgentProfileForSession(this.config.config, conversationId);
+		return this.buildAgentSkillAvailability(profile, this.getResolvedWorkspaceForSession(conversationId), this.agents.get(conversationId)?.registeredToolNames);
 	}
-	getSessionWorkspaceTrust(sessionKey) {
-		return this.getWorkspaceTrust(this.getResolvedWorkspaceForSession(sessionKey));
+	getSessionWorkspaceTrust(conversationId) {
+		return this.getWorkspaceTrust(this.getResolvedWorkspaceForSession(conversationId));
 	}
 	getWorkspaceTrust(workspacePath) {
 		const required = hasTrustRequiringProjectResources(workspacePath);
@@ -585,8 +587,8 @@ var AgentManager = class {
 			trusted: required && this.isProjectWorkspaceTrusted(workspacePath)
 		};
 	}
-	setSessionWorkspaceTrust(sessionKey, trusted) {
-		return this.setWorkspaceTrust(this.getResolvedWorkspaceForSession(sessionKey), trusted);
+	setSessionWorkspaceTrust(conversationId, trusted) {
+		return this.setWorkspaceTrust(this.getResolvedWorkspaceForSession(conversationId), trusted);
 	}
 	setWorkspaceTrust(workspacePath, trusted) {
 		if (!hasTrustRequiringProjectResources(workspacePath)) return {
@@ -606,18 +608,18 @@ var AgentManager = class {
 		const cfg = this.config.config;
 		for (const rt of this.workspaceRuntimes.values()) rt.skillManager.refreshPromptFromConfig();
 		for (const instance of this.agents.values()) {
-			const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(instance.sessionKey);
+			const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(instance.conversationId);
 			const rt = this.workspaceRuntimes.getOrCreate(resolvedWorkspacePath, instance.effectiveProfile.agentId);
-			const contextFiles = this.resolveContextFilesForSession(instance.sessionKey, instance.effectiveProfile);
-			instance.activeProjectContext = this.buildExecutionScopeContext(instance.sessionKey);
+			const contextFiles = this.resolveContextFilesForSession(instance.conversationId, instance.effectiveProfile);
+			instance.activeProjectContext = this.buildExecutionScopeContext(instance.conversationId);
 			const newPrompt = rt.systemPromptBuilder.build(contextFiles, {
-				externalMemoryInstructions: this.buildExternalMemoryInstructions(instance.sessionKey, rt),
+				externalMemoryInstructions: this.buildExternalMemoryInstructions(instance.conversationId, rt),
 				workspaceOverride: resolvedWorkspacePath,
 				profileMarkdownPathRoot: resolveAgentProfileDir(cfg, instance.effectiveProfile.agentId),
 				customInstructions: instance.effectiveProfile.customInstructions,
 				skillAllowlist: instance.effectiveProfile.skillsAllowlist,
 				registeredToolNames: instance.registeredToolNames,
-				sessionKey: instance.sessionKey,
+				conversationId: instance.conversationId,
 				modelRef: instance.effectiveProfile.primaryModelRef?.trim() || this.defaultModel,
 				agentId: instance.effectiveProfile.agentId,
 				thinkingLevel: this.config.thinkingLevel ?? "medium",
@@ -681,18 +683,18 @@ var AgentManager = class {
 		const cfg = this.config.config;
 		for (const rt of this.workspaceRuntimes.values()) rt.skillManager.reload(reason);
 		for (const instance of this.agents.values()) {
-			const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(instance.sessionKey);
+			const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(instance.conversationId);
 			const rt = this.workspaceRuntimes.getOrCreate(resolvedWorkspacePath, instance.effectiveProfile.agentId);
-			const contextFiles = this.resolveContextFilesForSession(instance.sessionKey, instance.effectiveProfile);
-			instance.activeProjectContext = this.buildExecutionScopeContext(instance.sessionKey);
+			const contextFiles = this.resolveContextFilesForSession(instance.conversationId, instance.effectiveProfile);
+			instance.activeProjectContext = this.buildExecutionScopeContext(instance.conversationId);
 			const newPrompt = rt.systemPromptBuilder.rebuild(contextFiles, {
-				externalMemoryInstructions: this.buildExternalMemoryInstructions(instance.sessionKey, rt),
+				externalMemoryInstructions: this.buildExternalMemoryInstructions(instance.conversationId, rt),
 				workspaceOverride: resolvedWorkspacePath,
 				profileMarkdownPathRoot: resolveAgentProfileDir(cfg, instance.effectiveProfile.agentId),
 				customInstructions: instance.effectiveProfile.customInstructions,
 				skillAllowlist: instance.effectiveProfile.skillsAllowlist,
 				registeredToolNames: instance.registeredToolNames,
-				sessionKey: instance.sessionKey,
+				conversationId: instance.conversationId,
 				modelRef: instance.effectiveProfile.primaryModelRef?.trim() || this.defaultModel,
 				agentId: instance.effectiveProfile.agentId,
 				thinkingLevel: this.config.thinkingLevel ?? "medium",
@@ -705,43 +707,43 @@ var AgentManager = class {
 	/**
 	* Get or create an Agent instance for a session
 	*/
-	getOrCreateAgent(sessionKey) {
+	getOrCreateAgent(conversationId) {
 		const cfg = this.config.config;
-		const targetPath = this.getResolvedWorkspaceForSession(sessionKey);
-		const existing = this.agents.get(sessionKey);
-		if (existing) if (existing.resolvedWorkspacePath !== targetPath) this.removeAgent(sessionKey);
+		const targetPath = this.getResolvedWorkspaceForSession(conversationId);
+		const existing = this.agents.get(conversationId);
+		if (existing) if (existing.resolvedWorkspacePath !== targetPath) this.removeAgent(conversationId);
 		else {
 			this.refreshDynamicContextIfChanged(existing);
 			existing.lastUsedAt = Date.now();
-			log.debug({ sessionKey }, "Reusing existing agent instance");
+			log.debug({ conversationId }, "Reusing existing agent instance");
 			return existing.agent;
 		}
-		let profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);
+		let profile = resolveEffectiveAgentProfileForSession(cfg, conversationId);
 		const resolvedPath = targetPath;
 		const rt = this.workspaceRuntimes.getOrCreate(resolvedPath, profile.agentId);
 		profile = this.materializeSkillAllowlist(profile, rt);
-		if (isMemorySubsystemEnabled(cfg)) rt.memoryManager.initializeAll(sessionKey, {
+		if (isMemorySubsystemEnabled(cfg)) rt.memoryManager.initializeAll(conversationId, {
 			workspace: resolvedPath,
 			agentId: profile.agentId
 		}).catch((err) => log.warn({
 			err,
-			sessionKey
+			conversationId
 		}, "memory initializeAll failed"));
-		const activeProjectContext = this.buildExecutionScopeContext(sessionKey);
+		const activeProjectContext = this.buildExecutionScopeContext(conversationId);
 		const profileModelRef = profile.primaryModelRef?.trim() || this.defaultModel;
 		const modelManager = this.config.getModelManager?.();
-		const initialModelRef = modelManager?.resolveInitialModelForSession(sessionKey, profileModelRef, profile.fallbacks) ?? profileModelRef;
+		const initialModelRef = modelManager?.resolveInitialModelForSession(conversationId, profileModelRef, profile.fallbacks) ?? profileModelRef;
 		let created;
 		try {
-			created = this.createAgentForProfile(sessionKey, profile, initialModelRef, resolvedPath, rt, activeProjectContext);
+			created = this.createAgentForProfile(conversationId, profile, initialModelRef, resolvedPath, rt, activeProjectContext);
 		} catch (err) {
-			modelManager?.clearSessionProfileDefault(sessionKey);
+			modelManager?.clearSessionProfileDefault(conversationId);
 			throw err;
 		}
 		const { agent, registeredToolNames } = created;
-		this.agents.set(sessionKey, {
+		this.agents.set(conversationId, {
 			agent,
-			sessionKey,
+			conversationId,
 			createdAt: Date.now(),
 			lastUsedAt: Date.now(),
 			effectiveProfile: profile,
@@ -749,53 +751,53 @@ var AgentManager = class {
 			registeredToolNames,
 			activeCapabilities: /* @__PURE__ */ new Map(),
 			activeProjectContext,
-			interactionStateVersion: this.getInteractionStateVersion(sessionKey),
-			userContextAccessVersion: this.getUserContextAccessVersion(sessionKey),
+			interactionStateVersion: this.getInteractionStateVersion(conversationId),
+			userContextAccessVersion: this.getUserContextAccessVersion(conversationId),
 			skillEnvPassthroughKeys: /* @__PURE__ */ new Set()
 		});
 		log.debug({
-			sessionKey,
+			conversationId,
 			totalAgents: this.agents.size,
 			agentId: profile.agentId
 		}, "Created new agent instance");
 		return agent;
 	}
-	createAgentTurnPolicy(sessionKey) {
-		const profile = this.agents.get(sessionKey)?.effectiveProfile ?? resolveEffectiveAgentProfileForSession(this.config.config, sessionKey);
-		return this.buildAgentTurnPolicy(sessionKey, profile);
+	createAgentTurnPolicy(conversationId) {
+		const profile = this.agents.get(conversationId)?.effectiveProfile ?? resolveEffectiveAgentProfileForSession(this.config.config, conversationId);
+		return this.buildAgentTurnPolicy(conversationId, profile);
 	}
 	/**
 	* Get existing agent for a session (if any)
 	*/
-	getAgent(sessionKey) {
-		return this.agents.get(sessionKey)?.agent;
+	getAgent(conversationId) {
+		return this.agents.get(conversationId)?.agent;
 	}
 	/**
 	* Check if an agent exists for a session
 	*/
-	hasAgent(sessionKey) {
-		return this.agents.has(sessionKey);
+	hasAgent(conversationId) {
+		return this.agents.has(conversationId);
 	}
 	/**
 	* Remove an agent instance
 	*/
-	removeAgent(sessionKey) {
-		const instance = this.agents.get(sessionKey);
+	removeAgent(conversationId) {
+		const instance = this.agents.get(conversationId);
 		if (instance) {
-			this.backgroundReview.forgetSession(sessionKey);
-			this.toolsFactory.closeBrowserPageForSession(sessionKey);
-			retireSessionMcpRuntimeForSessionKey({
-				sessionKey,
+			this.backgroundReview.forgetSession(conversationId);
+			this.toolsFactory.closeBrowserPageForSession(conversationId);
+			retireSessionMcpRuntimeForConversationId({
+				conversationId,
 				reason: "agent-evict"
 			});
 			instance.agent.abort();
-			evictEmbeddedSessionRunner(sessionKey, "agent_removed");
-			this.agents.delete(sessionKey);
-			this.executionContext.forgetSession(sessionKey);
-			clearBootstrapSnapshot(sessionKey);
-			this.config.getModelManager?.().clearSessionProfileDefault(sessionKey);
+			evictEmbeddedSessionRunner(conversationId, "agent_removed");
+			this.agents.delete(conversationId);
+			this.executionContext.forgetSession(conversationId);
+			clearBootstrapSnapshot(conversationId);
+			this.config.getModelManager?.().clearSessionProfileDefault(conversationId);
 			log.info({
-				sessionKey,
+				conversationId,
 				totalAgents: this.agents.size
 			}, "Removed agent instance");
 			return true;
@@ -817,26 +819,26 @@ var AgentManager = class {
 	/**
 	* Merge per-turn channel system prompt (e.g. Telegram group/topic override) into the agent.
 	*/
-	applyTurnChannelSystemPrompt(sessionKey, channelSystemPrompt) {
+	applyTurnChannelSystemPrompt(conversationId, channelSystemPrompt) {
 		const trimmed = channelSystemPrompt.trim();
 		if (!trimmed) return;
-		const instance = this.agents.get(sessionKey);
+		const instance = this.agents.get(conversationId);
 		if (!instance) return;
 		const cfg = this.config.config;
-		const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(sessionKey);
+		const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(conversationId);
 		const rt = this.workspaceRuntimes.getOrCreate(resolvedWorkspacePath, instance.effectiveProfile.agentId);
-		const contextFiles = this.resolveContextFilesForSession(sessionKey, instance.effectiveProfile);
+		const contextFiles = this.resolveContextFilesForSession(conversationId, instance.effectiveProfile);
 		const modelRef = instance.effectiveProfile.primaryModelRef?.trim() || this.defaultModel;
 		const thinkingLevel = this.config.thinkingLevel ?? "medium";
-		const activeProjectContext = this.buildExecutionScopeContext(sessionKey);
+		const activeProjectContext = this.buildExecutionScopeContext(conversationId);
 		instance.agent.state.systemPrompt = rt.systemPromptBuilder.build(contextFiles, {
-			externalMemoryInstructions: this.buildExternalMemoryInstructions(sessionKey, rt),
+			externalMemoryInstructions: this.buildExternalMemoryInstructions(conversationId, rt),
 			workspaceOverride: resolvedWorkspacePath,
 			profileMarkdownPathRoot: resolveAgentProfileDir(cfg, instance.effectiveProfile.agentId),
 			customInstructions: instance.effectiveProfile.customInstructions,
 			skillAllowlist: instance.effectiveProfile.skillsAllowlist,
 			registeredToolNames: instance.registeredToolNames,
-			sessionKey,
+			conversationId,
 			modelRef,
 			agentId: instance.effectiveProfile.agentId,
 			thinkingLevel,
@@ -848,12 +850,12 @@ var AgentManager = class {
 	/**
 	* Set thinking level for a session's agent
 	*/
-	setThinkingLevel(sessionKey, level) {
-		const instance = this.agents.get(sessionKey);
+	setThinkingLevel(conversationId, level) {
+		const instance = this.agents.get(conversationId);
 		if (instance) {
 			instance.agent.state.thinkingLevel = level;
 			log.debug({
-				sessionKey,
+				conversationId,
 				thinkingLevel: level
 			}, "Set thinking level for agent");
 		}
@@ -906,35 +908,35 @@ var AgentManager = class {
 	composeDynamicProjectContext(...sections) {
 		return sections.map((section) => section?.trim()).filter((section) => Boolean(section)).join("\n\n") || void 0;
 	}
-	buildExecutionScopeContext(sessionKey) {
-		const access = resolveUserContextSessionAccess(this.config.config, sessionKey);
-		return buildExecutionScopeContextForPrompt(sessionKey, {
+	buildExecutionScopeContext(conversationId) {
+		const access = resolveUserContextSessionAccess(this.config.config, conversationId);
+		return buildExecutionScopeContextForPrompt(conversationId, {
 			includeKnowledge: access.knowledge,
 			knowledgeSources: access.knowledgeSources
 		});
 	}
-	getInteractionStateVersion(sessionKey) {
-		return isXopcDatabaseOpen() ? getInteractionState(sessionKey)?.updatedAt : void 0;
+	getInteractionStateVersion(conversationId) {
+		return isXopcDatabaseOpen() ? getInteractionState(conversationId)?.updatedAt : void 0;
 	}
-	getUserContextAccessVersion(sessionKey) {
-		return JSON.stringify(resolveUserContextSessionAccess(this.config.config, sessionKey));
+	getUserContextAccessVersion(conversationId) {
+		return JSON.stringify(resolveUserContextSessionAccess(this.config.config, conversationId));
 	}
-	buildExternalMemoryInstructions(sessionKey, rt) {
-		return resolveUserContextSessionAccess(this.config.config, sessionKey).knowledge ? rt.memoryManager.buildExternalSystemPrompt() : "";
+	buildExternalMemoryInstructions(conversationId, rt) {
+		return resolveUserContextSessionAccess(this.config.config, conversationId).knowledge ? rt.memoryManager.buildExternalSystemPrompt() : "";
 	}
-	getCapabilityCatalogForSession(sessionKey) {
-		const inst = sessionKey?.trim() ? this.agents.get(sessionKey.trim()) : void 0;
+	getCapabilityCatalogForSession(conversationId) {
+		const inst = conversationId?.trim() ? this.agents.get(conversationId.trim()) : void 0;
 		return this.resolveCapabilityCatalogForInstance(inst);
 	}
-	createAgentForProfile(sessionKey, profile, modelRef, resolvedWorkspacePath, rt, activeProjectContext) {
+	createAgentForProfile(conversationId, profile, modelRef, resolvedWorkspacePath, rt, activeProjectContext) {
 		const model = this.resolveModelStringToModel(modelRef);
 		let agent;
-		const contextFiles = this.resolveContextFilesForSession(sessionKey, profile);
+		const contextFiles = this.resolveContextFilesForSession(conversationId, profile);
 		const tools = this.toolsFactory.createAllTools({
 			workspace: resolvedWorkspacePath,
 			profileMarkdownRoot: resolveAgentProfileDir(this.config.config, profile.agentId),
 			agentId: profile.agentId,
-			sessionKey,
+			conversationId,
 			disabledTools: profile.tools.denied,
 			getPrimaryModel: () => agent?.state.model ?? model,
 			getMemoryManager: () => rt.memoryManager,
@@ -942,17 +944,17 @@ var AgentManager = class {
 		});
 		const registeredToolNames = tools.map((t) => t.name);
 		const thinkingLevel = this.config.thinkingLevel ?? "medium";
-		const turnPolicy = this.buildAgentTurnPolicy(sessionKey, profile);
+		const turnPolicy = this.buildAgentTurnPolicy(conversationId, profile);
 		agent = new Agent({
 			initialState: {
 				systemPrompt: rt.systemPromptBuilder.build(contextFiles, {
-					externalMemoryInstructions: this.buildExternalMemoryInstructions(sessionKey, rt),
+					externalMemoryInstructions: this.buildExternalMemoryInstructions(conversationId, rt),
 					workspaceOverride: resolvedWorkspacePath,
 					profileMarkdownPathRoot: resolveAgentProfileDir(this.config.config, profile.agentId),
 					customInstructions: profile.customInstructions,
 					skillAllowlist: profile.skillsAllowlist,
 					registeredToolNames,
-					sessionKey,
+					conversationId,
 					modelRef,
 					agentId: profile.agentId,
 					thinkingLevel,
@@ -978,7 +980,7 @@ var AgentManager = class {
 			registeredToolNames
 		};
 	}
-	buildAgentTurnPolicy(sessionKey, profile) {
+	buildAgentTurnPolicy(conversationId, profile) {
 		return createAgentTurnPolicy({
 			maxTurns: profile.config.runtime.maxTurns,
 			maxToolFailures: profile.config.runtime.maxToolFailuresPerTurn,
@@ -1000,7 +1002,7 @@ var AgentManager = class {
 					apply_patch: "filesystem_write",
 					xopc_tool_execute: "external_tool"
 				}[toolName] ?? toolName;
-				const executionGate = this.executionContext.getCurrent(sessionKey);
+				const executionGate = this.executionContext.getCurrent(conversationId);
 				if (executionGate) {
 					const decision = evaluateToolGate(executionGate, operation);
 					if (!decision.allowed) return {
@@ -1012,7 +1014,7 @@ var AgentManager = class {
 				const policy = this.resolveToolPolicy(profile, toolName, args);
 				const detail = JSON.stringify(args ?? {});
 				if (policy?.mode === "ask") {
-					if (!await this.requestToolConfirmation(sessionKey, policy?.id ?? toolName, detail)) return {
+					if (!await this.requestToolConfirmation(conversationId, policy?.id ?? toolName, detail)) return {
 						block: true,
 						terminate: true,
 						reason: `User did not approve ${policy?.id ?? toolName}.`
@@ -1027,7 +1029,7 @@ var AgentManager = class {
 						const approval = await maybeRequestChannelExecApproval({
 							cfg,
 							payload: {
-								sessionKey: ctx.sessionKey,
+								conversationId: ctx.conversationId,
 								channel: ctx.channel,
 								chatId: ctx.chatId,
 								accountId,
@@ -1043,7 +1045,7 @@ var AgentManager = class {
 					}
 				}
 				if (!this.config.hookRunner) return;
-				const hookResult = await this.config.hookRunner.runBeforeToolCall(toolName, args ?? {}, { sessionKey });
+				const hookResult = await this.config.hookRunner.runBeforeToolCall(toolName, args ?? {}, { conversationId });
 				if (!hookResult.allowed) return {
 					block: true,
 					reason: hookResult.reason ?? "Tool call blocked by policy hook."
@@ -1068,16 +1070,16 @@ var AgentManager = class {
 			...policy
 		} : void 0;
 	}
-	async requestToolConfirmation(sessionKey, toolName, detail) {
+	async requestToolConfirmation(conversationId, toolName, detail) {
 		const request = this.config.gatewayClarify?.requestClarification;
 		if (!request) return false;
 		const approvalKey = createHash("sha256").update(`${toolName}\0${detail}`).digest("hex");
-		const existing = consumeClarificationApproval(sessionKey, approvalKey);
+		const existing = consumeClarificationApproval(conversationId, approvalKey);
 		if (existing) return existing === "approved";
 		const runId = getEmbeddedExecutionRunId();
 		if (!runId) return false;
 		const result = await request({
-			sessionKey,
+			conversationId,
 			runId,
 			toolCallId: `approval:${approvalKey}`
 		}, {
@@ -1093,24 +1095,24 @@ var AgentManager = class {
 		return result.status === "answered" && result.answer === "Allow once";
 	}
 	refreshDynamicContextIfChanged(instance) {
-		const nextProjectContext = this.buildExecutionScopeContext(instance.sessionKey);
-		const interactionStateVersion = this.getInteractionStateVersion(instance.sessionKey);
-		const userContextAccessVersion = this.getUserContextAccessVersion(instance.sessionKey);
+		const nextProjectContext = this.buildExecutionScopeContext(instance.conversationId);
+		const interactionStateVersion = this.getInteractionStateVersion(instance.conversationId);
+		const userContextAccessVersion = this.getUserContextAccessVersion(instance.conversationId);
 		if (nextProjectContext === instance.activeProjectContext && interactionStateVersion === instance.interactionStateVersion && userContextAccessVersion === instance.userContextAccessVersion) return;
 		const cfg = this.config.config;
-		const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(instance.sessionKey);
+		const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(instance.conversationId);
 		const rt = this.workspaceRuntimes.getOrCreate(resolvedWorkspacePath, instance.effectiveProfile.agentId);
-		const contextFiles = this.resolveContextFilesForSession(instance.sessionKey, instance.effectiveProfile);
+		const contextFiles = this.resolveContextFilesForSession(instance.conversationId, instance.effectiveProfile);
 		const modelRef = instance.effectiveProfile.primaryModelRef?.trim() || this.defaultModel;
 		const thinkingLevel = instance.agent.state.thinkingLevel ?? this.config.thinkingLevel ?? "medium";
 		instance.agent.state.systemPrompt = rt.systemPromptBuilder.build(contextFiles, {
-			externalMemoryInstructions: this.buildExternalMemoryInstructions(instance.sessionKey, rt),
+			externalMemoryInstructions: this.buildExternalMemoryInstructions(instance.conversationId, rt),
 			workspaceOverride: resolvedWorkspacePath,
 			profileMarkdownPathRoot: resolveAgentProfileDir(cfg, instance.effectiveProfile.agentId),
 			customInstructions: instance.effectiveProfile.customInstructions,
 			skillAllowlist: instance.effectiveProfile.skillsAllowlist,
 			registeredToolNames: instance.registeredToolNames,
-			sessionKey: instance.sessionKey,
+			conversationId: instance.conversationId,
 			modelRef,
 			agentId: instance.effectiveProfile.agentId,
 			thinkingLevel,
@@ -1119,16 +1121,16 @@ var AgentManager = class {
 		instance.activeProjectContext = nextProjectContext;
 		instance.interactionStateVersion = interactionStateVersion;
 		instance.userContextAccessVersion = userContextAccessVersion;
-		log.debug({ sessionKey: instance.sessionKey }, "Dynamic agent context changed; system prompt refreshed");
+		log.debug({ conversationId: instance.conversationId }, "Dynamic agent context changed; system prompt refreshed");
 	}
 	/**
 	* Set model for a specific session
 	*/
-	setModelForSession(sessionKey, modelId) {
-		const instance = this.agents.get(sessionKey);
+	setModelForSession(conversationId, modelId) {
+		const instance = this.agents.get(conversationId);
 		if (!instance) {
 			log.warn({
-				sessionKey,
+				conversationId,
 				modelId,
 				activeSessionCount: this.agents.size
 			}, `setModelForSession: no agent instance for session (create session / run turn first); modelId=${modelId}`);
@@ -1138,19 +1140,19 @@ var AgentManager = class {
 			const model = resolveModel(modelId);
 			instance.agent.state.model = model;
 			const cfg = this.config.config;
-			const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(sessionKey);
+			const resolvedWorkspacePath = this.getResolvedWorkspaceForSession(conversationId);
 			const rt = this.workspaceRuntimes.getOrCreate(resolvedWorkspacePath, instance.effectiveProfile.agentId);
-			const contextFiles = this.resolveContextFilesForSession(sessionKey, instance.effectiveProfile);
+			const contextFiles = this.resolveContextFilesForSession(conversationId, instance.effectiveProfile);
 			const thinkingLevel = instance.agent.state.thinkingLevel ?? this.config.thinkingLevel ?? "medium";
-			const activeProjectContext = this.buildExecutionScopeContext(sessionKey);
+			const activeProjectContext = this.buildExecutionScopeContext(conversationId);
 			instance.agent.state.systemPrompt = rt.systemPromptBuilder.build(contextFiles, {
-				externalMemoryInstructions: this.buildExternalMemoryInstructions(sessionKey, rt),
+				externalMemoryInstructions: this.buildExternalMemoryInstructions(conversationId, rt),
 				workspaceOverride: resolvedWorkspacePath,
 				profileMarkdownPathRoot: resolveAgentProfileDir(cfg, instance.effectiveProfile.agentId),
 				customInstructions: instance.effectiveProfile.customInstructions,
 				skillAllowlist: instance.effectiveProfile.skillsAllowlist,
 				registeredToolNames: instance.registeredToolNames,
-				sessionKey,
+				conversationId,
 				modelRef: modelId,
 				agentId: instance.effectiveProfile.agentId,
 				thinkingLevel,
@@ -1158,14 +1160,14 @@ var AgentManager = class {
 			});
 			instance.activeProjectContext = activeProjectContext;
 			log.info({
-				sessionKey,
+				conversationId,
 				modelId
 			}, "Model set for session");
 			return true;
 		} catch (err) {
 			log.error({
 				err,
-				sessionKey,
+				conversationId,
 				modelId
 			}, "Failed to set model for session");
 			return false;
@@ -1174,8 +1176,8 @@ var AgentManager = class {
 	/**
 	* Get last assistant content from a session's agent
 	*/
-	getLastAssistantContent(sessionKey) {
-		const instance = this.agents.get(sessionKey);
+	getLastAssistantContent(conversationId) {
+		const instance = this.agents.get(conversationId);
 		if (!instance) return null;
 		const messages = instance.agent.state.messages;
 		for (let i = messages.length - 1; i >= 0; i--) {
@@ -1191,8 +1193,8 @@ var AgentManager = class {
 	/**
 	* Replace messages for a session's agent
 	*/
-	replaceMessages(sessionKey, messages) {
-		const instance = this.agents.get(sessionKey);
+	replaceMessages(conversationId, messages) {
+		const instance = this.agents.get(conversationId);
 		if (!instance) return false;
 		instance.agent.state.messages = messages;
 		return true;
@@ -1200,26 +1202,26 @@ var AgentManager = class {
 	/**
 	* Get messages for a session's agent
 	*/
-	getMessages(sessionKey) {
-		const instance = this.agents.get(sessionKey);
+	getMessages(conversationId) {
+		const instance = this.agents.get(conversationId);
 		if (!instance) return null;
 		return instance.agent.state.messages;
 	}
 	/**
 	* Subscribe to agent events for a session
 	*/
-	subscribeToSession(sessionKey, callback) {
-		const listeners = this.runtimeListeners.get(sessionKey) ?? /* @__PURE__ */ new Set();
+	subscribeToSession(conversationId, callback) {
+		const listeners = this.runtimeListeners.get(conversationId) ?? /* @__PURE__ */ new Set();
 		listeners.add(callback);
-		this.runtimeListeners.set(sessionKey, listeners);
+		this.runtimeListeners.set(conversationId, listeners);
 		return () => {
 			listeners.delete(callback);
-			if (listeners.size === 0) this.runtimeListeners.delete(sessionKey);
+			if (listeners.size === 0) this.runtimeListeners.delete(conversationId);
 		};
 	}
 	runtimeListeners = /* @__PURE__ */ new Map();
-	emitRuntimeEvent(sessionKey, event) {
-		for (const listener of this.runtimeListeners.get(sessionKey) ?? []) listener(event);
+	emitRuntimeEvent(conversationId, event) {
+		for (const listener of this.runtimeListeners.get(conversationId) ?? []) listener(event);
 	}
 };
 //#endregion