@xopcai/xopc 0.0.285 → 0.0.291

package/dist/src/tui/tui.js

@@ -1,11 +1,10 @@
 import { version } from "../../package.js";
 import { resolveStateDir, resolveXopcDatabasePath } from "../config/paths-state.js";
-import { parseAgentSessionKey } from "../routing/session-key-utils.js";
-import { init_agent_session_key, normalizeAgentId } from "../routing/agent-session-key.js";
-import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { init_paths } from "../config/paths.js";
 import { loadConfig } from "../config/loader.js";
+import { init_agent_session_key, normalizeAgentId } from "../routing/agent-session-key.js";
 import { getAllModels, getAllProviders, getApiKey, init_providers, isProviderConfiguredSync } from "../providers/index.js";
+import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { ProjectTrustStore, hasTrustRequiringProjectResources } from "../project-trust/trust-store.js";
 import { MAX_WEBCHAT_ATTACHMENT_FILE_BYTES } from "../gateway/chat-limits.js";
 import { renderWorkflowFinalSummary, renderWorkflowPanel } from "../agent/workflow/snapshot.js";
@@ -14,7 +13,7 @@ import "../config/index.js";
 import { isTerminalWorkflowRunStatus } from "../workflows/domain/run.js";
 import "../workflows/domain/index.js";
 import { runViewToSnapshot } from "../workflows/service/run-view-to-snapshot.js";
-import { resolveTuiSessionKey, resolveTuiStartupSessionKey } from "../routing/resolve-tui-session-key.js";
+import { resolveTuiConversationId, resolveTuiStartupConversationId } from "../routing/resolve-tui-session-key.js";
 import { applyThemeById, getBashExcludeBorderColor, getBashModeBorderColor, getCustomThemesDir, getThemeExports, getThinkingBorderColor, initTuiTheme, listAvailableThemeIds, resolveThemePalette } from "./theme-manager.js";
 import { editorTheme, theme } from "./theme.js";
 import { extensionForImageMimeType, readClipboardImage } from "./clipboard-image.js";
@@ -27,7 +26,7 @@ import { transcriptTreeEntryIdToRowNumber } from "./tui-transcript-tree.js";
 import { formatTuiCompactionResult, formatTuiShareResult } from "./tui-command-formatters.js";
 import { formatTuiStartupText } from "./tui-startup-text.js";
 import { createTuiCommandHandler, getSlashCommands } from "./tui-commands.js";
-import { GENERATED_TUI_SESSION_SHELL_PATCH, cleanupAbandonedTuiSessions, deleteGeneratedTuiSessionIfEmpty, isGeneratedTuiSessionKey } from "./tui-empty-session-cleanup.js";
+import { GENERATED_TUI_SESSION_SHELL_PATCH, cleanupAbandonedTuiSessions, deleteGeneratedTuiSessionIfEmpty } from "./tui-empty-session-cleanup.js";
 import { extensionCustomMessageContentToText, extensionCustomMessageToTurnText, extensionUserMessageContentToText } from "./tui-extension-user-message.js";
 import { resolveFdPath } from "./tui-fd-path.js";
 import { createBackspaceDeduper, drainAndStopTuiSafely, isIgnorableTuiStopError, resolveCtrlCAction, stopTuiSafely } from "./tui-lifecycle.js";
@@ -107,8 +106,8 @@ function wrapMarkdownExportAsHtml(markdown) {
 		""
 	].join("\n");
 }
