@xopcai/xopc 0.0.285 → 0.0.286

package/dist/src/chat-commands/builtins/thinking.js

@@ -1,10 +1,10 @@
 import { formatThinkingLevels, normalizeReasoningLevel, normalizeThinkLevel, normalizeVerboseLevel } from "../../agent/transcript/thinking-types.js";
 import { commandRegistry } from "../registry.js";
 //#region src/chat-commands/builtins/thinking.ts
-async function setSessionAgentField(store, sessionKey, field, value) {
+async function setSessionAgentField(store, conversationId, field, value) {
 	if (!store) return;
-	const existing = await store.get(sessionKey) ?? {};
-	await store.set(sessionKey, {
+	const existing = await store.get(conversationId) ?? {};
+	await store.set(conversationId, {
 		...existing,
 		[field]: value
 	});
@@ -37,7 +37,7 @@ const thinkCommand = {
 			content: `❌ Invalid thinking level: ${args}\n\nAvailable levels: ${formatThinkingLevels()}\n\nUsage: /think <level>\nExample: /think high`,
 			success: false
 		};
-		await setSessionAgentField(ctx.getSessionConfigStore?.(), ctx.sessionKey, "thinkingLevel", level);
+		await setSessionAgentField(ctx.getSessionConfigStore?.(), ctx.conversationId, "thinkingLevel", level);
 		ctx.syncAgentThinkingLevel?.(level);
 		return {
 			content: `🧠 *Thinking Level Set*\n\nLevel: *${level}*\n${{
@@ -82,7 +82,7 @@ const reasoningCommand = {
 			content: `❌ Invalid reasoning mode: ${args}\n\nAvailable modes: off, on, stream\n\nUsage: /reasoning <mode>\nExample: /reasoning stream`,
 			success: false
 		};
-		await setSessionAgentField(ctx.getSessionConfigStore?.(), ctx.sessionKey, "reasoningLevel", level);
+		await setSessionAgentField(ctx.getSessionConfigStore?.(), ctx.conversationId, "reasoningLevel", level);
 		return {
 			content: `💭 *Reasoning Visibility Set*\n\nMode: *${level}*\n${{
 				off: "Hide reasoning from user",
@@ -114,7 +114,7 @@ const verboseCommand = {
 		await ctx.setTyping(true);
 		if (!args.trim()) {
 			const newLevel = await ctx.getVerboseLevel?.() === "on" ? "off" : "on";
-			await setSessionAgentField(ctx.getSessionConfigStore?.(), ctx.sessionKey, "verboseLevel", newLevel);
+			await setSessionAgentField(ctx.getSessionConfigStore?.(), ctx.conversationId, "verboseLevel", newLevel);
 			return {
 				content: `📝 *Verbose Mode*\n\nMode: *${newLevel}*\n\n${newLevel === "on" ? "Verbose output enabled (process lifetime)." : "Verbose output disabled (process lifetime)."}`,
 				success: true
@@ -125,7 +125,7 @@ const verboseCommand = {
 			content: `❌ Invalid verbose mode: ${args}\n\nAvailable modes: off, on, full\n\nUsage: /verbose [mode]\nExample: /verbose on`,
 			success: false
 		};
-		await setSessionAgentField(ctx.getSessionConfigStore?.(), ctx.sessionKey, "verboseLevel", level);
+		await setSessionAgentField(ctx.getSessionConfigStore?.(), ctx.conversationId, "verboseLevel", level);
 		return {
 			content: `📝 *Verbose Mode Set*\n\nMode: *${level}*\n${{
 				off: "Minimal output",

package/dist/src/chat-commands/builtins/understanding.js

@@ -23,7 +23,7 @@ const rememberCommand = {
 	acceptsArgs: true,
 	examples: ["/remember I prefer concise updates", "/remember --session This chat is about launch planning"],
 	handler: async (ctx, args) => {
-		if ((await ctx.getSessionConfigStore?.().get(ctx.sessionKey))?.userContextMode === "temporary") return {
+		if ((await ctx.getSessionConfigStore?.().get(ctx.conversationId))?.userContextMode === "temporary") return {
 			content: "This conversation is temporary, so it cannot save user understanding.",
 			success: false
 		};
@@ -45,7 +45,7 @@ const rememberCommand = {
 			kind: "derived_insight",
 			scope: sessionOnly ? {
 				type: "session",
-				id: ctx.sessionKey
+				id: ctx.conversationId
 			} : { type: "global" },
 			authority: "user_explicit",
 			confidence: 1,
@@ -96,9 +96,9 @@ const learningCommand = {
 			content: "Usage: /learning on | off | temporary | status",
 			success: false
 		};
-		if (action !== "status") await store.update(ctx.sessionKey, { userContextMode: action === "on" ? "enabled" : action });
+		if (action !== "status") await store.update(ctx.conversationId, { userContextMode: action === "on" ? "enabled" : action });
 		const globallyEnabled = ctx.config.userContext.enabled;
-		const mode = (await store.get(ctx.sessionKey))?.userContextMode ?? "enabled";
+		const mode = (await store.get(ctx.conversationId))?.userContextMode ?? "enabled";
 		return {
 			content: globallyEnabled && mode === "enabled" ? "User understanding is enabled for this conversation." : globallyEnabled && mode === "temporary" ? "This is a temporary conversation. Stored user context is not read, and this conversation does not update user understanding." : globallyEnabled ? "User understanding is off for this conversation. Existing chat history is still stored; use /remember for anything you explicitly want saved." : "User understanding is disabled globally. Existing chat history is still stored.",
 			success: true

package/dist/src/chat-commands/builtins/workflow.js

@@ -139,20 +139,20 @@ async function runWorkflowFromCommand(ctx, args) {
 			success: false
 		};
 	}
-	const agentId = extractProfileAgentId(ctx.sessionKey, ctx.config);
+	const agentId = extractProfileAgentId(ctx.conversationId, ctx.config);
 	const source = ctx.source === "webui" || ctx.channelId === "webchat" ? {
 		kind: "webui",
-		sessionKey: ctx.sessionKey
+		conversationId: ctx.conversationId
 	} : {
 		kind: "chat",
-		sessionKey: ctx.sessionKey
+		conversationId: ctx.conversationId
 	};
 	const result = await ctx.workflowRunApis.startWorkflowRun({
 		agentId,
 		definitionId: parsed.name,
 		goal: parsed.goal,
 		input: parsed.input,
-		parentSessionKey: ctx.sessionKey,
+		parentConversationId: ctx.conversationId,
 		source
 	});
 	if (result.ok === false) return {
@@ -170,16 +170,16 @@ async function runWorkflowFromCommand(ctx, args) {
 			label: "runId",
 			detail: code(result.runId)
 		}, {
-			label: "sessionKey",
-			detail: code(result.sessionKey)
+			label: "conversationId",
+			detail: code(result.conversationId)
 		}])),
 		success: true,
 		metadata: { workflowRun: {
 			ok: true,
 			definitionId: parsed.name,
 			runId: result.runId,
-			sessionKey: result.sessionKey,
-			parentSessionKey: ctx.sessionKey
+			conversationId: result.conversationId,
+			parentConversationId: ctx.conversationId
 		} }
 	};
 }

package/dist/src/chat-commands/context.d.ts

@@ -13,7 +13,7 @@ import type { ThinkLevel, ReasoningLevel, VerboseLevel } from '../agent/transcri
 import type { CompactionResult } from '../agent/memory/compaction.js';
 import type { WorkflowRunServiceLike } from '../workflows/service/workflow-run-service.types.js';
 export interface CommandContextDeps {
-    sessionKey: string;
+    conversationId: string;
     source: MessageSource;
     channelId: string;
     chatId: string;
@@ -26,15 +26,15 @@ export interface CommandContextDeps {
     sessionStore: SessionStore;
     sessionConfigStore?: SessionConfigStore;
     /** After persisting session thinking, sync pi-agent in-memory state */
-    applySessionThinkingLevel?: (sessionKey: string, level: ThinkLevel) => void;
+    applySessionThinkingLevel?: (conversationId: string, level: ThinkLevel) => void;
     replyHandler: (text: string, options?: ReplyOptions) => Promise<void>;
     componentHandler?: (component: UIComponent) => Promise<void>;
     typingHandler?: (typing: boolean) => Promise<void>;
     supportedFeatures: PlatformFeature[];
     /** Called after session files are removed so in-memory agents match disk */
-    invalidateAgentSession?: (sessionKey: string) => void;
+    invalidateAgentSession?: (conversationId: string) => void;
     /** Reset session in place (archive + new session id); optional — falls back to clearSession */
-    resetSession?: (sessionKey: string) => Promise<void>;
+    resetSession?: (conversationId: string) => Promise<void>;
     getCurrentModel?: () => string;
     switchModel?: (modelId: string) => Promise<boolean>;
     listModels?: () => Promise<ModelInfo[]>;
@@ -45,20 +45,20 @@ export interface CommandContextDeps {
     reloadSkills?: () => Promise<void>;
     /** Install a managed skill from an explicit source and refresh active agent prompts. */
     installSkillFromSource?: CommandContext['installSkillFromSource'];
-    compactSession?: (sessionKey: string, options?: {
+    compactSession?: (conversationId: string, options?: {
         instructions?: string;
         force?: boolean;
     }) => Promise<CompactionResult>;
-    btwQuery?: (sessionKey: string, question: string, options?: BtwQueryOptions) => Promise<{
+    btwQuery?: (conversationId: string, question: string, options?: BtwQueryOptions) => Promise<{
         text: string;
         error?: string;
     }>;
     emitEvent?: (event: CommandStreamEvent) => void | Promise<void>;
-    getSessionContextReport?: (sessionKey: string, mode: 'list' | 'detail' | 'json') => Promise<string>;
+    getSessionContextReport?: (conversationId: string, mode: 'list' | 'detail' | 'json') => Promise<string>;
     workflowRunService?: WorkflowRunServiceLike;
 }
 export declare class CommandContextImpl implements CommandContext {
-    readonly sessionKey: string;
+    readonly conversationId: string;
     readonly source: MessageSource;
     readonly channelId: string;
     readonly chatId: string;
@@ -82,7 +82,7 @@ export declare class CommandContextImpl implements CommandContext {
     clearSession(): Promise<void>;
     archiveSession(): Promise<void>;
     listSessions(): Promise<SessionInfo[]>;
-    switchSession(sessionKey: string): Promise<void>;
+    switchSession(conversationId: string): Promise<void>;
     getCurrentModel(): string;
     listModels(): Promise<ModelInfo[]>;
     switchModel(modelId: string): Promise<boolean>;

package/dist/src/chat-commands/context.js

@@ -14,7 +14,7 @@ init_logger();
 init_loader();
 const log = createLogger("CommandContext");
 var CommandContextImpl = class {
-	sessionKey;
+	conversationId;
 	source;
 	channelId;
 	chatId;
@@ -29,7 +29,7 @@ var CommandContextImpl = class {
 	workflowRunApis;
 	deps;
 	constructor(deps) {
-		this.sessionKey = deps.sessionKey;
+		this.conversationId = deps.conversationId;
 		this.source = deps.source;
 		this.channelId = deps.channelId;
 		this.chatId = deps.chatId;
@@ -75,13 +75,13 @@ var CommandContextImpl = class {
 		if (this.deps.typingHandler) await this.deps.typingHandler(typing);
 	}
 	async getSession() {
-		return this.deps.sessionStore.load(this.sessionKey);
+		return this.deps.sessionStore.load(this.conversationId);
 	}
 	async resetSession() {
-		if (this.deps.resetSession) await this.deps.resetSession(this.sessionKey);
+		if (this.deps.resetSession) await this.deps.resetSession(this.conversationId);
 		else if (typeof this.deps.sessionStore.reset === "function") {
-			if (!await this.deps.sessionStore.reset(this.sessionKey)) throw new Error("Session not found");
-			this.deps.invalidateAgentSession?.(this.sessionKey);
+			if (!await this.deps.sessionStore.reset(this.conversationId)) throw new Error("Session not found");
+			this.deps.invalidateAgentSession?.(this.conversationId);
 		} else {
 			await this.clearSession();
 			return;
@@ -93,19 +93,19 @@ var CommandContextImpl = class {
 			type: "message",
 			metadata: this.outboundMetadata()
 		});
-		log.info({ sessionKey: this.sessionKey }, "Session reset");
+		log.info({ conversationId: this.conversationId }, "Session reset");
 	}
 	async clearSession() {
 		const messages = await this.getSession();
 		if (messages.length > 0) {
-			await this.deps.sessionStore.archive(this.sessionKey);
+			await this.deps.sessionStore.archive(this.conversationId);
 			log.info({
-				sessionKey: this.sessionKey,
+				conversationId: this.conversationId,
 				messageCount: messages.length
 			}, "Session archived");
 		}
-		await this.deps.sessionStore.deleteSession(this.sessionKey);
-		this.deps.invalidateAgentSession?.(this.sessionKey);
+		await this.deps.sessionStore.deleteSession(this.conversationId);
+		this.deps.invalidateAgentSession?.(this.conversationId);
 		await this.deps.bus.publishOutbound({
 			channel: this.source,
 			chat_id: this.chatId,
@@ -113,27 +113,27 @@ var CommandContextImpl = class {
 			type: "message",
 			metadata: this.outboundMetadata()
 		});
-		log.info({ sessionKey: this.sessionKey }, "Session cleared");
+		log.info({ conversationId: this.conversationId }, "Session cleared");
 	}
 	async archiveSession() {
-		await this.deps.sessionStore.archive(this.sessionKey);
-		log.info({ sessionKey: this.sessionKey }, "Session archived");
+		await this.deps.sessionStore.archive(this.conversationId);
+		log.info({ conversationId: this.conversationId }, "Session archived");
 	}
 	async listSessions() {
 		const messages = await this.getSession();
 		return [{
-			key: this.sessionKey,
-			name: getSessionDisplayName(this.sessionKey),
+			key: this.conversationId,
+			name: getSessionDisplayName(this.conversationId),
 			messageCount: messages.length,
 			createdAt: /* @__PURE__ */ new Date(),
 			updatedAt: /* @__PURE__ */ new Date(),
 			isActive: true
 		}];
 	}
-	async switchSession(sessionKey) {
+	async switchSession(conversationId) {
 		log.info({
-			from: this.sessionKey,
-			to: sessionKey
+			from: this.conversationId,
+			to: conversationId
 		}, "Session switch requested");
 	}
 	getCurrentModel() {
@@ -208,7 +208,7 @@ var CommandContextImpl = class {
 	async getThinkingLevel() {
 		const configStore = this.deps.sessionConfigStore;
 		if (configStore) {
-			const sessionConfig = await configStore.get(this.sessionKey);
+			const sessionConfig = await configStore.get(this.conversationId);
 			if (sessionConfig?.thinkingLevel) return sessionConfig.thinkingLevel;
 		}
 	}
@@ -217,15 +217,15 @@ var CommandContextImpl = class {
 	*/
 	async setThinkingLevel(level) {
 		const configStore = this.deps.sessionConfigStore;
-		if (configStore) await configStore.update(this.sessionKey, { thinkingLevel: level });
-		this.deps.applySessionThinkingLevel?.(this.sessionKey, level);
+		if (configStore) await configStore.update(this.conversationId, { thinkingLevel: level });
+		this.deps.applySessionThinkingLevel?.(this.conversationId, level);
 	}
 	syncAgentThinkingLevel(level) {
-		this.deps.applySessionThinkingLevel?.(this.sessionKey, level);
+		this.deps.applySessionThinkingLevel?.(this.conversationId, level);
 	}
 	async compactSession(options) {
 		if (!this.deps.compactSession) return null;
-		const r = await this.deps.compactSession(this.sessionKey, options);
+		const r = await this.deps.compactSession(this.conversationId, options);
 		return {
 			compacted: r.compacted,
 			tokensBefore: r.tokensBefore,
@@ -238,19 +238,19 @@ var CommandContextImpl = class {
 			text: "",
 			error: "Side questions are not available in this environment."
 		};
-		return this.deps.btwQuery(this.sessionKey, question, options);
+		return this.deps.btwQuery(this.conversationId, question, options);
 	}
 	emitEvent(event) {
 		return this.deps.emitEvent?.(event);
 	}
 	async exportSessionToWorkspace(format) {
 		const exportFmt = format === "json" ? "json" : "markdown";
-		let body = await this.deps.sessionStore.exportSession(this.sessionKey, exportFmt);
-		if (format === "html") body = wrapMarkdownExportAsHtml(`Session ${this.sessionKey}`, body);
-		const sc = this.deps.sessionConfigStore ? await this.deps.sessionConfigStore.get(this.sessionKey) : null;
-		const dir = join(effectiveWorkspacePathForSession(this.config, this.sessionKey, sc, getProjectForSession(this.sessionKey)), "exports");
+		let body = await this.deps.sessionStore.exportSession(this.conversationId, exportFmt);
+		if (format === "html") body = wrapMarkdownExportAsHtml(`Session ${this.conversationId}`, body);
+		const sc = this.deps.sessionConfigStore ? await this.deps.sessionConfigStore.get(this.conversationId) : null;
+		const dir = join(effectiveWorkspacePathForSession(this.config, this.conversationId, sc, getProjectForSession(this.conversationId)), "exports");
 		await mkdir(dir, { recursive: true });
-		const safe = this.sessionKey.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 96);
+		const safe = this.conversationId.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 96);
 		const ext = format === "json" ? "json" : format === "html" ? "html" : "md";
 		const outPath = join(dir, `session-${safe}-${Date.now()}.${ext}`);
 		await writeFile(outPath, body, "utf-8");
@@ -258,7 +258,7 @@ var CommandContextImpl = class {
 	}
 	async agentContextReport(mode = "list") {
 		if (!this.deps.getSessionContextReport) return "Context report is not available in this environment.";
-		return this.deps.getSessionContextReport(this.sessionKey, mode);
+		return this.deps.getSessionContextReport(this.conversationId, mode);
 	}
 	/**
 	* Get current reasoning level (session override or default)
@@ -266,7 +266,7 @@ var CommandContextImpl = class {
 	async getReasoningLevel() {
 		const configStore = this.deps.sessionConfigStore;
 		if (configStore) {
-			const sessionConfig = await configStore.get(this.sessionKey);
+			const sessionConfig = await configStore.get(this.conversationId);
 			if (sessionConfig?.reasoningLevel) return sessionConfig.reasoningLevel;
 		}
 	}
@@ -275,7 +275,7 @@ var CommandContextImpl = class {
 	*/
 	async setReasoningLevel(level) {
 		const configStore = this.deps.sessionConfigStore;
-		if (configStore) await configStore.update(this.sessionKey, { reasoningLevel: level });
+		if (configStore) await configStore.update(this.conversationId, { reasoningLevel: level });
 	}
 	/**
 	* Get current verbose level (session override or default)
@@ -283,7 +283,7 @@ var CommandContextImpl = class {
 	async getVerboseLevel() {
 		const configStore = this.deps.sessionConfigStore;
 		if (configStore) {
-			const sessionConfig = await configStore.get(this.sessionKey);
+			const sessionConfig = await configStore.get(this.conversationId);
 			if (sessionConfig?.verboseLevel) return sessionConfig.verboseLevel;
 		}
 	}
@@ -292,7 +292,7 @@ var CommandContextImpl = class {
 	*/
 	async setVerboseLevel(level) {
 		const configStore = this.deps.sessionConfigStore;
-		if (configStore) await configStore.update(this.sessionKey, { verboseLevel: level });
+		if (configStore) await configStore.update(this.conversationId, { verboseLevel: level });
 	}
 	renderComponentAsText(component) {
 		switch (component.type) {

package/dist/src/chat-commands/index.d.ts

@@ -5,7 +5,7 @@
  * Telegram, Feishu, Web UI, CLI, and other channel surfaces.
  */
 export type { MessageSource, UnifiedMessage, PlatformMetadata, MessageAttachment, CommandDefinition, CommandCategory, CommandScope, CommandHandler, CommandResult, CommandStreamEvent, BtwQueryOptions, CommandContext, ReplyOptions, UIComponent, ButtonGroup, SelectMenu, ModelPicker, UsageDisplay, SessionList, TextInput, ProviderInfo, ModelInfo, UsageStats, SessionInfo, PlatformFeature, ChannelAdapter, ReplyPayload, } from './types.js';
-export { generateSessionKey, getSessionDisplayName, type SessionKeyContext } from './session-key.js';
+export { generateConversationId, getSessionDisplayName, type ConversationIdContext } from './session-key.js';
 export { normalizeTelegramCommandName, parseSlashCommand } from './command-parse.js';
 export { CommandRegistry, commandRegistry } from './registry.js';
 export type { CommandRegistry as CommandRegistryType } from './types.js';

package/dist/src/chat-commands/index.js

@@ -1,6 +1,6 @@
 import { normalizeTelegramCommandName, parseSlashCommand } from "./command-parse.js";
 import { CommandRegistry, commandRegistry } from "./registry.js";
-import { generateSessionKey, getSessionDisplayName } from "./session-key.js";
+import { generateConversationId, getSessionDisplayName } from "./session-key.js";
 import { registerSessionCommands } from "./builtins/session.js";
 import { registerModelCommands } from "./builtins/model.js";
 import { registerSystemCommands } from "./builtins/system.js";
@@ -39,4 +39,4 @@ function initializeCommands() {
 	registerAgentEditCommand();
 }
 //#endregion
-export { CommandContextImpl, CommandRegistry, commandRegistry, createCommandContext, generateSessionKey, getSessionDisplayName, initializeCommands, normalizeTelegramCommandName, parseSlashCommand, registerAgentEditCommand, registerConfigCommand, registerContextCommands, registerModelCommands, registerReviewCommand, registerSessionCommands, registerSkillCommand, registerSystemCommands, registerTTSCommands, registerThinkingCommands, registerUnderstandingCommands, registerWorkflowCommands };
+export { CommandContextImpl, CommandRegistry, commandRegistry, createCommandContext, generateConversationId, getSessionDisplayName, initializeCommands, normalizeTelegramCommandName, parseSlashCommand, registerAgentEditCommand, registerConfigCommand, registerContextCommands, registerModelCommands, registerReviewCommand, registerSessionCommands, registerSkillCommand, registerSystemCommands, registerTTSCommands, registerThinkingCommands, registerUnderstandingCommands, registerWorkflowCommands };

package/dist/src/chat-commands/processor.js

@@ -28,7 +28,7 @@ async function executeCommand(message, deps) {
 	if (!commandName) return false;
 	log.info({
 		command: commandName,
-		sessionKey: message.sessionKey
+		conversationId: message.conversationId
 	}, "Executing command");
 	const ctx = await createCommandContextFromMessage(message, deps);
 	const result = await commandRegistry.execute(commandName, ctx, commandArgs || "");
@@ -46,7 +46,7 @@ async function executeCommand(message, deps) {
 */
 async function createCommandContextFromMessage(message, deps) {
 	return createCommandContext({
-		sessionKey: message.sessionKey,
+		conversationId: message.conversationId,
 		source: message.source,
 		channelId: message.channelId,
 		chatId: message.chatId,

package/dist/src/chat-commands/registry.js

@@ -104,7 +104,7 @@ var CommandRegistry = class CommandRegistry {
 		};
 		log.info({
 			command: name,
-			sessionKey: context.sessionKey
+			conversationId: context.conversationId
 		}, "Executing command");
 		try {
 			const result = await command.handler(context, args);

package/dist/src/chat-commands/session-key.d.ts

@@ -4,7 +4,7 @@
  * Session routing is resolved from SessionMetadata, not by parsing session keys.
  */
 import type { MessageSource } from './types.js';
-export interface SessionKeyContext {
+export interface ConversationIdContext {
     source: MessageSource;
     channelId?: string;
     chatId: string;
@@ -17,5 +17,5 @@ export interface SessionKeyContext {
     dmScope?: 'main' | 'per-peer' | 'per-channel-peer' | 'per-account-channel-peer';
     identityLinks?: Record<string, string[]>;
 }
-export declare function generateSessionKey(ctx: SessionKeyContext): string;
-export declare function getSessionDisplayName(sessionKey: string): string;
+export declare function generateConversationId(ctx: ConversationIdContext): string;
+export declare function getSessionDisplayName(conversationId: string): string;

package/dist/src/chat-commands/session-key.js

@@ -1,17 +1,17 @@
-import { buildAgentMainSessionKey, buildAgentPeerSessionKey } from "../routing/agent-session-key.js";
+import { resolveAgentMainConversationId, resolveAgentPeerConversationId } from "../routing/agent-session-key.js";
 import { init_session_key } from "../routing/session-key.js";
 //#region src/chat-commands/session-key.ts
 init_session_key();
-function generateSessionKey(ctx) {
+function generateConversationId(ctx) {
 	const effectiveAgentId = ctx.agentId ?? "main";
 	const effectiveAccountId = ctx.accountId ?? "default";
 	const channel = ctx.source === "webui" ? "webchat" : ctx.source;
 	if (ctx.source === "cli") {
-		if (ctx.chatId === "direct" || ctx.chatId === "main") return buildAgentMainSessionKey({
+		if (ctx.chatId === "direct" || ctx.chatId === "main") return resolveAgentMainConversationId({
 			agentId: effectiveAgentId,
 			mainKey: ctx.mainKey
 		});
-		return buildAgentPeerSessionKey({
+		return resolveAgentPeerConversationId({
 			agentId: effectiveAgentId,
 			mainKey: ctx.mainKey,
 			channel: "cli",
@@ -21,34 +21,30 @@ function generateSessionKey(ctx) {
 			dmScope: "per-peer"
 		});
 	}
-	if (!ctx.isGroup) {
-		const key = buildAgentPeerSessionKey({
-			agentId: effectiveAgentId,
-			mainKey: ctx.mainKey,
-			channel,
-			accountId: effectiveAccountId,
-			peerKind: "direct",
-			peerId: ctx.senderId,
-			identityLinks: ctx.identityLinks,
-			dmScope: ctx.dmScope ?? "per-account-channel-peer"
-		});
-		if (ctx.threadId) return `${key}:thread:${ctx.threadId.toLowerCase()}`;
-		return key;
-	}
-	let key = buildAgentPeerSessionKey({
+	if (!ctx.isGroup) return resolveAgentPeerConversationId({
+		agentId: effectiveAgentId,
+		mainKey: ctx.mainKey,
+		channel,
+		accountId: effectiveAccountId,
+		peerKind: "direct",
+		peerId: ctx.senderId,
+		identityLinks: ctx.identityLinks,
+		threadId: ctx.threadId,
+		dmScope: ctx.dmScope ?? "per-account-channel-peer"
+	});
+	return resolveAgentPeerConversationId({
 		agentId: effectiveAgentId,
 		mainKey: ctx.mainKey,
 		channel,
 		accountId: effectiveAccountId,
 		peerKind: "group",
+		threadId: ctx.threadId,
 		peerId: ctx.chatId,
 		identityLinks: ctx.identityLinks
 	});
-	if (ctx.threadId) key = `${key}:thread:${ctx.threadId.toLowerCase()}`;
-	return key;
 }
-function getSessionDisplayName(sessionKey) {
-	return sessionKey.trim() || "Session";
+function getSessionDisplayName(conversationId) {
+	return conversationId.trim() || "Session";
 }
 //#endregion
-export { generateSessionKey, getSessionDisplayName };
+export { generateConversationId, getSessionDisplayName };

package/dist/src/chat-commands/types.d.ts

@@ -31,7 +31,7 @@ export interface UnifiedMessage {
     /** Command arguments */
     commandArgs?: string;
     /** Unified session key */
-    sessionKey: string;
+    conversationId: string;
     /** Platform-specific metadata */
     platformData: PlatformMetadata;
     /** Optional attachments */
@@ -121,7 +121,7 @@ export type BtwQueryOptions = {
 };
 export interface CommandContext {
     /** Unified session key */
-    sessionKey: string;
+    conversationId: string;
     /** Message source platform */
     source: MessageSource;
     /** Channel ID */
@@ -156,7 +156,7 @@ export interface CommandContext {
     /** List user's sessions */
     listSessions(): Promise<SessionInfo[]>;
     /** Switch to a different session */
-    switchSession(sessionKey: string): Promise<void>;
+    switchSession(conversationId: string): Promise<void>;
     /** Get current model ID */
     getCurrentModel(): string;
     /** List available models */

package/dist/src/cli/command-manifest.js

@@ -56,7 +56,7 @@ const ROOT_HELP_COMMANDS = [
 		description: "Interactive terminal UI (pi-tui)"
 	},
 	{
-		name: "resume [options] [sessionKey]",
+		name: "resume [options] [conversationId]",
 		description: "Resume a previous TUI session"
 	},
 	{

package/dist/src/cli/commands/agent/interactive.d.ts

@@ -4,7 +4,7 @@
 import type { AgentService } from '../../../agent/index.js';
 export interface InteractiveOptions {
     workspace: string;
-    sessionKey: string;
+    conversationId: string;
     continuingSession: boolean;
 }
 /**

package/dist/src/cli/commands/agent/interactive.js

@@ -6,8 +6,8 @@ import { renderStreamToTerminal } from "./stream-renderer.js";
 * Start interactive chat mode
 */
 async function startInteractiveChat(agent, options) {
-	const { sessionKey: initialSessionKey, continuingSession } = options;
-	let sessionKey = initialSessionKey;
+	const { conversationId: initialConversationId, continuingSession } = options;
+	let conversationId = initialConversationId;
 	if (continuingSession) console.log("🧠 Interactive chat mode - Continuing session\n");
 	else console.log("🧠 Interactive chat mode (Ctrl+C to exit)\n");
 	const rl = (await import("readline")).createInterface({
@@ -25,11 +25,11 @@ async function startInteractiveChat(agent, options) {
 			return;
 		}
 		if (trimmed.startsWith(":session ")) {
-			const newSessionKey = trimmed.slice(9).trim();
-			if (await (await getSessionIndex()).getSessionMetadata(newSessionKey)) {
-				sessionKey = newSessionKey;
-				console.log(`🔄 Switched to session: ${sessionKey}\n`);
-			} else console.log(`❌ Session not found: ${newSessionKey}\n`);
+			const newConversationId = trimmed.slice(9).trim();
+			if (await (await getSessionIndex()).getSessionMetadata(newConversationId)) {
+				conversationId = newConversationId;
+				console.log(`🔄 Switched to session: ${conversationId}\n`);
+			} else console.log(`❌ Session not found: ${newConversationId}\n`);
 			rl.prompt();
 			return;
 		}
@@ -43,7 +43,7 @@ async function startInteractiveChat(agent, options) {
 			return;
 		}
 		rl.pause();
-		await renderStreamToTerminal(agent, input, sessionKey);
+		await renderStreamToTerminal(agent, input, conversationId);
 		rl.resume();
 		rl.prompt();
 	});

package/dist/src/cli/commands/agent/stream-renderer.d.ts

@@ -11,4 +11,4 @@ import type { AgentService } from '../../../agent/index.js';
  *
  * Returns the final aggregated response text.
  */
-export declare function renderStreamToTerminal(agent: AgentService, message: string, sessionKey: string): Promise<string>;
+export declare function renderStreamToTerminal(agent: AgentService, message: string, conversationId: string): Promise<string>;

package/dist/src/cli/commands/agent/stream-renderer.js

@@ -26,9 +26,9 @@ function formatToolArgs(args) {
 *
 * Returns the final aggregated response text.
 */
-async function renderStreamToTerminal(agent, message, sessionKey) {
+async function renderStreamToTerminal(agent, message, conversationId) {
 	const stamped = message.trimStart().startsWith("/") ? message : prependEnvelopeTimestamp(message);
-	const stream = agent.turnDispatcher.processDirectStreaming(stamped, sessionKey, {
+	const stream = agent.turnDispatcher.processDirectStreaming(stamped, conversationId, {
 		type: "system",
 		source: "cli"
 	});