@xopcai/xopc 0.0.285 → 0.0.291

package/dist/src/agent/service/direct-turn-helpers.js

@@ -1,5 +1,5 @@
 import { getClarificationResumeInput } from "../../storage/sqlite/clarification-wait-repository.js";
-import { getConnectionResumeInput } from "../../storage/sqlite/connection-wait-repository.js";
+import { getConnectionResumeInput, init_connection_wait_repository } from "../../storage/sqlite/connection-wait-repository.js";
 import { resolveImageHandlingStrategy } from "../image/vision-detection.js";
 import { hydrateUserTurnForLlm } from "../inbound/attachment-pipeline.js";
 import { buildTaskExecutionDirective } from "../../tasks/task-context-assembler.js";
@@ -20,11 +20,12 @@ import crypto from "node:crypto";
 * the entry points only manage their I/O specifics (event sink, voice STT,
 * TTS, transcript persistence).
 */
+init_connection_wait_repository();
 /** Workspace + model + thinking level — common prep before any direct turn. */
-async function hydratePerTurnState(deps, sessionKey, thinking) {
-	await deps.hydrateSessionWorkspaceFromStore(sessionKey);
-	await deps.hydrateSessionModelFromStore(sessionKey);
-	await deps.applyResolvedThinkingLevel(sessionKey, thinking);
+async function hydratePerTurnState(deps, conversationId, thinking) {
+	await deps.hydrateSessionWorkspaceFromStore(conversationId);
+	await deps.hydrateSessionModelFromStore(conversationId);
+	await deps.applyResolvedThinkingLevel(conversationId, thinking);
 }
 /**
 * Detect a slash command and, if registered, execute it and aggregate the reply
@@ -53,7 +54,7 @@ async function tryRunSlashCommand(deps, ctx, content, options) {
 	};
 	try {
 		const { aggregatedText, metadata } = await deps.commandHandler.executeCommandAndAggregateReply(parsed.command, parsed.args, {
-			sessionKey: ctx.sessionKey,
+			conversationId: ctx.conversationId,
 			channel: ctx.channel,
 			chatId: ctx.chatId,
 			senderId: ctx.senderId ?? "",
@@ -71,7 +72,7 @@ async function tryRunSlashCommand(deps, ctx, content, options) {
 		const em = err instanceof Error ? err.message : String(err);
 		deps.log.warn({
 			err,
-			sessionKey: ctx.sessionKey,
+			conversationId: ctx.conversationId,
 			command: parsed.command
 		}, `Slash command failed: ${em}`);
 		return {
@@ -87,14 +88,14 @@ async function tryRunSlashCommand(deps, ctx, content, options) {
 */
 async function runDirectAgentTurn(deps, input) {
 	const turnId = input.runId ?? crypto.randomUUID();
-	const isConnectionResume = Boolean(getConnectionResumeInput(input.sessionKey, turnId));
-	const isClarificationResume = Boolean(getClarificationResumeInput(input.sessionKey, turnId));
+	const isConnectionResume = Boolean(getConnectionResumeInput(input.conversationId, turnId));
+	const isClarificationResume = Boolean(getClarificationResumeInput(input.conversationId, turnId));
 	const isResume = isConnectionResume || isClarificationResume;
 	const userPlain = extractAgentUserPlainText(input.userMessage);
-	const userContext = await deps.agentManager.prepareUserTurnContext(input.userMessage, input.sessionKey, turnId);
+	const userContext = await deps.agentManager.prepareUserTurnContext(input.userMessage, input.conversationId, turnId);
 	const sourceContexts = input.sourceContexts ?? [];
-	const userMessageForModel = prependAgentContext(injectSourceContextsIntoUserMessage(userContext.modelMessage, sourceContexts), buildTaskExecutionDirective(input.sessionKey));
-	const modelRef = deps.modelManager.getModelForSession(input.sessionKey);
+	const userMessageForModel = prependAgentContext(injectSourceContextsIntoUserMessage(userContext.modelMessage, sourceContexts), buildTaskExecutionDirective(input.conversationId));
+	const modelRef = deps.modelManager.getModelForSession(input.conversationId);
 	const llmTurn = await hydrateUserTurnForLlm({
 		message: input.userMessage,
 		modelRef
@@ -103,7 +104,7 @@ async function runDirectAgentTurn(deps, input) {
 	const sourceImages = resolveImageHandlingStrategy(modelRef) === "native" ? [...input.sourceImages ?? [], ...contextImages] : [];
 	const llmImages = [...llmTurn.images, ...sourceImages];
 	const result = await runEmbeddedTurnForSession({
-		sessionKey: input.sessionKey,
+		conversationId: input.conversationId,
 		runId: turnId,
 		userMessage: userMessageForModel,
 		llmImages,
@@ -114,11 +115,11 @@ async function runDirectAgentTurn(deps, input) {
 		getConfig: () => deps.config,
 		abortSignal: input.abortSignal,
 		deadlineAtMs: input.deadlineAtMs,
-		beforeTurn: isResume ? void 0 : () => deps.agentManager.beginBackgroundReviewUserTurn(input.sessionKey),
+		beforeTurn: isResume ? void 0 : () => deps.agentManager.beginBackgroundReviewUserTurn(input.conversationId),
 		onEvent: input.onEvent
 	});
-	if (!isResume) await deps.agentManager.afterAgentTurn(input.sessionKey, userPlain, turnId);
-	if (!isResume && result.stopReason !== "connection_required" && result.stopReason !== "clarification_required") deps.agentManager.scheduleBackgroundReviewAfterUserTurn(input.sessionKey);
+	if (!isResume) await deps.agentManager.afterAgentTurn(input.conversationId, userPlain, turnId);
+	if (!isResume && result.stopReason !== "connection_required" && result.stopReason !== "clarification_required") deps.agentManager.scheduleBackgroundReviewAfterUserTurn(input.conversationId);
 	return result;
 }
 //#endregion

package/dist/src/agent/service/parse-outbound-session-key.d.ts

@@ -2,7 +2,7 @@ import type { Config } from '../../config/schema.js';
 /**
  * Map a session key to outbound channel routing (heartbeat/cron/virtual keys included).
  */
-export declare function parseOutboundSessionKey(sessionKey: string, config: Config | undefined): {
+export declare function parseOutboundConversationId(conversationId: string, config: Config | undefined): {
     channel: string;
     chatId: string;
 };

package/dist/src/agent/service/parse-outbound-session-key.js

@@ -5,10 +5,10 @@ import { INTERNAL_OUTBOUND_DROP_CHANNEL } from "../../channels/internal-outbound
 /**
 * Map a session key to outbound channel routing (heartbeat/cron/virtual keys included).
 */
-function parseOutboundSessionKey(sessionKey, config) {
-	const parts = sessionKey.split(":").filter(Boolean);
-	const first = parts[0] || "cli";
-	if (first === "heartbeat") {
+function parseOutboundConversationId(conversationId, config) {
+	const metadata = getSessionMetadata(conversationId);
+	if (!metadata) throw new Error(`Conversation not found: ${conversationId}`);
+	if (metadata.sessionType === "heartbeat") {
 		const hb = config?.gateway?.heartbeat;
 		const target = hb?.target?.trim();
 		const targetChatId = hb?.targetChatId?.trim();
@@ -18,10 +18,9 @@ function parseOutboundSessionKey(sessionKey, config) {
 		};
 		return {
 			channel: INTERNAL_OUTBOUND_DROP_CHANNEL,
-			chatId: parts.slice(1).join(":") || "heartbeat"
+			chatId: conversationId
 		};
 	}
-	const metadata = getSessionMetadata(sessionKey);
 	const routing = metadata?.routing;
 	if (routing?.source && routing.peerId) return {
 		channel: routing.source,
@@ -31,9 +30,9 @@ function parseOutboundSessionKey(sessionKey, config) {
 		channel: metadata.sourceChannel,
 		chatId: metadata.sourceChatId
 	};
-	if (first === "cron") return {
+	if (metadata.sessionType === "cron") return {
 		channel: INTERNAL_OUTBOUND_DROP_CHANNEL,
-		chatId: parts.slice(1).join(":") || "cron"
+		chatId: conversationId
 	};
 	return {
 		channel: "cli",
@@ -41,4 +40,4 @@ function parseOutboundSessionKey(sessionKey, config) {
 	};
 }
 //#endregion
-export { parseOutboundSessionKey };
+export { parseOutboundConversationId };

package/dist/src/agent/service/process-direct-one-shot.d.ts

@@ -9,29 +9,29 @@ import type { InboundAttachmentInput, MediaRef } from '../../channels/attachment
 export type RunProcessDirectDeps = {
     log: ProcessDirectStreamLog;
     config: Config;
-    resolveSessionEndpoint: (sessionKey: string) => Promise<{
+    resolveSessionEndpoint: (conversationId: string) => Promise<{
         channel: string;
         chatId: string;
     }>;
-    initSessionContext: (sessionKey: string, channel: string, chatId: string, origin: TurnOrigin) => void;
-    hydrateSessionWorkspaceFromStore: (sessionKey: string) => Promise<void>;
-    hydrateSessionModelFromStore: (sessionKey: string) => Promise<void>;
+    initSessionContext: (conversationId: string, channel: string, chatId: string, origin: TurnOrigin) => void;
+    hydrateSessionWorkspaceFromStore: (conversationId: string) => Promise<void>;
+    hydrateSessionModelFromStore: (conversationId: string) => Promise<void>;
     agentManager: AgentInstanceGateway;
     sessionStore: SessionStore;
     modelManager: ModelManager;
-    applyResolvedThinkingLevel: (sessionKey: string, thinking?: string | null) => Promise<void>;
-    prepareInboundAttachments: (sessionKey: string, attachments?: InboundAttachmentInput[]) => Promise<MediaRef[] | undefined>;
+    applyResolvedThinkingLevel: (conversationId: string, thinking?: string | null) => Promise<void>;
+    prepareInboundAttachments: (conversationId: string, attachments?: InboundAttachmentInput[]) => Promise<MediaRef[] | undefined>;
     commandHandler: Pick<CommandHandler, 'executeCommandAndAggregateReply'>;
-    onTurnComplete?: (sessionKey: string, lastAssistantText?: string) => void;
+    onTurnComplete?: (conversationId: string, lastAssistantText?: string) => void;
     endDirectRequestContext: () => void;
-    resetSession: (sessionKey: string) => Promise<{
-        sessionId: string;
-        previousSessionId: string;
+    resetSession: (conversationId: string) => Promise<{
+        transcriptId: string;
+        previousTranscriptId: string;
     } | null>;
 };
 export declare function runProcessDirect(deps: RunProcessDirectDeps, input: {
     content: string;
-    sessionKey: string;
+    conversationId: string;
     origin: TurnOrigin;
     attachments?: InboundAttachmentInput[];
     thinking?: string;

package/dist/src/agent/service/process-direct-one-shot.js

@@ -8,31 +8,31 @@ function isReviewOutput(value) {
 	return !!value && typeof value === "object" && !Array.isArray(value) && value.type === "review";
 }
 async function runProcessDirect(deps, input) {
-	const { channel, chatId } = await deps.resolveSessionEndpoint(input.sessionKey);
-	deps.initSessionContext(input.sessionKey, channel, chatId, input.origin);
+	const { channel, chatId } = await deps.resolveSessionEndpoint(input.conversationId);
+	deps.initSessionContext(input.conversationId, channel, chatId, input.origin);
 	try {
 		let turnBody = input.content;
 		let resetTriggeredAtInit = false;
 		const turn = await initSessionTurn({
 			cfg: deps.config,
-			sessionKey: input.sessionKey,
+			conversationId: input.conversationId,
 			body: input.content,
 			resetSession: deps.resetSession
 		});
 		resetTriggeredAtInit = turn.resetTriggered;
 		if (turn.bareReset && turn.ackMessage) return turn.ackMessage;
 		turnBody = turn.bodyStripped;
-		await hydratePerTurnState(deps, input.sessionKey, input.thinking);
-		const prepared = await deps.prepareInboundAttachments(input.sessionKey, input.attachments);
+		await hydratePerTurnState(deps, input.conversationId, input.thinking);
+		const prepared = await deps.prepareInboundAttachments(input.conversationId, input.attachments);
 		const slash = await tryRunSlashCommand(deps, {
-			sessionKey: input.sessionKey,
+			conversationId: input.conversationId,
 			channel,
 			chatId
 		}, turnBody, { skipResetCommands: resetTriggeredAtInit });
 		if (slash.matched) {
 			const trimmed = slash.aggregatedText.trim();
 			if (trimmed) {
-				await deps.sessionStore.appendTranscriptMessage(input.sessionKey, {
+				await deps.sessionStore.appendTranscriptMessage(input.conversationId, {
 					role: "assistant",
 					content: isReviewOutput(slash.metadata?.review) ? [slash.metadata.review] : [{
 						type: "text",
@@ -41,40 +41,40 @@ async function runProcessDirect(deps, input) {
 					timestamp: Date.now(),
 					...slash.metadata && Object.keys(slash.metadata).length > 0 ? { metadata: slash.metadata } : {}
 				});
-				if (input.origin.type === "system" && input.origin.source === "automation") await deps.sessionStore.updateMetadata(input.sessionKey, { hiddenFromSessionList: false });
-				deps.onTurnComplete?.(input.sessionKey, trimmed);
+				if (input.origin.type === "system" && input.origin.source === "automation") await deps.sessionStore.updateMetadata(input.conversationId, { hiddenFromSessionList: false });
+				deps.onTurnComplete?.(input.conversationId, trimmed);
 			}
 			return slash.aggregatedText ?? "";
 		}
-		const skillTurn = deps.agentManager.prepareSkillTurn(input.sessionKey, turnBody);
+		const skillTurn = deps.agentManager.prepareSkillTurn(input.conversationId, turnBody);
 		const textForDirect = skillTurn.text;
 		const userMessage = await buildDirectUserMessageContent({
 			content: textForDirect,
 			attachments: prepared,
-			sessionKey: input.sessionKey,
+			conversationId: input.conversationId,
 			config: deps.config,
 			agentManager: deps.agentManager,
 			modelManager: deps.modelManager
 		});
 		const pendingUserMessage = userMessage;
-		setPendingTranscriptUserMessage(input.sessionKey, pendingUserMessage);
+		setPendingTranscriptUserMessage(input.conversationId, pendingUserMessage);
 		const result = await (async () => {
 			try {
-				return await deps.agentManager.withSkillCapabilities(input.sessionKey, skillTurn.activatedCapabilityNames, () => runDirectAgentTurn({
+				return await deps.agentManager.withSkillCapabilities(input.conversationId, skillTurn.activatedCapabilityNames, () => runDirectAgentTurn({
 					...deps,
 					config: deps.config
 				}, {
-					sessionKey: input.sessionKey,
+					conversationId: input.conversationId,
 					runId: input.runId,
 					userMessage,
 					abortSignal: input.signal,
 					deadlineAtMs: input.deadlineAtMs
 				}));
 			} finally {
-				clearPendingTranscriptUserMessage(input.sessionKey, pendingUserMessage);
+				clearPendingTranscriptUserMessage(input.conversationId, pendingUserMessage);
 			}
 		})();
-		deps.onTurnComplete?.(input.sessionKey, result.lastAssistantText);
+		deps.onTurnComplete?.(input.conversationId, result.lastAssistantText);
 		if (!result.ok) throw new Error(result.errorMessage ?? "Agent turn failed");
 		return result.lastAssistantText ?? "";
 	} finally {

package/dist/src/agent/service/process-direct-streaming.d.ts

@@ -16,50 +16,50 @@ export type ProcessDirectStreamLog = {
 };
 export interface ProcessDirectStreamingDeps {
     log: ProcessDirectStreamLog;
-    resolveSessionEndpoint: (sessionKey: string) => Promise<{
+    resolveSessionEndpoint: (conversationId: string) => Promise<{
         channel: string;
         chatId: string;
     }>;
-    initDirectStreamingSession: (sessionKey: string, channel: string, chatId: string, origin: TurnOrigin) => SessionContext;
-    registerWebchatStreamPublisher: (sessionKey: string, publisher: (event: {
+    initDirectStreamingSession: (conversationId: string, channel: string, chatId: string, origin: TurnOrigin) => SessionContext;
+    registerWebchatStreamPublisher: (conversationId: string, publisher: (event: {
         type: string;
         [key: string]: unknown;
     }) => void) => void;
-    unregisterWebchatStreamPublisher: (sessionKey: string) => void;
+    unregisterWebchatStreamPublisher: (conversationId: string) => void;
     agentManager: AgentInstanceGateway;
-    hydrateSessionWorkspaceFromStore: (sessionKey: string) => Promise<void>;
-    hydrateSessionModelFromStore: (sessionKey: string) => Promise<void>;
+    hydrateSessionWorkspaceFromStore: (conversationId: string) => Promise<void>;
+    hydrateSessionModelFromStore: (conversationId: string) => Promise<void>;
     sessionStore: SessionStore;
     modelManager: ModelManager;
-    applyResolvedThinkingLevel: (sessionKey: string, thinking?: string | null) => Promise<void>;
+    applyResolvedThinkingLevel: (conversationId: string, thinking?: string | null) => Promise<void>;
     getConfig: () => Config | undefined;
     sessionConfigStore: SessionConfigStore;
     commandHandler: Pick<CommandHandler, 'executeCommandAndAggregateReply'>;
-    prepareInboundAttachments: (sessionKey: string, attachments?: DirectStreamInboundAttachment[]) => Promise<MediaRef[] | undefined>;
-    buildTranscriptUserMessage: (content: string, prepared: MediaRef[] | undefined, sessionKey: string) => Promise<TranscriptUserMessage>;
-    recordTaskReviewStreamHint?: (sessionKey: string, task: {
+    prepareInboundAttachments: (conversationId: string, attachments?: DirectStreamInboundAttachment[]) => Promise<MediaRef[] | undefined>;
+    buildTranscriptUserMessage: (content: string, prepared: MediaRef[] | undefined, conversationId: string) => Promise<TranscriptUserMessage>;
+    recordTaskReviewStreamHint?: (conversationId: string, task: {
         skipTaskReview: boolean;
     }) => void;
-    onTurnComplete?: (sessionKey: string, lastAssistantText?: string) => void;
-    enqueueProvisionalSessionTitle?: (sessionKey: string, userText: string) => void;
+    onTurnComplete?: (conversationId: string, lastAssistantText?: string) => void;
+    enqueueProvisionalSessionTitle?: (conversationId: string, userText: string) => void;
     /** Disk-only transcript sync (slash receipt already streamed as tokens). */
-    reloadWebchatTranscript?: (sessionKey: string) => void;
-    maybeEmitWebchatTts: (sessionKey: string, hadInboundVoice: boolean) => Promise<{
+    reloadWebchatTranscript?: (conversationId: string) => void;
+    maybeEmitWebchatTts: (conversationId: string, hadInboundVoice: boolean) => Promise<{
         type: 'tts_audio';
         uri: string;
         mimeType: string;
         name: string;
     } | null>;
     endDirectRequestContext: () => void;
-    resetSession: (sessionKey: string) => Promise<{
-        sessionId: string;
-        previousSessionId: string;
+    resetSession: (conversationId: string) => Promise<{
+        transcriptId: string;
+        previousTranscriptId: string;
     } | null>;
     sourceContextResolver?: AgentSourceContextResolver;
 }
 export interface ProcessDirectStreamingInput {
     content: string;
-    sessionKey?: string;
+    conversationId?: string;
     origin: TurnOrigin;
     attachments?: DirectStreamInboundAttachment[];
     thinking?: string;

package/dist/src/agent/service/process-direct-streaming.js

@@ -1,5 +1,7 @@
 import { getClarificationResumeInput } from "../../storage/sqlite/clarification-wait-repository.js";
-import { getConnectionResumeInput } from "../../storage/sqlite/connection-wait-repository.js";
+import { getConnectionResumeInput, init_connection_wait_repository } from "../../storage/sqlite/connection-wait-repository.js";
+import { init_agent_scope, resolveDefaultAgentId } from "../agent-scope.js";
+import { init_agent_session_key, resolveAgentMainConversationId } from "../../routing/agent-session-key.js";
 import { readAgentMessageContent } from "../memory/agent-message-access.js";
 import { abortEmbeddedRun } from "../embedded/runs.js";
 import { clearPendingTranscriptUserMessage, setPendingTranscriptUserMessage } from "../inbound/attachment-pipeline.js";
@@ -17,6 +19,9 @@ import { AsyncQueue, AsyncQueueOverflowError } from "./async-queue.js";
 import { hydratePerTurnState, runDirectAgentTurn, tryRunSlashCommand } from "./direct-turn-helpers.js";
 import { isSuccessfulWebchatTtsToolEvent } from "./webchat-tts.js";
 //#region src/agent/service/process-direct-streaming.ts
+init_agent_session_key();
+init_agent_scope();
+init_connection_wait_repository();
 const MAX_BUFFERED_STREAM_EVENTS = 512;
 const LOSSY_STREAM_EVENT_TYPES = new Set([
 	"message_update",
@@ -125,12 +130,12 @@ function pushAssistantReceipt(queue, text, runId, metadata) {
 	});
 }
 async function* runProcessDirectStreaming(deps, input) {
-	const sessionKey = input.sessionKey ?? "agent:main:main";
-	const isConnectionResume = Boolean(input.runId && getConnectionResumeInput(sessionKey, input.runId));
-	const isClarificationResume = Boolean(input.runId && getClarificationResumeInput(sessionKey, input.runId));
+	const conversationId = input.conversationId ?? resolveAgentMainConversationId({ agentId: resolveDefaultAgentId(deps.getConfig()) });
+	const isConnectionResume = Boolean(input.runId && getConnectionResumeInput(conversationId, input.runId));
+	const isClarificationResume = Boolean(input.runId && getClarificationResumeInput(conversationId, input.runId));
 	const isInternalResume = isConnectionResume || isClarificationResume;
-	const { channel, chatId } = await deps.resolveSessionEndpoint(sessionKey);
-	const context = deps.initDirectStreamingSession(sessionKey, channel, chatId, input.origin);
+	const { channel, chatId } = await deps.resolveSessionEndpoint(conversationId);
+	const context = deps.initDirectStreamingSession(conversationId, channel, chatId, input.origin);
 	const queue = new AsyncQueue({
 		maxBuffered: MAX_BUFFERED_STREAM_EVENTS,
 		isDroppable: (event) => LOSSY_STREAM_EVENT_TYPES.has(event.type)
@@ -144,15 +149,15 @@ async function* runProcessDirectStreaming(deps, input) {
 		let provider;
 		let modelRef;
 		try {
-			provider = deps.modelManager.getResolvedModelForSession(sessionKey).provider;
-			modelRef = deps.modelManager.getModelForSession(sessionKey);
+			provider = deps.modelManager.getResolvedModelForSession(conversationId).provider;
+			modelRef = deps.modelManager.getModelForSession(conversationId);
 		} catch {}
 		return formatAgentRunErrorForClient(raw, {
 			provider,
 			modelRef
 		});
 	};
-	if (channel === "webchat") deps.registerWebchatStreamPublisher(sessionKey, pushVisible);
+	if (channel === "webchat") deps.registerWebchatStreamPublisher(conversationId, pushVisible);
 	const signal = input.signal;
 	let userAborted = false;
 	let abortHandled = false;
@@ -172,7 +177,7 @@ async function* runProcessDirectStreaming(deps, input) {
 			if (cfg) {
 				const turn = await initSessionTurn({
 					cfg,
-					sessionKey,
+					conversationId,
 					body: input.content,
 					resetSession: deps.resetSession
 				});
@@ -185,19 +190,19 @@ async function* runProcessDirectStreaming(deps, input) {
 				}
 				turnBody = turn.bodyStripped;
 				if (turn.isNewSession) deps.log.debug({
-					sessionKey,
-					sessionId: turn.sessionId,
-					previousSessionId: turn.previousSessionId,
+					conversationId,
+					transcriptId: turn.transcriptId,
+					previousTranscriptId: turn.previousTranscriptId,
 					resetTriggered: turn.resetTriggered,
 					staleRollover: turn.staleRollover
 				}, "Session reset boundary at direct turn start");
 			}
-			await hydratePerTurnState(deps, sessionKey, input.thinking);
+			await hydratePerTurnState(deps, conversationId, input.thinking);
 			{
 				const defReason = channel === "webchat" ? resolveConfiguredActivityDetailDefault(cfg) : "stream";
-				reasoningLevel = await resolveEffectiveReasoningLevel(deps.sessionConfigStore, sessionKey, defReason);
+				reasoningLevel = await resolveEffectiveReasoningLevel(deps.sessionConfigStore, conversationId, defReason);
 			}
-			const prepared = await deps.prepareInboundAttachments(sessionKey, input.attachments);
+			const prepared = await deps.prepareInboundAttachments(conversationId, input.attachments);
 			const sttCfg = mergeSttConfigFromAppConfig(deps.getConfig()?.tools?.media?.audio, deps.getConfig()?.tools?.media);
 			const voiceMerge = await mergeVoiceTranscriptsIntoUserText(prepared, turnBody, sttCfg);
 			mergedUserText = voiceMerge.text;
@@ -219,7 +224,7 @@ async function* runProcessDirectStreaming(deps, input) {
 				if (abortHandled) return;
 				abortHandled = true;
 				userAborted = true;
-				abortEmbeddedRun(sessionKey);
+				abortEmbeddedRun(conversationId);
 				queue.close();
 			};
 			if (signal) {
@@ -230,7 +235,7 @@ async function* runProcessDirectStreaming(deps, input) {
 				signal.addEventListener("abort", armAbort, { once: true });
 			}
 			const slash = await tryRunSlashCommand(deps, {
-				sessionKey,
+				conversationId,
 				channel,
 				chatId,
 				senderId: context.senderId,
@@ -267,15 +272,15 @@ async function* runProcessDirectStreaming(deps, input) {
 				});
 				return;
 			}
-			const skillTurn = deps.agentManager.prepareSkillTurn(sessionKey, mergedUserText);
+			const skillTurn = deps.agentManager.prepareSkillTurn(conversationId, mergedUserText);
 			const textForAgent = skillTurn.text;
-			const userMessage = await deps.buildTranscriptUserMessage(textForAgent, prepared, sessionKey);
+			const userMessage = await deps.buildTranscriptUserMessage(textForAgent, prepared, conversationId);
 			const sourceContexts = [...input.sourceContexts ?? []];
 			if (deps.sourceContextResolver) {
-				const metadata = await deps.sessionStore.getMetadata(sessionKey).catch(() => null);
+				const metadata = await deps.sessionStore.getMetadata(conversationId).catch(() => null);
 				const sourceBinding = metadata?.customData && typeof metadata.customData === "object" ? metadata.customData.sourceBinding : void 0;
 				if (isSessionSourceBinding(sourceBinding)) {
-					const sourceContext = await deps.sourceContextResolver(sourceBinding, sessionKey);
+					const sourceContext = await deps.sourceContextResolver(sourceBinding, conversationId);
 					if (sourceContext && !sourceContexts.some((context) => context.kind === sourceContext.kind && context.sourceId === sourceContext.sourceId)) sourceContexts.push(sourceContext);
 				}
 			}
@@ -287,18 +292,18 @@ async function* runProcessDirectStreaming(deps, input) {
 					media: userMessage.media,
 					metadata: sourceContexts.length > 0 ? { sourceContexts: sourceContexts.map(summarizeSourceContext) } : void 0
 				});
-				if (textForAgent.trim()) deps.enqueueProvisionalSessionTitle?.(sessionKey, textForAgent);
+				if (textForAgent.trim()) deps.enqueueProvisionalSessionTitle?.(conversationId, textForAgent);
 			}
 			const pendingUserMessage = sourceContexts.length > 0 ? injectSourceContextsIntoUserMessage(userMessage, sourceContexts) : userMessage;
-			if (!isInternalResume) setPendingTranscriptUserMessage(sessionKey, pendingUserMessage);
+			if (!isInternalResume) setPendingTranscriptUserMessage(conversationId, pendingUserMessage);
 			try {
-				const result = await deps.agentManager.withSkillCapabilities(sessionKey, skillTurn.activatedCapabilityNames, () => runDirectAgentTurn({
+				const result = await deps.agentManager.withSkillCapabilities(conversationId, skillTurn.activatedCapabilityNames, () => runDirectAgentTurn({
 					sessionStore: deps.sessionStore,
 					agentManager: deps.agentManager,
 					modelManager: deps.modelManager,
 					config: deps.getConfig()
 				}, {
-					sessionKey,
+					conversationId,
 					userMessage,
 					abortSignal: signal,
 					sourceContexts,
@@ -311,21 +316,21 @@ async function* runProcessDirectStreaming(deps, input) {
 						pushVisible(event);
 					}
 				}));
-				if (result.lastAssistantText) deps.onTurnComplete?.(sessionKey, result.lastAssistantText);
+				if (result.lastAssistantText) deps.onTurnComplete?.(conversationId, result.lastAssistantText);
 				if (!result.ok && result.errorMessage && !abortHandled) pushVisible({
 					type: "error",
 					content: formatStreamError(result.errorMessage)
 				});
 			} finally {
-				if (!isInternalResume) clearPendingTranscriptUserMessage(sessionKey, pendingUserMessage);
+				if (!isInternalResume) clearPendingTranscriptUserMessage(conversationId, pendingUserMessage);
 			}
 		} catch (err) {
 			if (err instanceof AsyncQueueOverflowError) {
 				streamOverflowed = true;
-				await abortEmbeddedRun(sessionKey).catch(() => false);
+				await abortEmbeddedRun(conversationId).catch(() => false);
 				deps.log.warn({
 					err,
-					sessionKey,
+					conversationId,
 					maxBuffered: err.maxBuffered
 				}, "Aborted agent stream because the consumer could not keep up with critical events");
 			} else if (!abortHandled) pushVisible({
@@ -334,16 +339,16 @@ async function* runProcessDirectStreaming(deps, input) {
 			});
 		} finally {
 			if (queue.droppedCount > 0) deps.log.warn({
-				sessionKey,
+				conversationId,
 				droppedEvents: queue.droppedCount
 			}, "Coalesced stream progress events because the consumer fell behind");
 			if (!userAborted && !streamOverflowed && channel === "webchat" && !explicitTtsEmitted && input.presentation !== "voice") try {
-				const ttsAudioEvent = await deps.maybeEmitWebchatTts(sessionKey, inboundVoice);
+				const ttsAudioEvent = await deps.maybeEmitWebchatTts(conversationId, inboundVoice);
 				if (ttsAudioEvent) queue.push(ttsAudioEvent);
 			} catch (ttsErr) {
 				deps.log.warn({
 					err: ttsErr,
-					sessionKey
+					conversationId
 				}, "Failed to emit TTS audio before stream close");
 			}
 			queue.close();
@@ -361,8 +366,8 @@ async function* runProcessDirectStreaming(deps, input) {
 				}],
 				timestamp: Date.now()
 			};
-			await deps.sessionStore.appendTranscriptMessage(sessionKey, userMsg);
-			for (const traceRow of slashTraceRows) await deps.sessionStore.appendTranscriptContextEntry(sessionKey, traceRow);
+			await deps.sessionStore.appendTranscriptMessage(conversationId, userMsg);
+			for (const traceRow of slashTraceRows) await deps.sessionStore.appendTranscriptContextEntry(conversationId, traceRow);
 			if (webchatSlashReceipt?.trim()) {
 				const assistantMsg = {
 					role: "assistant",
@@ -373,18 +378,18 @@ async function* runProcessDirectStreaming(deps, input) {
 					timestamp: Date.now(),
 					...slashCommandMetadata && Object.keys(slashCommandMetadata).length > 0 ? { metadata: slashCommandMetadata } : {}
 				};
-				await deps.sessionStore.appendTranscriptMessage(sessionKey, assistantMsg);
+				await deps.sessionStore.appendTranscriptMessage(conversationId, assistantMsg);
 			}
-			deps.reloadWebchatTranscript?.(sessionKey);
+			deps.reloadWebchatTranscript?.(conversationId);
 		} catch (err) {
 			deps.log.warn({
 				err,
-				sessionKey
+				conversationId
 			}, "Failed to persist webchat slash command receipt");
 		}
-		deps.recordTaskReviewStreamHint?.(sessionKey, { skipTaskReview: ranSlashCommand });
+		deps.recordTaskReviewStreamHint?.(conversationId, { skipTaskReview: ranSlashCommand });
 	} finally {
-		if (channel === "webchat") deps.unregisterWebchatStreamPublisher(sessionKey);
+		if (channel === "webchat") deps.unregisterWebchatStreamPublisher(conversationId);
 		deps.endDirectRequestContext();
 	}
 }

package/dist/src/agent/service/session-context-report.d.ts

@@ -1,6 +1,6 @@
 /** Assembled snapshot for `/context` (list, detail markdown, or JSON). */
 export type SessionContextReportInput = {
-    sessionKey: string;
+    conversationId: string;
     mode: 'list' | 'detail' | 'json';
     model: string;
     workspacePath: string;

package/dist/src/agent/service/session-context-report.js

@@ -1,8 +1,8 @@
 //#region src/agent/service/session-context-report.ts
 function formatSessionContextReport(input) {
-	const { sessionKey, mode, model, workspacePath, agentId, messageCount, contextWindowNominal: cw, estimatedTranscriptTokens: estTokens, thinkingDefault, reasoningDefault, verboseDefault, compaction, toolsFlagsSummary, windowStats, compactionRunStats } = input;
+	const { conversationId, mode, model, workspacePath, agentId, messageCount, contextWindowNominal: cw, estimatedTranscriptTokens: estTokens, thinkingDefault, reasoningDefault, verboseDefault, compaction, toolsFlagsSummary, windowStats, compactionRunStats } = input;
 	const payload = {
-		sessionKey,
+		conversationId,
 		model,
 		workspacePath,
 		agentId,
@@ -22,7 +22,7 @@ function formatSessionContextReport(input) {
 	const lines = [
 		"📎 *Context overview*",
 		"",
-		`• Session: \`${sessionKey}\``,
+		`• Session: \`${conversationId}\``,
 		`• Model: \`${model}\``,
 		`• Agent profile: \`${agentId}\``,
 		`• Workspace: \`${workspacePath}\``,

package/dist/src/agent/service/webchat-tts.d.ts

@@ -10,7 +10,7 @@ export type WebchatTtsResult = {
 export type WebchatTtsDeps = {
     config: Config | undefined;
     sessionStore: SessionStore;
-    getLastAssistantPlainText: (sessionKey: string) => string;
+    getLastAssistantPlainText: (conversationId: string) => string;
     log: {
         warn: (obj: Record<string, unknown>, msg: string) => void;
     };
@@ -20,5 +20,5 @@ export declare function isSuccessfulWebchatTtsToolEvent(event: unknown): boolean
 /**
  * Generate TTS for webchat when config allows; persist under `{stateDir}/media/tts/`.
  */
-export declare function maybeEmitWebchatTts(deps: WebchatTtsDeps, sessionKey: string, hadInboundVoice: boolean): Promise<WebchatTtsResult | null>;
-export declare function appendMediaToLastAssistant(sessionStore: SessionStore, sessionKey: string, ref: MediaRef): Promise<void>;
+export declare function maybeEmitWebchatTts(deps: WebchatTtsDeps, conversationId: string, hadInboundVoice: boolean): Promise<WebchatTtsResult | null>;
+export declare function appendMediaToLastAssistant(sessionStore: SessionStore, conversationId: string, ref: MediaRef): Promise<void>;