-function defaultExportPath(sessionKey, format) {
-	const safeKey = sessionKey.replace(/[^a-z0-9_.-]+/gi, "_").replace(/^_+|_+$/g, "") || "session";
+function defaultExportPath(conversationId, format) {
+	const safeKey = conversationId.replace(/[^a-z0-9_.-]+/gi, "_").replace(/^_+|_+$/g, "") || "session";
 	const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 	return resolve(process.cwd(), `xopc-session-${safeKey}-${stamp}.${exportExtension(format)}`);
 }
@@ -138,11 +137,11 @@ function shellQuote(value) {
 	if (/^[A-Za-z0-9_/:@%+=,.-]+$/.test(value)) return value;
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-function formatTuiResumeCommand(opts, sessionKey) {
+function formatTuiResumeCommand(opts, conversationId) {
 	const parts = ["xopc", "tui"];
 	if (opts.local === true) parts.push("--local");
 	if (opts.url) parts.push("--url", shellQuote(opts.url));
-	parts.push("--session", shellQuote(sessionKey));
+	parts.push("--session", shellQuote(conversationId));
 	return parts.join(" ");
 }
 function isLoopbackGatewayUrl(rawUrl) {
@@ -180,27 +179,21 @@ async function runTui(opts) {
 	const isLocalMode = opts.local === true;
 	const loadedConfig = loadConfig();
 	const config = isLocalMode ? ensureStarterAgentsInitialized(loadedConfig).config : loadedConfig;
-	const startup = resolveTuiStartupSessionKey({
+	const startup = resolveTuiStartupConversationId({
 		cfg: config,
 		sessionOption: opts.session,
 		agentOption: opts.agentId,
 		cwd: process.cwd()
 	});
 	let currentAgentId = startup.agentId;
-	const sessionScope = startup.sessionScope;
-	const sessionMainKey = startup.sessionMainKey;
-	const resolveSessionKey = (raw) => resolveTuiSessionKey({
-		raw,
-		sessionScope,
-		currentAgentId,
-		sessionMainKey
-	});
+	const resolveConversationId = (raw) => resolveTuiConversationId({ raw });
 	let tuiSettings = loadTuiSettings();
 	const newSessionPreferenceKey = isLocalMode ? tuiGatewayPreferenceKey() : tuiGatewayPreferenceKey(opts.url ?? "http://localhost:3120");
 	initTuiTheme({ themeId: opts.theme ?? tuiSettings.theme });
-	const state = createInitialState(startup.sessionKey);
-	const generatedStartupSessionKey = !opts.session?.trim() && isGeneratedTuiSessionKey(startup.sessionKey) ? startup.sessionKey : null;
-	const generatedStartupSessionKeys = new Set(generatedStartupSessionKey ? [generatedStartupSessionKey] : []);
+	const state = createInitialState(startup.conversationId);
+	const generatedStartupConversationId = !opts.session?.trim() ? startup.conversationId : null;
+	const generatedStartupConversationIds = new Set(generatedStartupConversationId ? [generatedStartupConversationId] : []);
+	const isGeneratedTuiConversationId = (id) => generatedStartupConversationIds.has(id);
 	let startupSessionHadUserTurn = false;
 	const startupWorkingDirectory = resolveStartupWorkingDirectory(opts, isLocalMode);
 	const implicitTrustedWorkspace = startupWorkingDirectory ?? (isLocalMode ? process.cwd() : void 0);
@@ -215,7 +208,7 @@ async function runTui(opts) {
 	};
 	const sessionStateDir = resolveStateDir();
 	const sessionDatabasePath = resolveXopcDatabasePath();
-	const sessionSnapshot = new TuiSessionSnapshot(() => state.currentSessionKey, () => process.cwd(), () => state.sessionInfo.displayName, () => `${sessionDatabasePath}#session=${encodeURIComponent(state.currentSessionKey)}`, () => sessionStateDir);
+	const sessionSnapshot = new TuiSessionSnapshot(() => state.currentConversationId, () => process.cwd(), () => state.sessionInfo.displayName, () => `${sessionDatabasePath}#session=${encodeURIComponent(state.currentConversationId)}`, () => sessionStateDir);
 	state.scopedModelRefs = loadScopedModelRefs();
 	state.showThinking = tuiSettings.showThinking;
 	state.toolsExpanded = tuiSettings.toolsExpanded;
@@ -265,7 +258,7 @@ async function runTui(opts) {
 	const header = new TuiHeader(() => ({
 		version: version ?? "dev",
 		connectionLabel: client.connectionLabel,
-		sessionKey: state.currentSessionKey,
+		conversationId: state.currentConversationId,
 		showHints: tuiSettings.showStartupHints
 	}), keybindings);
 	const statusContainer = new Container();
@@ -283,7 +276,7 @@ async function runTui(opts) {
 	});
 	setExtensionLabel = (entryId, label) => {
 		sessionSnapshot.setLabel(entryId, label);
-		client.setTranscriptLabel(state.currentSessionKey, entryId, label).catch((err) => {
+		client.setTranscriptLabel(state.currentConversationId, entryId, label).catch((err) => {
 			const errorMessage = err instanceof Error ? err.message : String(err);
 			chatLog.addSystem(`Label update failed: ${errorMessage}`);
 		}).finally(() => {
@@ -295,7 +288,7 @@ async function runTui(opts) {
 		const normalized = customType.trim();
 		if (!normalized) throw new Error("appendEntry requires customType.");
 		sessionSnapshot.appendCustomEntry(normalized, data);
-		client.appendCustomEntry(state.currentSessionKey, normalized, data).catch((err) => {
+		client.appendCustomEntry(state.currentConversationId, normalized, data).catch((err) => {
 			const errorMessage = err instanceof Error ? err.message : String(err);
 			chatLog.addSystem(`Custom entry append failed: ${errorMessage}`);
 		}).finally(() => {
@@ -324,7 +317,7 @@ async function runTui(opts) {
 			});
 			tui.requestRender();
 		}
-		const persist = client.appendCustomMessage(state.currentSessionKey, nextMessage).catch((err) => {
+		const persist = client.appendCustomMessage(state.currentConversationId, nextMessage).catch((err) => {
 			const errorMessage = err instanceof Error ? err.message : String(err);
 			chatLog.addSystem(`Custom message append failed: ${errorMessage}`);
 			throw err;
@@ -346,7 +339,7 @@ async function runTui(opts) {
 			if (state.activeRunId) {
 				if (options?.deliverAs === "next") {
 					client.submitChatInput({
-						sessionKey: state.currentSessionKey,
+						conversationId: state.currentConversationId,
 						message: controlText,
 						delivery: "next"
 					}).then((result) => {
@@ -561,7 +554,7 @@ async function runTui(opts) {
 		}
 	};
 	const getAvailableProviderCount = () => getAllProviders().filter((provider) => isProviderConfiguredSync(provider)).length;
-	const getExtensionSystemPrompt = () => resolveEffectiveAgentProfileForSession(config, state.currentSessionKey).customInstructions ?? "";
+	const getExtensionSystemPrompt = () => resolveEffectiveAgentProfileForSession(config, state.currentConversationId).customInstructions ?? "";
 	const waitForTuiIdle = async () => {
 		while (state.activeRunId != null || state.isCompacting || state.activityStatus === "sending" || state.activityStatus === "waiting" || state.activityStatus === "streaming" || state.activityStatus === "running" || state.activityStatus === "compacting") await new Promise((resolveDelay) => setTimeout(resolveDelay, 50));
 	};
@@ -660,7 +653,7 @@ async function runTui(opts) {
 			},
 			model,
 			cwd: process.cwd(),
-			sessionKey: state.currentSessionKey,
+			conversationId: state.currentConversationId,
 			isProjectTrusted: isCurrentProjectTrusted,
 			isIdle: () => !state.activeRunId && !state.isCompacting,
 			hasPendingMessages: () => state.compactionQueue.length > 0,
@@ -673,7 +666,7 @@ async function runTui(opts) {
 			getSystemPrompt: getExtensionSystemPrompt,
 			getSystemPromptOptions: () => ({
 				cwd: process.cwd(),
-				sessionKey: state.currentSessionKey,
+				conversationId: state.currentConversationId,
 				...model ? { model } : {}
 			}),
 			waitForIdle: waitForTuiIdle,
@@ -725,7 +718,7 @@ async function runTui(opts) {
 	};
 	const runExtensionNewSession = async (options) => {
 		await abortActive({ clearUi: false });
-		await startPreferredNewSession("session");
+		await startPreferredNewSession();
 		await options?.setup?.(sessionSnapshot.manager());
 		await runWithReplacementContext(options?.withSession);
 		return { cancelled: false };
@@ -735,14 +728,14 @@ async function runTui(opts) {
 		if (rowNumber == null) throw new Error(`Invalid entry ID for forking: ${entryId}`);
 		const throughRow = options?.position === "before" ? rowNumber - 1 : rowNumber;
 		if (throughRow <= 0) throw new Error(`Invalid entry ID for forking: ${entryId}`);
-		const sourceSessionKey = state.currentSessionKey;
-		const targetKey = resolveSessionKey(`fork-${randomUUID()}`);
+		const sourceConversationId = state.currentConversationId;
+		const targetKey = randomUUID();
 		await abortActive({ clearUi: false });
-		const result = await client.forkSessionAt(sourceSessionKey, targetKey, `row-${throughRow}`);
-		await setSession(result.sessionKey);
+		const result = await client.forkSessionAt(sourceConversationId, targetKey, `row-${throughRow}`);
+		await setSession(result.conversationId);
 		chatLog.addBranchSummary({
-			sourceSessionKey,
-			targetSessionKey: result.sessionKey,
+			sourceConversationId,
+			targetConversationId: result.conversationId,
 			rowCount: result.rowCount,
 			entryId
 		});
@@ -776,7 +769,7 @@ async function runTui(opts) {
 		getEditorText: () => editor.getExpandedText?.() ?? editor.getText(),
 		setEditorComponent,
 		getEditorComponent: () => editorComponentFactory,
-		searchWorkspaceFiles: (sessionKey, query, options) => client.searchWorkspaceFiles?.(sessionKey, query, options) ?? Promise.resolve([]),
+		searchWorkspaceFiles: (conversationId, query, options) => client.searchWorkspaceFiles?.(conversationId, query, options) ?? Promise.resolve([]),
 		getThemeObject: () => theme,
 		getAllThemes: getAllExtensionThemes,
 		getTheme: getExtensionTheme,
@@ -800,7 +793,7 @@ async function runTui(opts) {
 		getSystemPrompt: getExtensionSystemPrompt,
 		getSystemPromptOptions: () => ({
 			cwd: process.cwd(),
-			sessionKey: state.currentSessionKey,
+			conversationId: state.currentConversationId,
 			...state.sessionInfo.model ? { model: {
 				...state.sessionInfo.modelProvider ? { provider: state.sessionInfo.modelProvider } : {},
 				id: state.sessionInfo.model,
@@ -936,7 +929,7 @@ async function runTui(opts) {
 		syncTerminalTitle();
 	};
 	const syncTerminalTitle = () => {
-		const shortKey = state.currentSessionKey.length > 48 ? `${state.currentSessionKey.slice(0, 45)}…` : state.currentSessionKey;
+		const shortKey = state.currentConversationId.length > 48 ? `${state.currentConversationId.slice(0, 45)}…` : state.currentConversationId;
 		tui.terminal.setTitle(`xopc · ${shortKey}`);
 	};
 	const updateFooter = () => {
@@ -967,15 +960,15 @@ async function runTui(opts) {
 		tui.terminal.setProgress(false);
 		(async () => {
 			const removedEmptyStartupSessions = /* @__PURE__ */ new Set();
-			if (!state.activeRunId) for (const sessionKey of generatedStartupSessionKeys) {
-				if (sessionKey === state.currentSessionKey && startupSessionHadUserTurn) continue;
-				if (await deleteGeneratedTuiSessionIfEmpty(client, sessionKey).catch(() => false)) removedEmptyStartupSessions.add(sessionKey);
+			if (!state.activeRunId) for (const conversationId of generatedStartupConversationIds) {
+				if (conversationId === state.currentConversationId && startupSessionHadUserTurn) continue;
+				if (await deleteGeneratedTuiSessionIfEmpty(client, conversationId).catch(() => false)) removedEmptyStartupSessions.add(conversationId);
 			}
 			client.stop();
 			await drainAndStopTuiSafely(tui);
 			restoreStdio();
-			const currentSessionWasRemoved = removedEmptyStartupSessions.has(state.currentSessionKey);
-			if (options?.showResumeHint !== false && !currentSessionWasRemoved) process.stdout.write(`\nTo resume this session: ${formatTuiResumeCommand(opts, state.currentSessionKey)}\n`);
+			const currentSessionWasRemoved = removedEmptyStartupSessions.has(state.currentConversationId);
+			if (options?.showResumeHint !== false && !currentSessionWasRemoved) process.stdout.write(`\nTo resume this session: ${formatTuiResumeCommand(opts, state.currentConversationId)}\n`);
 			finishTui?.();
 			process.exit(0);
 		})();
@@ -985,7 +978,7 @@ async function runTui(opts) {
 		chatLog,
 		tui,
 		state,
-		resolveSessionKey,
+		resolveConversationId,
 		updateHeader,
 		updateFooter,
 		setActivityStatus,
@@ -1006,15 +999,17 @@ async function runTui(opts) {
 		});
 		saveTuiSettings(tuiSettings);
 	};
-	const startPreferredNewSession = async (prefix = "tui") => {
+	const startPreferredNewSession = async () => {
 		const projectId = state.sessionInfo.projectId?.trim() || void 0;
-		await setSession(resolveSessionKey(`${prefix}-${randomUUID()}`));
+		const targetKey = await client.createConversation(currentAgentId);
+		generatedStartupConversationIds.add(targetKey);
+		await setSession(targetKey);
 		const initialAgentConfig = tuiInitialAgentConfig(tuiSettings, newSessionPreferenceKey, currentAgentId);
 		if (initialAgentConfig || projectId) {
-			await client.patchSession(state.currentSessionKey, {
+			await client.patchSession(state.currentConversationId, {
 				...initialAgentConfig,
 				...projectId ? { projectId } : {},
-				...isGeneratedTuiSessionKey(state.currentSessionKey) ? GENERATED_TUI_SESSION_SHELL_PATCH : {}
+				...isGeneratedTuiConversationId(state.currentConversationId) ? GENERATED_TUI_SESSION_SHELL_PATCH : {}
 			});
 			await refreshSessionInfo();
 		}
@@ -1031,7 +1026,7 @@ async function runTui(opts) {
 			return;
 		}
 		try {
-			startupResources = await client.getStartupResources(state.currentSessionKey);
+			startupResources = await client.getStartupResources(state.currentConversationId);
 		} catch {
 			startupResources = void 0;
 		}
@@ -1051,9 +1046,9 @@ async function runTui(opts) {
 	const applyStartupWorkingDirectory = async () => {
 		if (startupWorkingDirectoryApplied || !startupWorkingDirectory) return;
 		startupWorkingDirectoryApplied = true;
-		await client.patchSession(state.currentSessionKey, {
+		await client.patchSession(state.currentConversationId, {
 			workingDirectory: startupWorkingDirectory,
-			...isGeneratedTuiSessionKey(state.currentSessionKey) ? GENERATED_TUI_SESSION_SHELL_PATCH : {}
+			...isGeneratedTuiConversationId(state.currentConversationId) ? GENERATED_TUI_SESSION_SHELL_PATCH : {}
 		});
 		state.sessionInfo.effectiveWorkspacePath = startupWorkingDirectory;
 		state.sessionInfo.workingDirectoryLocked = true;
@@ -1063,29 +1058,28 @@ async function runTui(opts) {
 		startupProjectApplied = true;
 		const result = await client.resolveStartupProject?.({
 			workspacePath: startupWorkingDirectory,
-			sessionKey: state.currentSessionKey,
+			conversationId: state.currentConversationId,
 			agentId: currentAgentId,
 			autoCreate: true
 		});
 		if (!result?.project) return;
 		const projectAgentId = result.project.defaultAgentId?.trim() ? normalizeAgentId(result.project.defaultAgentId) : void 0;
-		const currentParsed = parseAgentSessionKey(state.currentSessionKey);
-		if (!opts.agentId?.trim() && currentParsed?.rest && projectAgentId && projectAgentId !== currentAgentId) {
-			const targetSessionKey = `agent:${projectAgentId}:${currentParsed.rest}`;
-			await setSession(targetSessionKey);
-			if (isGeneratedTuiSessionKey(targetSessionKey)) generatedStartupSessionKeys.add(targetSessionKey);
+		if (!opts.agentId?.trim() && projectAgentId && projectAgentId !== currentAgentId) {
+			const targetConversationId = await client.createConversation(projectAgentId);
+			generatedStartupConversationIds.add(targetConversationId);
+			await setSession(targetConversationId);
 			currentAgentId = projectAgentId;
-			if (isGeneratedTuiSessionKey(state.currentSessionKey)) await client.patchSession(state.currentSessionKey, GENERATED_TUI_SESSION_SHELL_PATCH);
-			await client.patchSession(state.currentSessionKey, {
+			if (isGeneratedTuiConversationId(state.currentConversationId)) await client.patchSession(state.currentConversationId, GENERATED_TUI_SESSION_SHELL_PATCH);
+			await client.patchSession(state.currentConversationId, {
 				projectId: result.project.id,
 				workingDirectory: startupWorkingDirectory,
-				...isGeneratedTuiSessionKey(state.currentSessionKey) ? GENERATED_TUI_SESSION_SHELL_PATCH : {}
+				...isGeneratedTuiConversationId(state.currentConversationId) ? GENERATED_TUI_SESSION_SHELL_PATCH : {}
 			});
 			state.sessionInfo.effectiveWorkspacePath = startupWorkingDirectory;
 			state.sessionInfo.workingDirectoryLocked = true;
-		} else await client.patchSession(state.currentSessionKey, {
+		} else await client.patchSession(state.currentConversationId, {
 			projectId: result.project.id,
-			...isGeneratedTuiSessionKey(state.currentSessionKey) ? GENERATED_TUI_SESSION_SHELL_PATCH : {}
+			...isGeneratedTuiConversationId(state.currentConversationId) ? GENERATED_TUI_SESSION_SHELL_PATCH : {}
 		});
 		const verb = result.created ? "Created project" : "Using project";
 		chatLog.addStatus(theme.dim(`${verb}: ${result.project.name}`));
@@ -1106,7 +1100,7 @@ async function runTui(opts) {
 					clearSeenStreamEventsForRun(runId);
 					if (client.resumeChat) {
 						const resumed = await client.resumeChat({
-							sessionKey: state.currentSessionKey,
+							conversationId: state.currentConversationId,
 							runId
 						});
 						if (resumed.ok) {
@@ -1142,7 +1136,7 @@ async function runTui(opts) {
 	};
 	const setThinkingLevel = async (level) => {
 		try {
-			await client.patchSession(state.currentSessionKey, { thinkingLevel: level });
+			await client.patchSession(state.currentConversationId, { thinkingLevel: level });
 			state.sessionInfo.thinkingLevel = level;
 			const currentModelRef = state.sessionInfo.modelProvider && state.sessionInfo.model ? `${state.sessionInfo.modelProvider}/${state.sessionInfo.model}` : state.sessionInfo.model;
 			if (currentModelRef) {
@@ -1164,7 +1158,7 @@ async function runTui(opts) {
 	};
 	const setReasoningLevel = async (level) => {
 		try {
-			await client.patchSession(state.currentSessionKey, { reasoningLevel: level });
+			await client.patchSession(state.currentConversationId, { reasoningLevel: level });
 			state.sessionInfo.reasoningLevel = level;
 			await refreshSessionInfoWithBorder();
 			updateFooter();
@@ -1178,7 +1172,7 @@ async function runTui(opts) {
 	};
 	const setVerboseLevel = async (level) => {
 		try {
-			await client.patchSession(state.currentSessionKey, { verboseLevel: level });
+			await client.patchSession(state.currentConversationId, { verboseLevel: level });
 			state.sessionInfo.verboseLevel = level;
 			await refreshSessionInfoWithBorder();
 			updateFooter();
@@ -1215,7 +1209,7 @@ async function runTui(opts) {
 			return;
 		}
 		try {
-			if (!(await client.renameSession(state.currentSessionKey, nextName)).ok) {
+			if (!(await client.renameSession(state.currentConversationId, nextName)).ok) {
 				chatLog.addSystem("Session rename failed.");
 				tui.requestRender();
 				return;
@@ -1284,7 +1278,7 @@ async function runTui(opts) {
 			return;
 		}
 		try {
-			await client.patchSession(state.currentSessionKey, { model: trimmed });
+			await client.patchSession(state.currentConversationId, { model: trimmed });
 			state.sessionInfo.modelProvider = selected.provider;
 			state.sessionInfo.model = selected.id;
 			tuiSettings = rememberTuiAgentModel(tuiSettings, newSessionPreferenceKey, currentAgentId, {
@@ -1305,10 +1299,10 @@ async function runTui(opts) {
 		}
 	};
 	const exportCurrentSession = async (request) => {
-		const outputPath = request.outputPath ? isAbsolute(request.outputPath) ? request.outputPath : resolve(process.cwd(), request.outputPath) : defaultExportPath(state.currentSessionKey, request.format);
+		const outputPath = request.outputPath ? isAbsolute(request.outputPath) ? request.outputPath : resolve(process.cwd(), request.outputPath) : defaultExportPath(state.currentConversationId, request.format);
 		try {
 			const backendFormat = request.format === "json" ? "json" : "markdown";
-			const raw = await client.exportSession(state.currentSessionKey, backendFormat);
+			const raw = await client.exportSession(state.currentConversationId, backendFormat);
 			const content = request.format === "html" ? wrapMarkdownExportAsHtml(raw) : raw;
 			mkdirSync(dirname(outputPath), { recursive: true });
 			writeFileSync(outputPath, content, "utf8");
@@ -1328,11 +1322,11 @@ async function runTui(opts) {
 			return;
 		}
 		const inputPath = isAbsolute(rawPath) ? rawPath : resolve(process.cwd(), rawPath);
-		const targetKey = resolveSessionKey(request.targetKey?.trim() || `import-${randomUUID()}`);
+		const targetKey = resolveConversationId(request.targetKey?.trim() || randomUUID());
 		try {
 			const content = readFileSync(inputPath, "utf8");
 			const result = await client.importSession(targetKey, content);
-			await setSession(result.sessionKey);
+			await setSession(result.conversationId);
 			chatLog.addStatus(theme.dim(`Imported ${result.rowCount} transcript rows from: ${inputPath}`));
 		} catch (err) {
 			const errorMessage = err instanceof Error ? err.message : String(err);
@@ -1345,7 +1339,7 @@ async function runTui(opts) {
 		try {
 			chatLog.addStatus(theme.dim(`Creating share for: ${request.path}`));
 			tui.requestRender();
-			const result = await client.createShare(state.currentSessionKey, request, { agentId: currentAgentId });
+			const result = await client.createShare(state.currentConversationId, request, { agentId: currentAgentId });
 			chatLog.addSystem(formatTuiShareResult(result));
 		} catch (err) {
 			const errorMessage = err instanceof Error ? err.message : String(err);
@@ -1357,7 +1351,7 @@ async function runTui(opts) {
 	const startWorkflowRun = async (request) => {
 		if (!client.startWorkflowRun) throw new Error("Workflow runs are not available in this mode.");
 		const result = await client.startWorkflowRun({
-			sessionKey: state.currentSessionKey,
+			conversationId: state.currentConversationId,
 			definitionId: request.definitionId,
 			agentId: currentAgentId,
 			goal: request.goal
@@ -1374,7 +1368,7 @@ async function runTui(opts) {
 			chatLog.addUser(`/btw ${question}`);
 			chatLog.addStatus(theme.dim("BTW running..."));
 			tui.requestRender();
-			const result = await client.btwQuery(state.currentSessionKey, question);
+			const result = await client.btwQuery(state.currentConversationId, question);
 			if (result.error) {
 				chatLog.addSystem(`BTW failed: ${result.error}`);
 				return;
@@ -1397,20 +1391,20 @@ async function runTui(opts) {
 		}
 	};
 	const forkCurrentSession = async (rawKey) => {
-		const targetKey = resolveSessionKey(rawKey?.trim() || `fork-${randomUUID()}`);
-		if (targetKey === state.currentSessionKey) {
+		const targetKey = resolveConversationId(rawKey?.trim() || randomUUID());
+		if (targetKey === state.currentConversationId) {
 			chatLog.addSystem("Fork target must be different from the current session.");
 			tui.requestRender();
 			return;
 		}
-		const sourceSessionKey = state.currentSessionKey;
+		const sourceConversationId = state.currentConversationId;
 		try {
 			await abortActive({ clearUi: false });
-			const result = await client.forkSession(sourceSessionKey, targetKey);
-			await setSession(result.sessionKey);
+			const result = await client.forkSession(sourceConversationId, targetKey);
+			await setSession(result.conversationId);
 			chatLog.addBranchSummary({
-				sourceSessionKey,
-				targetSessionKey: result.sessionKey,
+				sourceConversationId,
+				targetConversationId: result.conversationId,
 				rowCount: result.rowCount
 			});
 		} catch (err) {
@@ -1468,7 +1462,7 @@ async function runTui(opts) {
 		touchStreamingActivity();
 		tui.requestRender();
 		client.submitChatInput({
-			sessionKey: state.currentSessionKey,
+			conversationId: state.currentConversationId,
 			message: text,
 			delivery: "steer"
 		}).then(({ ok, effectiveDelivery }) => {
@@ -1530,7 +1524,7 @@ async function runTui(opts) {
 		touchStreamingActivity();
 		tui.requestRender();
 		client.sendChat({
-			sessionKey: state.currentSessionKey,
+			conversationId: state.currentConversationId,
 			message: messageText,
 			attachments: attachments.length > 0 ? attachments : void 0,
 			thinking: opts.thinking
@@ -1555,7 +1549,7 @@ async function runTui(opts) {
 		}
 		if (options?.deliverAs === "next") {
 			client.submitChatInput({
-				sessionKey: state.currentSessionKey,
+				conversationId: state.currentConversationId,
 				message: text,
 				delivery: "next"
 			}).then((result) => {
@@ -1578,7 +1572,7 @@ async function runTui(opts) {
 		chatLog.addSystem(theme.dim(instructions ? `Compacting session with instructions: ${instructions}` : "Compacting session…"));
 		tui.requestRender();
 		try {
-			const result = await client.compactSession(state.currentSessionKey, {
+			const result = await client.compactSession(state.currentConversationId, {
 				force: true,
 				instructions
 			});
@@ -1685,12 +1679,14 @@ async function runTui(opts) {
 		if (state.activeRunId) await abortActive({ clearUi: false });
 		sendMessage(message);
 	};
-	const switchAgentSession = async (sessionKey, agentId) => {
+	const switchAgentSession = async (conversationId, agentId) => {
 		const previousWorkspace = state.sessionInfo.effectiveWorkspacePath?.trim();
-		await setSession(sessionKey);
+		await client.createConversation(agentId, conversationId);
+		generatedStartupConversationIds.add(conversationId);
+		await setSession(conversationId);
 		await refreshStartupResources();
 		if (previousWorkspace && state.sessionInfo.workingDirectoryLocked !== true) try {
-			await client.patchSession(state.currentSessionKey, { workingDirectory: previousWorkspace });
+			await client.patchSession(state.currentConversationId, { workingDirectory: previousWorkspace });
 			state.sessionInfo.effectiveWorkspacePath = previousWorkspace;
 			state.sessionInfo.workingDirectoryLocked = true;
 			await refreshSessionInfoWithBorder();
@@ -1727,10 +1723,10 @@ async function runTui(opts) {
 		listAgents: () => client.listAgents(),
 		setTuiDefaultAgent: (agentId) => client.setTuiDefaultAgent?.(agentId) ?? Promise.reject(/* @__PURE__ */ new Error("Not available")),
 		switchAgentSession,
-		getSessionStats: () => client.getSessionStats(state.currentSessionKey),
+		getSessionStats: () => client.getSessionStats(state.currentConversationId),
 		getStartupResources: () => startupResources,
-		loadTranscriptTree: () => client.loadTranscriptTree(state.currentSessionKey),
-		loadTimeline: () => client.loadTimeline(state.currentSessionKey),
+		loadTranscriptTree: () => client.loadTranscriptTree(state.currentConversationId),
+		loadTimeline: () => client.loadTimeline(state.currentConversationId),
 		loadHistoryWindow,
 		loadSessionHistory: () => loadSessionHistory(),
 		exportSession: exportCurrentSession,
@@ -1791,7 +1787,7 @@ async function runTui(opts) {
 			return workspace;
 		},
 		onComplete: async (entry) => {
-			await client.appendBashExecution(state.currentSessionKey, entry).catch((err) => {
+			await client.appendBashExecution(state.currentConversationId, entry).catch((err) => {
 				const errorMessage = err instanceof Error ? err.message : String(err);
 				chatLog.addSystem(`Bash transcript append failed: ${errorMessage}`);
 			}).finally(() => {
@@ -1835,12 +1831,12 @@ async function runTui(opts) {
 			applyComposerHistory(await client.getComposerInputHistory());
 		} catch {}
 	};
-	const refreshPendingInputCount = async (sessionKey = state.currentSessionKey) => {
+	const refreshPendingInputCount = async (conversationId = state.currentConversationId) => {
 		try {
-			const inputState = await client.getChatInputState(sessionKey);
-			if (state.currentSessionKey === sessionKey) state.pendingInputCount = countPendingChatInputs(inputState.inputs);
+			const inputState = await client.getChatInputState(conversationId);
+			if (state.currentConversationId === conversationId) state.pendingInputCount = countPendingChatInputs(inputState.inputs);
 		} catch {
-			if (state.currentSessionKey === sessionKey) state.pendingInputCount = 0;
+			if (state.currentConversationId === conversationId) state.pendingInputCount = 0;
 		}
 		bottomBar.invalidate();
 		tui.requestRender();
@@ -1893,17 +1889,17 @@ async function runTui(opts) {
 				tui.requestRender();
 				return;
 			}
-			const sessionKey = state.currentSessionKey;
+			const conversationId = state.currentConversationId;
 			client.submitChatInput({
-				sessionKey,
+				conversationId,
 				message: text,
 				delivery: "next"
 			}).then(async ({ ok }) => {
 				if (!ok) throw new Error("Gateway did not accept the message");
 				recordChatHistory(text);
-				if (state.currentSessionKey === sessionKey && editor.getText().trim() === text) editor.setText("");
+				if (state.currentConversationId === conversationId && editor.getText().trim() === text) editor.setText("");
 				chatLog.addSystem(theme.dim("Queued as the next message."));
-				await refreshPendingInputCount(sessionKey);
+				await refreshPendingInputCount(conversationId);
 			}).catch((error) => {
 				const errorMessage = error instanceof Error ? error.message : String(error);
 				chatLog.addSystem(theme.dim(`Queue failed: ${errorMessage}`));
@@ -1913,15 +1909,16 @@ async function runTui(opts) {
 		}
 		submitBurst(text);
 	};
-	const setSessionKey = (key) => {
-		state.currentSessionKey = resolveSessionKey(key);
+	const setConversationId = (key) => {
+		state.currentConversationId = resolveConversationId(key);
 		state.pendingInputCount = 0;
-		refreshPendingInputCount(state.currentSessionKey);
+		refreshPendingInputCount(state.currentConversationId);
 		updateAgentFromPicker(key);
 	};
 	const updateAgentFromPicker = (key) => {
-		const parsed = parseAgentSessionKey(resolveSessionKey(key));
-		if (parsed?.agentId) currentAgentId = parsed.agentId;
+		client.getSessionInfo(resolveConversationId(key)).then((info) => {
+			if (state.currentConversationId === resolveConversationId(key) && info.agentId) currentAgentId = info.agentId;
+		}).catch(() => void 0);
 	};
 	let ctrlCHandling = false;
 	const handleCtrlC = () => {
@@ -1967,7 +1964,7 @@ async function runTui(opts) {
 		refreshSessionInfo,
 		updateHeader,
 		state,
-		setSessionKey,
+		setConversationId,
 		switchAgentSession,
 		clearChatForSessionSwitch,
 		loadSessionHistory,
@@ -2144,7 +2141,7 @@ async function runTui(opts) {
 	client.onEvent = (evt) => {
 		const data = evt.data ?? {};
 		if (evt.event === "session.input-state") {
-			if (data.sessionKey === state.currentSessionKey && Array.isArray(data.inputs)) {
+			if (data.conversationId === state.currentConversationId && Array.isArray(data.inputs)) {
 				state.pendingInputCount = countPendingChatInputs(data.inputs);
 				bottomBar.invalidate();
 				tui.requestRender();
@@ -2172,11 +2169,16 @@ async function runTui(opts) {
 		dispatchAgentEvent(evt.event, data, state, chatLog, tui, setActivityStatus, touchStreamingActivity, onAgentRunEnded, (message) => sessionSnapshot.appendMessage("assistant", assistantMessagePlainText(message)), evt.source);
 	};
 	let startupSessionPickerOpened = false;
+	let startupConversationCreated = Boolean(opts.session?.trim());
 	client.onConnected = () => {
 		state.isConnected = true;
 		setConnectionStatus(isLocalMode ? "local ready" : "gateway connected");
 		touchStreamingActivity();
 		(async () => {
+			if (!startupConversationCreated) {
+				await client.createConversation(currentAgentId, state.currentConversationId);
+				startupConversationCreated = true;
+			}
 			await refreshComposerHistory();
 			if (opts.openSessionPickerOnStart && !startupSessionPickerOpened) {
 				startupSessionPickerOpened = true;
@@ -2204,9 +2206,9 @@ async function runTui(opts) {
 				const errorMessage = err instanceof Error ? err.message : String(err);
 				chatLog.addSystem(`Project not selected: ${errorMessage}`);
 			}
-			if (!opts.session?.trim() && isGeneratedTuiSessionKey(state.currentSessionKey)) {
+			if (!opts.session?.trim() && isGeneratedTuiConversationId(state.currentConversationId)) {
 				const initialAgentConfig = tuiInitialAgentConfig(tuiSettings, newSessionPreferenceKey, currentAgentId);
-				if (initialAgentConfig || opts.thinking?.trim()) await client.patchSession(state.currentSessionKey, {
+				if (initialAgentConfig || opts.thinking?.trim()) await client.patchSession(state.currentConversationId, {
 					...initialAgentConfig,
 					...opts.thinking?.trim() ? { thinkingLevel: opts.thinking.trim() } : {}
 				});
@@ -2214,13 +2216,13 @@ async function runTui(opts) {
 			await refreshSessionInfoWithBorder();
 			persistCurrentNewSessionContext();
 			try {
-				state.pendingInputCount = countPendingChatInputs((await client.getChatInputState(state.currentSessionKey)).inputs);
+				state.pendingInputCount = countPendingChatInputs((await client.getChatInputState(state.currentConversationId)).inputs);
 			} catch {
 				state.pendingInputCount = 0;
 			}
 			await refreshModelChoices();
 			await loadSessionHistory({ merge: true });
-			cleanupAbandonedTuiSessions(client, state.currentSessionKey).catch(() => {});
+			cleanupAbandonedTuiSessions(client, state.currentConversationId).catch(() => {});
 			showStartupCardOnce();
 			refreshStartupResources().then(() => {
 				updateFooter();