@xopcai/xopc 0.0.284 → 0.0.286

package/dist/src/agent/service.js

@@ -4,6 +4,7 @@ import { parseNoteAttachmentTarget } from "../notes/attachment-ref.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { applyConfigOverrides } from "../config/runtime-overrides.js";
 import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
+import { init_agent_session_key, resolveAgentIdFromConversationId } from "../routing/agent-session-key.js";
 import { extractProfileAgentId } from "../config/agent-profile.js";
 import { init_providers, resolveModel } from "../providers/index.js";
 import { extractTextContent } from "./context/workspace.js";
@@ -20,13 +21,13 @@ import { resolveAgentTurnTimeoutMs } from "./orchestration/run-agent-turn-with-t
 import { onSessionTranscriptUpdate } from "../session/transcript-events.js";
 import { persistInboundAttachments } from "../channels/attachments/inbound-persist.js";
 import { buildTranscriptUserMessage, hydrateUserTurnForLlm } from "./inbound/attachment-pipeline.js";
+import { resolveCompactionPolicy } from "./memory/compaction-policy.js";
 import { runXopcEmbeddedTurn } from "./embedded/run-turn.js";
 import { resolveResponseLanguageForSession } from "./prompt/response-language.js";
 import { normalizeSkillInstallTarget } from "./skills/install-target.js";
 import { AgentManager } from "./agent-manager.js";
 import { MAX_WEBCHAT_ATTACHMENT_FILE_BYTES } from "../gateway/chat-limits.js";
 import { maybeRefineSessionTitleWithLlm, maybeSetProvisionalSessionTitle } from "../session/session-title.js";
-import { resolveCompactionPolicy } from "./memory/compaction-policy.js";
 import { SessionStore } from "../session/store.js";
 import { SessionConfigStore } from "../session/config-store.js";
 import "../session/index.js";
@@ -70,6 +71,7 @@ import { TaskJudgeService } from "./tasks/task-judge-service.js";
 import { analyzeResponseLanguage } from "../i18n/language-consistency.js";
 import { readFile } from "node:fs/promises";
 //#region src/agent/service.ts
+init_agent_session_key();
 init_schema();
 init_logger();
 init_agent_scope();
@@ -182,10 +184,10 @@ var AgentService = class {
 			this.sessionStore.syncEmbeddedTranscriptUpdate(update).catch((err) => {
 				log.warn({
 					err,
-					sessionKey: update.sessionKey
+					conversationId: update.conversationId
 				}, "Transcript index sync failed");
 			});
-			const sk = update.sessionKey?.trim();
+			const sk = update.conversationId?.trim();
 			if (sk) this.onSessionTranscriptUpdated?.(sk);
 		});
 		const appCfgForPaths = this.config.config;
@@ -196,16 +198,16 @@ var AgentService = class {
 		this.hookHandler = new HookHandler({
 			hookRunner: this.hookRunner,
 			agentId: this.agentId,
-			get sessionKey() {
-				return this.currentContext?.sessionKey;
+			get conversationId() {
+				return this.currentContext?.conversationId;
 			}
 		});
 		this.sessionStore.setCompactionHooks({
-			before: ({ sessionKey, messageCount, tokenCount }) => this.hookHandler.triggerWithSessionKey(sessionKey, "before_compaction", {
+			before: ({ conversationId, messageCount, tokenCount }) => this.hookHandler.triggerWithConversationId(conversationId, "before_compaction", {
 				messageCount,
 				tokenCount
 			}),
-			after: ({ sessionKey, messageCount, tokenCount, compactedCount }) => this.hookHandler.triggerWithSessionKey(sessionKey, "after_compaction", {
+			after: ({ conversationId, messageCount, tokenCount, compactedCount }) => this.hookHandler.triggerWithConversationId(conversationId, "after_compaction", {
 				messageCount,
 				tokenCount,
 				compactedCount
@@ -256,10 +258,10 @@ var AgentService = class {
 		this.agentEventHandler.registerListener("message_end", (event, context) => {
 			const message = event.message;
 			if (message.role !== "assistant") return;
-			const analysis = analyzeResponseLanguage(assistantMessageText(message), resolveResponseLanguageForSession(this.effectiveAppConfig(), context.sessionKey));
+			const analysis = analyzeResponseLanguage(assistantMessageText(message), resolveResponseLanguageForSession(this.effectiveAppConfig(), context.conversationId));
 			const fields = {
 				phase: "response_language_check",
-				sessionKey: context.sessionKey,
+				conversationId: context.conversationId,
 				...analysis
 			};
 			if (analysis.compliant) log.debug(fields, "Assistant response language check passed");
@@ -281,20 +283,20 @@ var AgentService = class {
 			getConfig: () => this.effectiveAppConfig(),
 			getThinkingDefault: () => void 0,
 			workspaceRoot: this.workspaceDir,
-			getWorkspaceRootForSession: (sessionKey) => this.agentManager.getResolvedWorkspaceForSession(sessionKey),
-			getAgentInternalStorageRootForSession: (sessionKey) => resolveAgentHomeDir(this.config.config, extractProfileAgentId(sessionKey, this.config.config)),
-			enqueueAutoTitle: (sessionKey) => this.enqueueMaybeAutoTitleAfterPersist(sessionKey),
-			onEmbeddedStreamEvent: (sessionKey, event) => {
+			getWorkspaceRootForSession: (conversationId) => this.agentManager.getResolvedWorkspaceForSession(conversationId),
+			getAgentInternalStorageRootForSession: (conversationId) => resolveAgentHomeDir(this.config.config, extractProfileAgentId(conversationId, this.config.config)),
+			enqueueAutoTitle: (conversationId) => this.enqueueMaybeAutoTitleAfterPersist(conversationId),
+			onEmbeddedStreamEvent: (conversationId, event) => {
 				const ctx = this.sessionContextManager.getContext();
-				if (!ctx || ctx.sessionKey !== sessionKey) return;
+				if (!ctx || ctx.conversationId !== conversationId) return;
 				if (event.type === "message_update" && event.message.role === "assistant") {
 					const next = assistantMessageText(event.message);
 					this.streamManager.update(next);
 				}
 			},
-			onEmbeddedTurnComplete: (sessionKey, text) => {
-				if (text) this.sessionState.setLastAssistantText(sessionKey, text);
-				this.sessionState.clearEmbeddedStreamText(sessionKey);
+			onEmbeddedTurnComplete: (conversationId, text) => {
+				if (text) this.sessionState.setLastAssistantText(conversationId, text);
+				this.sessionState.clearEmbeddedStreamText(conversationId);
 			}
 		});
 		this.messageRouter = new MessageRouter();
@@ -304,24 +306,24 @@ var AgentService = class {
 			sessionStore: this.sessionStore,
 			sessionConfigStore: this.sessionConfigStore,
 			getWorkflowRunService: config.getWorkflowRunService,
-			applySessionThinkingLevel: (sessionKey, level) => {
-				this.agentManager.setThinkingLevel(sessionKey, level);
+			applySessionThinkingLevel: (conversationId, level) => {
+				this.agentManager.setThinkingLevel(conversationId, level);
 			},
 			getCurrentModel: () => this.agentOrchestrator.getCurrentModel(),
-			switchModelForSession: (sessionKey, modelId) => this.switchModelForSession(sessionKey, modelId),
-			invalidateAgentSession: (sessionKey) => {
-				this.agentManager.removeAgent(sessionKey);
+			switchModelForSession: (conversationId, modelId) => this.switchModelForSession(conversationId, modelId),
+			invalidateAgentSession: (conversationId) => {
+				this.agentManager.removeAgent(conversationId);
 			},
-			resetSession: (sessionKey) => this.resetSession(sessionKey),
-			abortSessionTurn: async (sessionKey) => {
+			resetSession: (conversationId) => this.resetSession(conversationId),
+			abortSessionTurn: async (conversationId) => {
 				await this.streamManager.abort();
-				this.agentOrchestrator.abort(sessionKey);
+				this.agentOrchestrator.abort(conversationId);
 			},
 			reloadSkills: () => this.refreshSkillsAfterDiskChange(),
 			installSkillFromSource: (opts) => this.installSkillFromSource(opts),
-			compactSession: (sessionKey, options) => this.sessionInspector.compact(sessionKey, options),
-			btwQuery: (sessionKey, question, options) => this.sessionInspector.btwQuery(sessionKey, question, options),
-			getSessionContextReport: (sessionKey, mode) => this.sessionInspector.report(sessionKey, mode)
+			compactSession: (conversationId, options) => this.sessionInspector.compact(conversationId, options),
+			btwQuery: (conversationId, question, options) => this.sessionInspector.btwQuery(conversationId, question, options),
+			getSessionContextReport: (conversationId, mode) => this.sessionInspector.report(conversationId, mode)
 		});
 		this.sessionLifecycleManager = new SessionLifecycleManager(this.sessionStore, this.sessionTracker, this.lifecycleManager);
 		this.taskJudge = new TaskJudgeService({
@@ -343,7 +345,7 @@ var AgentService = class {
 			agentManager: this.agentManager,
 			sessionHydrator: this.sessionHydrator,
 			getConfig: () => this.effectiveAppConfig(),
-			getContextWindow: (sessionKey) => this.getContextWindowForSession(sessionKey)
+			getContextWindow: (conversationId) => this.getContextWindowForSession(conversationId)
 		});
 		this.outboundCoordinator = new OutboundCoordinator({
 			bus,
@@ -491,20 +493,20 @@ var AgentService = class {
 	getAgentSkillAvailability(agentId) {
 		return this.agentManager.getAgentSkillAvailability(agentId);
 	}
-	async getSessionSkillAvailability(sessionKey) {
-		await this.sessionHydrator.workspace(sessionKey);
-		return this.agentManager.getSessionSkillAvailability(sessionKey);
+	async getSessionSkillAvailability(conversationId) {
+		await this.sessionHydrator.workspace(conversationId);
+		return this.agentManager.getSessionSkillAvailability(conversationId);
 	}
-	async getSessionWorkspaceTrust(sessionKey) {
-		await this.sessionHydrator.workspace(sessionKey);
-		return this.agentManager.getSessionWorkspaceTrust(sessionKey);
+	async getSessionWorkspaceTrust(conversationId) {
+		await this.sessionHydrator.workspace(conversationId);
+		return this.agentManager.getSessionWorkspaceTrust(conversationId);
 	}
-	getResolvedWorkspaceForSession(sessionKey) {
-		return this.agentManager.getResolvedWorkspaceForSession(sessionKey);
+	getResolvedWorkspaceForSession(conversationId) {
+		return this.agentManager.getResolvedWorkspaceForSession(conversationId);
 	}
-	async setSessionWorkspaceTrust(sessionKey, trusted) {
-		await this.sessionHydrator.workspace(sessionKey);
-		return this.agentManager.setSessionWorkspaceTrust(sessionKey, trusted);
+	async setSessionWorkspaceTrust(conversationId, trusted) {
+		await this.sessionHydrator.workspace(conversationId);
+		return this.agentManager.setSessionWorkspaceTrust(conversationId, trusted);
 	}
 	getWorkspaceTrust(workspacePath) {
 		return this.agentManager.getWorkspaceTrust(workspacePath);
@@ -512,8 +514,8 @@ var AgentService = class {
 	setWorkspaceTrust(workspacePath, trusted) {
 		return this.agentManager.setWorkspaceTrust(workspacePath, trusted);
 	}
-	getCapabilityCatalog(sessionKey) {
-		return this.agentManager.getCapabilityCatalogForSession(sessionKey);
+	getCapabilityCatalog(conversationId) {
+		return this.agentManager.getCapabilityCatalogForSession(conversationId);
 	}
 	getSkillMarkdownSource(skillName) {
 		return this.agentManager.getSkillMarkdownSource(skillName);
@@ -526,7 +528,7 @@ var AgentService = class {
 	}
 	async installSkillFromSource(opts) {
 		const target = normalizeSkillInstallTarget(opts.target);
-		const workspace = opts.workspace?.trim() || (opts.sessionKey ? this.agentManager.getResolvedWorkspaceForSession(opts.sessionKey) : void 0) || this.workspaceDir;
+		const workspace = opts.workspace?.trim() || (opts.conversationId ? this.agentManager.getResolvedWorkspaceForSession(opts.conversationId) : void 0) || this.workspaceDir;
 		const result = await pullSkillFromSource(opts.source, {
 			ref: opts.ref,
 			subpath: opts.path,
@@ -545,7 +547,7 @@ var AgentService = class {
 	async installSkillFromMarketplace(opts) {
 		const config = this.effectiveAppConfig();
 		const target = normalizeSkillInstallTarget(opts.target);
-		const workspace = (opts.sessionKey ? this.agentManager.getResolvedWorkspaceForSession(opts.sessionKey) : void 0) || this.workspaceDir;
+		const workspace = (opts.conversationId ? this.agentManager.getResolvedWorkspaceForSession(opts.conversationId) : void 0) || this.workspaceDir;
 		const rootDir = target === "workspace" ? resolveWorkspaceSkillsDir(workspace) : void 0;
 		const lockPath = target === "workspace" ? resolveWorkspaceSkillsLockPath(workspace) : void 0;
 		const { downloadFromMarketplace } = await import("./skills/skills-marketplace.js");
@@ -577,22 +579,22 @@ var AgentService = class {
 	getMemoryManager() {
 		return this.agentManager.getMemoryManager();
 	}
-	getModelForSession(sessionKey) {
-		return this.modelManager.getModelForSession(sessionKey);
+	getModelForSession(conversationId) {
+		return this.modelManager.getModelForSession(conversationId);
 	}
-	getThinkingLevelForSession(sessionKey) {
-		return this.agentManager.getOrCreateAgent(sessionKey).state.thinkingLevel ?? "medium";
+	getThinkingLevelForSession(conversationId) {
+		return this.agentManager.getOrCreateAgent(conversationId).state.thinkingLevel ?? "medium";
 	}
 	/** Run a full tool-capable turn against a caller-owned, non-persistent transcript. */
 	async runEphemeralTurn(params) {
-		const agent = this.agentManager.getOrCreateAgent(params.parentSessionKey);
-		const workspaceDir = this.agentManager.getResolvedWorkspaceForSession(params.parentSessionKey);
+		const agent = this.agentManager.getOrCreateAgent(params.parentConversationId);
+		const workspaceDir = this.agentManager.getResolvedWorkspaceForSession(params.parentConversationId);
 		const model = resolveModel(params.modelRef);
-		const prepared = await this.prepareInboundAttachments(params.executionSessionKey, params.attachments);
+		const prepared = await this.prepareInboundAttachments(params.executionConversationId, params.attachments);
 		const userMessage = await buildTranscriptUserMessage({
 			text: params.content,
 			prepared,
-			sessionKey: params.parentSessionKey,
+			conversationId: params.parentConversationId,
 			modelRef: params.modelRef,
 			config: this.effectiveAppConfig(),
 			agentManager: this.agentManager
@@ -601,8 +603,9 @@ var AgentService = class {
 			message: userMessage,
 			modelRef: params.modelRef
 		});
-		return runWithEmbeddedExecutionSession(params.executionSessionKey, () => runXopcEmbeddedTurn({
-			sessionKey: params.executionSessionKey,
+		return runWithEmbeddedExecutionSession(params.executionConversationId, () => runXopcEmbeddedTurn({
+			conversationId: params.executionConversationId,
+			verifyChanges: resolveAgentIdFromConversationId(params.parentConversationId) === "coder",
 			runId: params.runId,
 			userMessage,
 			model,
@@ -612,25 +615,25 @@ var AgentService = class {
 			thinkingLevel: params.thinkingLevel ?? agent.state.thinkingLevel,
 			workspaceDir,
 			transcriptRuntime: params.transcriptRuntime,
-			timeoutMs: resolveAgentTurnTimeoutMs(this.effectiveAppConfig(), params.parentSessionKey),
-			turnPolicy: this.agentManager.createAgentTurnPolicy(params.parentSessionKey),
+			timeoutMs: resolveAgentTurnTimeoutMs(this.effectiveAppConfig(), params.parentConversationId),
+			turnPolicy: this.agentManager.createAgentTurnPolicy(params.parentConversationId),
 			abortSignal: params.abortSignal,
 			onEvent: params.onEvent,
 			images: llmTurn.images
 		}), params.runId);
 	}
-	async switchModelForSession(sessionKey, modelId) {
-		if (!await this.modelManager.switchModelForSession(sessionKey, modelId)) return false;
-		await this.sessionConfigStore.update(sessionKey, { modelOverride: modelId });
-		if (this.agentManager.setModelForSession(sessionKey, modelId)) this.sessionTracker.touchSession(sessionKey);
+	async switchModelForSession(conversationId, modelId) {
+		if (!await this.modelManager.switchModelForSession(conversationId, modelId)) return false;
+		await this.sessionConfigStore.update(conversationId, { modelOverride: modelId });
+		if (this.agentManager.setModelForSession(conversationId, modelId)) this.sessionTracker.touchSession(conversationId);
 		return true;
 	}
 	/**
 	* Clears per-session model override so the next turn uses the configured agent default
 	* (e.g. cron isolated job with no explicit model).
 	*/
-	async resetSessionModelToAgentDefault(sessionKey) {
-		await this.sessionConfig.clearModelOverride(sessionKey);
+	async resetSessionModelToAgentDefault(conversationId) {
+		await this.sessionConfig.clearModelOverride(conversationId);
 	}
 	setStreamHandle(handle) {
 		this.streamManager.setHandle(handle);
@@ -639,20 +642,20 @@ var AgentService = class {
 		this.streamManager.clearHandle();
 	}
 	/** Last assistant visible plain text for a session (e.g. after a webchat stream). */
-	getLastAssistantPlainText(sessionKey) {
-		return this.sessionState.getLastAssistantText(sessionKey) ?? this.agentManager.getLastAssistantContent(sessionKey) ?? "";
+	getLastAssistantPlainText(conversationId) {
+		return this.sessionState.getLastAssistantText(conversationId) ?? this.agentManager.getLastAssistantContent(conversationId) ?? "";
 	}
-	beginInboundTurn(sessionKey) {
-		this.sessionState.beginInboundTurn(sessionKey);
+	beginInboundTurn(conversationId) {
+		this.sessionState.beginInboundTurn(conversationId);
 	}
-	endInboundTurn(sessionKey) {
-		this.sessionState.endInboundTurn(sessionKey);
+	endInboundTurn(conversationId) {
+		this.sessionState.endInboundTurn(conversationId);
 	}
-	getInboundTurnDepth(sessionKey) {
-		return this.sessionState.getInboundTurnDepth(sessionKey);
+	getInboundTurnDepth(conversationId) {
+		return this.sessionState.getInboundTurnDepth(conversationId);
 	}
-	takeTaskReviewStreamHint(sessionKey) {
-		return this.sessionState.takeTaskReviewStreamHint(sessionKey);
+	takeTaskReviewStreamHint(conversationId) {
+		return this.sessionState.takeTaskReviewStreamHint(conversationId);
 	}
 	async start() {
 		await this.sessionConfigStore.initialize();
@@ -681,18 +684,18 @@ var AgentService = class {
 	* Persist agent messages with the same sanitizer + transcript hygiene as AgentOrchestrator.
 	* Uses persistence hygiene so `thinking` blocks remain on disk for the web UI (LLM load path still drops them).
 	*/
-	notifySessionTitleUpdated(sessionKey, name) {
-		this.onSessionMetadataUpdated?.(sessionKey, { name });
+	notifySessionTitleUpdated(conversationId, name) {
+		this.onSessionMetadataUpdated?.(conversationId, { name });
 	}
 	/** Fire-and-forget provisional title from first user text (webchat sidebar). */
-	enqueueProvisionalSessionTitle(sessionKey, userText) {
+	enqueueProvisionalSessionTitle(conversationId, userText) {
 		(async () => {
 			try {
-				await maybeSetProvisionalSessionTitle(this.sessionStore, sessionKey, userText, (sk, name) => this.notifySessionTitleUpdated(sk, name));
+				await maybeSetProvisionalSessionTitle(this.sessionStore, conversationId, userText, (sk, name) => this.notifySessionTitleUpdated(sk, name));
 			} catch (err) {
 				log.warn({
 					err,
-					sessionKey
+					conversationId
 				}, "Provisional session title failed");
 			}
 		})();
@@ -700,34 +703,34 @@ var AgentService = class {
 	/**
 	* Fire-and-forget LLM refine after turn persist; skips user-locked and finalized LLM titles.
 	*/
-	enqueueMaybeAutoTitleAfterPersist(sessionKey) {
+	enqueueMaybeAutoTitleAfterPersist(conversationId) {
 		(async () => {
 			try {
 				let modelRef = getAgentDefaultModelRef(this.config.config ?? {}) ?? this.config.model;
 				if (!modelRef?.trim()) try {
-					modelRef = this.modelManager.getModelForSession(sessionKey);
+					modelRef = this.modelManager.getModelForSession(conversationId);
 				} catch {
 					modelRef = void 0;
 				}
-				await maybeRefineSessionTitleWithLlm(this.sessionStore, sessionKey, modelRef?.trim() || void 0, (sk, name) => this.notifySessionTitleUpdated(sk, name));
+				await maybeRefineSessionTitleWithLlm(this.sessionStore, conversationId, modelRef?.trim() || void 0, (sk, name) => this.notifySessionTitleUpdated(sk, name));
 			} catch (err) {
 				log.warn({
 					err,
-					sessionKey
+					conversationId
 				}, "Auto session title failed");
 			}
 		})();
 	}
-	async resolveSessionEndpoint(sessionKey) {
-		const metadata = await this.sessionStore.getMetadata(sessionKey).catch(() => null);
+	async resolveSessionEndpoint(conversationId) {
+		const metadata = await this.sessionStore.getMetadata(conversationId).catch(() => null);
 		return {
 			channel: metadata?.routing?.source?.trim() || metadata?.sourceChannel?.trim() || "cli",
 			chatId: metadata?.routing?.peerId?.trim() || metadata?.sourceChatId?.trim() || "main"
 		};
 	}
-	initSessionContext(sessionKey, channel, chatId, origin, senderId = "") {
+	initSessionContext(conversationId, channel, chatId, origin, senderId = "") {
 		const context = {
-			sessionKey,
+			conversationId,
 			channel,
 			chatId,
 			senderId,
@@ -735,20 +738,20 @@ var AgentService = class {
 			origin
 		};
 		this.contextMiddleware.onRequest({
-			sessionKey,
+			conversationId,
 			userId: context.senderId,
 			channel,
 			chatId
 		});
 		this.sessionContextManager.enter(context);
-		this.agentManager.getOrCreateAgent(sessionKey);
-		this.setupSessionEventHandling(sessionKey);
+		this.agentManager.getOrCreateAgent(conversationId);
+		this.setupSessionEventHandling(conversationId);
 		return context;
 	}
 	/**
 	* Persist inbound file attachments to the global media store.
 	*/
-	async prepareInboundAttachments(_sessionKey, attachments) {
+	async prepareInboundAttachments(_conversationId, attachments) {
 		return persistInboundAttachments(attachments, {
 			maxBytes: MAX_WEBCHAT_ATTACHMENT_FILE_BYTES,
 			resolveUri: async (uri) => {
@@ -788,13 +791,13 @@ var AgentService = class {
 	*/
 	async resetSession(key) {
 		const { abortEmbeddedRun } = await import("./embedded/runs.js");
-		const { retireSessionMcpRuntimeForSessionKey } = await import("./mcp/bundle-mcp-tools.js");
+		const { retireSessionMcpRuntimeForConversationId } = await import("./mcp/bundle-mcp-tools.js");
 		await abortEmbeddedRun(key);
 		const task = await this.sessionStore.reset(key);
 		if (!task) return null;
 		this.agentManager.removeAgent(key);
-		await retireSessionMcpRuntimeForSessionKey({
-			sessionKey: key,
+		await retireSessionMcpRuntimeForConversationId({
+			conversationId: key,
 			reason: "session-reset"
 		});
 		return task;
@@ -802,24 +805,24 @@ var AgentService = class {
 	/**
 	* Drop in-memory agent so the next turn reloads transcript from disk (e.g. after checkpoint restore).
 	*/
-	evictSessionAgent(sessionKey) {
-		this.agentManager.removeAgent(sessionKey);
+	evictSessionAgent(conversationId) {
+		this.agentManager.removeAgent(conversationId);
 	}
 	/**
 	* Load session working directory override into AgentManager, ensure directory exists.
 	* Call before AgentManager.getOrCreateAgent for this session.
 	*/
 	/** Workspace root for UI file tree / editor (same as agent tools after hydration). */
-	async getEffectiveWorkspacePathForSession(sessionKey) {
-		await this.sessionHydrator.workspace(sessionKey);
+	async getEffectiveWorkspacePathForSession(conversationId) {
+		await this.sessionHydrator.workspace(conversationId);
 		const cfg = this.config.config;
-		return effectiveWorkspacePathForSession(cfg, sessionKey, await this.sessionConfigStore.get(sessionKey), getProjectForSession(sessionKey));
+		return effectiveWorkspacePathForSession(cfg, conversationId, await this.sessionConfigStore.get(conversationId), getProjectForSession(conversationId));
 	}
 	/**
 	* Best-effort timezone resolution for webchat envelope timestamps.
 	* Reads the structured global user profile.
 	*/
-	resolveUserTimezoneForSession(sessionKey) {
+	resolveUserTimezoneForSession(conversationId) {
 		try {
 			if (!this.effectiveAppConfig()) return void 0;
 			return getUserTimezone();
@@ -830,20 +833,20 @@ var AgentService = class {
 	/**
 	* Setup event handling for a specific session
 	*/
-	setupSessionEventHandling(sessionKey) {
-		if (this.sessionState.hasSessionEventUnsubscriber(sessionKey)) return;
-		const unsubscribe = this.agentManager.subscribeToSession(sessionKey, (event) => {
-			this.handleSessionEvent(sessionKey, event);
+	setupSessionEventHandling(conversationId) {
+		if (this.sessionState.hasSessionEventUnsubscriber(conversationId)) return;
+		const unsubscribe = this.agentManager.subscribeToSession(conversationId, (event) => {
+			this.handleSessionEvent(conversationId, event);
 		});
-		if (unsubscribe) this.sessionState.setSessionEventUnsubscriber(sessionKey, unsubscribe);
+		if (unsubscribe) this.sessionState.setSessionEventUnsubscriber(conversationId, unsubscribe);
 	}
 	/**
 	* Handle events from a specific session's agent
 	*/
-	handleSessionEvent(sessionKey, event) {
+	handleSessionEvent(conversationId, event) {
 		const currentContext = this.sessionContextManager.getContext();
 		if (!currentContext) return;
-		if (currentContext.sessionKey !== sessionKey) return;
+		if (currentContext.conversationId !== conversationId) return;
 		if (event.type === "message_update") {
 			const msgEvent = event;
 			if (msgEvent.message?.role === "assistant") {
@@ -854,13 +857,13 @@ var AgentService = class {
 		}
 		this.agentEventHandler.handle(event, currentContext);
 	}
-	getContextWindowForSession(sessionKey) {
+	getContextWindowForSession(conversationId) {
 		try {
-			return this.modelManager.getResolvedModelForSession(sessionKey).contextWindow ?? 128e3;
+			return this.modelManager.getResolvedModelForSession(conversationId).contextWindow ?? 128e3;
 		} catch (err) {
 			log.warn({
 				err,
-				sessionKey
+				conversationId
 			}, "Failed to resolve session context window; using default");
 			return 128e3;
 		}

package/dist/src/agent/service.types.d.ts

@@ -41,11 +41,11 @@ export interface AgentServiceConfig {
      * When omitted, `AgentService` creates its own `SessionStore` (CLI / embedded).
      */
     sessionStore?: SessionStore;
-    onSessionMetadataUpdated?: (sessionKey: string, patch?: {
+    onSessionMetadataUpdated?: (conversationId: string, patch?: {
         name?: string;
     }) => void;
     /** Gateway: transcript append notification. */
-    onSessionTranscriptUpdated?: (sessionKey: string) => void;
+    onSessionTranscriptUpdated?: (conversationId: string) => void;
     /** Gateway/TUI: local skill catalog changed or skill config toggles changed. */
     onSkillsUpdated?: (payload: {
         reason: 'disk' | 'config';
@@ -63,7 +63,7 @@ export interface AgentServiceConfig {
 export interface AgentContext {
     channel: string;
     chatId: string;
-    sessionKey: string;
+    conversationId: string;
     senderId?: string;
     isGroup?: boolean;
 }

package/dist/src/agent/session/session-config-service.d.ts

@@ -52,27 +52,27 @@ export declare class SessionConfigService {
      * a session's persisted config. Returns `{ ok: false, error }` on the first
      * invalid field. Model and thinking are validated together and committed in one write.
      */
-    patch(sessionKey: string, partial: PatchSessionAgentConfigInput): Promise<PatchSessionAgentConfigResult>;
+    patch(conversationId: string, partial: PatchSessionAgentConfigInput): Promise<PatchSessionAgentConfigResult>;
     /** Materialize a restored/new chat choice; unavailable identities stay visible for repair. */
-    initializeModelSelection(sessionKey: string, modelRef: string, thinkingLevel?: string, configVersion?: number): Promise<PatchSessionAgentConfigResult>;
+    initializeModelSelection(conversationId: string, modelRef: string, thinkingLevel?: string, configVersion?: number): Promise<PatchSessionAgentConfigResult>;
     /**
      * Sync persisted session working directory for an automation run. Runs may
      * change when the automation is edited; an empty/missing input clears the
      * override so the session uses the effective agent default.
      */
-    applyAutomationWorkingDirectory(sessionKey: string, workingDirectory: string | undefined): Promise<void>;
+    applyAutomationWorkingDirectory(conversationId: string, workingDirectory: string | undefined): Promise<void>;
     /**
      * Persist an automation model override before the direct turn creates/hydrates
      * the AgentSession. Unlike the user-facing patch path, this must not call
      * `agentManager.setModelForSession`, because the automation session usually
      * does not exist yet.
      */
-    applyAutomationModelOverride(sessionKey: string, model: string | undefined): Promise<boolean>;
+    applyAutomationModelOverride(conversationId: string, model: string | undefined): Promise<boolean>;
     /**
      * Clear the session's model override (back to agent default). Used both by
      * {@link patch} and by `AgentService.resetSessionModelToAgentDefault`.
      */
-    clearModelOverride(sessionKey: string): Promise<void>;
+    clearModelOverride(conversationId: string): Promise<void>;
     private clearAutomationWorkingDirectoryOverride;
     /**
      * Apply the workingDirectory branch of `patch`. Returns the next-step result