@xopcai/xopc 0.0.284 → 0.0.286

package/dist/src/agent/session/session-config-service.js

@@ -1,6 +1,7 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { chooseModelThinking } from "../../../packages/gateway-contract/src/model-selection.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { ResponseLanguageSchema, init_response_language } from "../../i18n/response-language.js";
 import { normalizeWorkingDirectoryInput } from "../../session/session-workspace.js";
 import { getProjectWorkspacePathForSession } from "../../projects/workspace.js";
@@ -9,21 +10,7 @@ import "../../session/index.js";
 import { getModelThinking } from "../../providers/model-thinking.js";
 import { mkdir } from "node:fs/promises";
 //#region src/agent/session/session-config-service.ts
-/**
-* SessionConfigService — owns the "write side" of per-session agent settings
-* (model override, thinking level, reasoning level, working directory).
-*
-* Previously these lived as four sibling methods on `AgentService`:
-*   - `patchSessionAgentConfig` (96 lines of validation + persistence)
-*   - `applyAutomationWorkingDirectory` (automation working dir update)
-*   - `applyAutomationModelOverride` (automation model update before session creation)
-*   - `clearAutomationWorkingDirectoryOverride` (private helper)
-*   - `clearSessionModelOverride` (private helper)
-*
-* Extracted so `AgentService` no longer mixes "session bag" concerns with
-* "session config write" concerns, and so future additions to the patch API
-* (e.g. new per-session overrides) only touch this file.
-*/
+init_src();
 init_response_language();
 init_logger();
 const log = createLogger("SessionConfigService");
@@ -37,9 +24,9 @@ var SessionConfigService = class {
 	* a session's persisted config. Returns `{ ok: false, error }` on the first
 	* invalid field. Model and thinking are validated together and committed in one write.
 	*/
-	async patch(sessionKey, partial) {
+	async patch(conversationId, partial) {
 		if (partial.model !== void 0 || partial.thinkingLevel !== void 0 || partial.fixedModel) {
-			const existing = await this.opts.sessionConfigStore.get(sessionKey);
+			const existing = await this.opts.sessionConfigStore.get(conversationId);
 			if (partial.configVersion !== void 0 && partial.configVersion !== (existing?.updatedAt ?? 0)) return {
 				ok: false,
 				code: "CONFIG_CHANGED",
@@ -51,9 +38,9 @@ var SessionConfigService = class {
 					code: "INVALID_MODEL",
 					error: "Select a specific model"
 				};
-				await this.clearModelOverride(sessionKey);
+				await this.clearModelOverride(conversationId);
 			} else {
-				const ref = partial.model ?? existing?.modelOverride ?? this.opts.modelManager.getModelForSession(sessionKey);
+				const ref = partial.model ?? existing?.modelOverride ?? this.opts.modelManager.getModelForSession(conversationId);
 				const model = this.opts.modelManager.findByRef(ref);
 				if (!model) return {
 					ok: false,
@@ -69,36 +56,36 @@ var SessionConfigService = class {
 				};
 				const thinkingLevel = requested ?? chooseModelThinking(capabilities, existing?.thinkingLevel);
 				const modelRef = `${model.provider}/${model.id}`;
-				const updated = await this.opts.sessionConfigStore.update(sessionKey, {
+				const updated = await this.opts.sessionConfigStore.update(conversationId, {
 					modelOverride: modelRef,
 					thinkingLevel,
 					fixedModel: partial.fixedModel ?? existing?.fixedModel ?? false
 				});
-				this.opts.modelManager.restoreSessionModel(sessionKey, modelRef, updated.fixedModel === true);
+				this.opts.modelManager.restoreSessionModel(conversationId, modelRef, updated.fixedModel === true);
 				try {
-					if (this.opts.agentManager.getAgent(sessionKey)) {
-						this.opts.agentManager.setModelForSession(sessionKey, modelRef);
-						this.opts.agentManager.setThinkingLevel(sessionKey, thinkingLevel);
+					if (this.opts.agentManager.getAgent(conversationId)) {
+						this.opts.agentManager.setModelForSession(conversationId, modelRef);
+						this.opts.agentManager.setThinkingLevel(conversationId, thinkingLevel);
 					}
 				} catch (err) {
-					this.opts.agentManager.removeAgent(sessionKey);
+					this.opts.agentManager.removeAgent(conversationId);
 					log.warn({
 						err,
-						sessionKey,
+						conversationId,
 						modelRef
 					}, "Saved model configuration; runtime will reload before the next turn");
 				}
 			}
 		}
 		const activityDetailLevel = partial.activityDetailLevel !== void 0 ? partial.activityDetailLevel : partial.reasoningLevel;
-		if (activityDetailLevel !== void 0) if (activityDetailLevel === null) await this.opts.sessionConfigStore.update(sessionKey, { reasoningLevel: void 0 });
+		if (activityDetailLevel !== void 0) if (activityDetailLevel === null) await this.opts.sessionConfigStore.update(conversationId, { reasoningLevel: void 0 });
 		else {
 			const normalized = normalizeReasoningLevel(activityDetailLevel);
 			if (!normalized) return {
 				ok: false,
 				error: "Invalid activity detail level"
 			};
-			await this.opts.sessionConfigStore.update(sessionKey, { reasoningLevel: normalized });
+			await this.opts.sessionConfigStore.update(conversationId, { reasoningLevel: normalized });
 		}
 		if (partial.verboseLevel !== void 0) {
 			const normalized = normalizeVerboseLevel(partial.verboseLevel);
@@ -106,19 +93,19 @@ var SessionConfigService = class {
 				ok: false,
 				error: "Invalid verbose level"
 			};
-			await this.opts.sessionConfigStore.update(sessionKey, { verboseLevel: normalized });
+			await this.opts.sessionConfigStore.update(conversationId, { verboseLevel: normalized });
 		}
 		if (partial.responseLanguage !== void 0) {
-			if (partial.responseLanguage === null) await this.opts.sessionConfigStore.update(sessionKey, { responseLanguage: void 0 });
+			if (partial.responseLanguage === null) await this.opts.sessionConfigStore.update(conversationId, { responseLanguage: void 0 });
 			else {
 				const parsed = ResponseLanguageSchema.safeParse(partial.responseLanguage);
 				if (!parsed.success) return {
 					ok: false,
 					error: "Invalid response language"
 				};
-				await this.opts.sessionConfigStore.update(sessionKey, { responseLanguage: parsed.data });
+				await this.opts.sessionConfigStore.update(conversationId, { responseLanguage: parsed.data });
 			}
-			this.opts.agentManager.removeAgent(sessionKey);
+			this.opts.agentManager.removeAgent(conversationId);
 		}
 		if (partial.userContextMode !== void 0) {
 			if (![
@@ -129,32 +116,32 @@ var SessionConfigService = class {
 				ok: false,
 				error: "Invalid user context mode"
 			};
-			await this.opts.sessionConfigStore.update(sessionKey, { userContextMode: partial.userContextMode });
+			await this.opts.sessionConfigStore.update(conversationId, { userContextMode: partial.userContextMode });
 		}
 		if (partial.workingDirectory !== void 0) {
 			if (!this.opts.getConfig()) return {
 				ok: false,
 				error: "Config not loaded"
 			};
-			if (getProjectWorkspacePathForSession(sessionKey)) return {
+			if (getProjectWorkspacePathForSession(conversationId)) return {
 				ok: false,
 				error: "Project sessions use the project workspace and cannot change working directory"
 			};
-			const result = await this.patchWorkingDirectory(sessionKey, partial.workingDirectory);
+			const result = await this.patchWorkingDirectory(conversationId, partial.workingDirectory);
 			if (!result.ok) return result;
 		}
 		return { ok: true };
 	}
 	/** Materialize a restored/new chat choice; unavailable identities stay visible for repair. */
-	async initializeModelSelection(sessionKey, modelRef, thinkingLevel, configVersion) {
-		const existing = await this.opts.sessionConfigStore.get(sessionKey);
+	async initializeModelSelection(conversationId, modelRef, thinkingLevel, configVersion) {
+		const existing = await this.opts.sessionConfigStore.get(conversationId);
 		if (configVersion !== void 0 && configVersion !== (existing?.updatedAt ?? 0)) return {
 			ok: false,
 			code: "CONFIG_CHANGED",
 			error: "Model configuration changed. Refresh and try again."
 		};
 		const model = this.opts.modelManager.findByRef(modelRef);
-		if (model) return this.patch(sessionKey, {
+		if (model) return this.patch(conversationId, {
 			model: `${model.provider}/${model.id}`,
 			thinkingLevel: chooseModelThinking(getModelThinking(model), thinkingLevel ?? existing?.thinkingLevel),
 			fixedModel: true,
@@ -165,12 +152,12 @@ var SessionConfigService = class {
 			code: "INVALID_MODEL",
 			error: "Select a specific model"
 		};
-		await this.opts.sessionConfigStore.update(sessionKey, {
+		await this.opts.sessionConfigStore.update(conversationId, {
 			modelOverride: modelRef,
 			fixedModel: true,
 			thinkingLevel: normalizeThinkLevel(thinkingLevel) ?? existing?.thinkingLevel ?? "off"
 		});
-		this.opts.modelManager.restoreSessionModel(sessionKey, modelRef, true);
+		this.opts.modelManager.restoreSessionModel(conversationId, modelRef, true);
 		return { ok: true };
 	}
 	/**
@@ -178,24 +165,24 @@ var SessionConfigService = class {
 	* change when the automation is edited; an empty/missing input clears the
 	* override so the session uses the effective agent default.
 	*/
-	async applyAutomationWorkingDirectory(sessionKey, workingDirectory) {
+	async applyAutomationWorkingDirectory(conversationId, workingDirectory) {
 		const raw = workingDirectory?.trim();
 		if (raw) {
 			const wdNorm = normalizeWorkingDirectoryInput(raw);
 			if (wdNorm.ok === false) {
 				log.warn({
-					sessionKey,
+					conversationId,
 					error: wdNorm.error
 				}, "Automation working directory invalid; using agent default");
-				await this.clearAutomationWorkingDirectoryOverride(sessionKey);
+				await this.clearAutomationWorkingDirectoryOverride(conversationId);
 				return;
 			}
 			await mkdir(wdNorm.path, { recursive: true });
-			await this.opts.sessionConfigStore.update(sessionKey, { workingDirectoryOverride: wdNorm.path });
-			this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, wdNorm.path);
+			await this.opts.sessionConfigStore.update(conversationId, { workingDirectoryOverride: wdNorm.path });
+			this.opts.agentManager.setSessionWorkspaceOverride(conversationId, wdNorm.path);
 			return;
 		}
-		await this.clearAutomationWorkingDirectoryOverride(sessionKey);
+		await this.clearAutomationWorkingDirectoryOverride(conversationId);
 	}
 	/**
 	* Persist an automation model override before the direct turn creates/hydrates
@@ -203,36 +190,36 @@ var SessionConfigService = class {
 	* `agentManager.setModelForSession`, because the automation session usually
 	* does not exist yet.
 	*/
-	async applyAutomationModelOverride(sessionKey, model) {
+	async applyAutomationModelOverride(conversationId, model) {
 		const raw = model?.trim();
 		if (!raw) {
-			await this.clearModelOverride(sessionKey);
+			await this.clearModelOverride(conversationId);
 			return true;
 		}
-		if (!await this.opts.modelManager.switchModelForSession(sessionKey, raw)) {
-			await this.clearModelOverride(sessionKey);
+		if (!await this.opts.modelManager.switchModelForSession(conversationId, raw)) {
+			await this.clearModelOverride(conversationId);
 			return false;
 		}
-		await this.opts.sessionConfigStore.update(sessionKey, { modelOverride: raw });
+		await this.opts.sessionConfigStore.update(conversationId, { modelOverride: raw });
 		return true;
 	}
 	/**
 	* Clear the session's model override (back to agent default). Used both by
 	* {@link patch} and by `AgentService.resetSessionModelToAgentDefault`.
 	*/
-	async clearModelOverride(sessionKey) {
-		this.opts.modelManager.clearSessionModelOverride(sessionKey);
-		await this.opts.sessionConfigStore.update(sessionKey, { modelOverride: void 0 });
-		const agent = this.opts.agentManager.getAgent(sessionKey);
-		if (agent) await this.opts.modelManager.applyModelForSession(agent, sessionKey);
+	async clearModelOverride(conversationId) {
+		this.opts.modelManager.clearSessionModelOverride(conversationId);
+		await this.opts.sessionConfigStore.update(conversationId, { modelOverride: void 0 });
+		const agent = this.opts.agentManager.getAgent(conversationId);
+		if (agent) await this.opts.modelManager.applyModelForSession(agent, conversationId);
 	}
-	async clearAutomationWorkingDirectoryOverride(sessionKey) {
-		const existing = await this.opts.sessionConfigStore.get(sessionKey);
+	async clearAutomationWorkingDirectoryOverride(conversationId) {
+		const existing = await this.opts.sessionConfigStore.get(conversationId);
 		if (existing?.workingDirectoryOverride) {
 			const { workingDirectoryOverride: _removed, ...rest } = existing;
-			await this.opts.sessionConfigStore.set(sessionKey, rest);
+			await this.opts.sessionConfigStore.set(conversationId, rest);
 		}
-		this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, null);
+		this.opts.agentManager.setSessionWorkspaceOverride(conversationId, null);
 	}
 	/**
 	* Apply the workingDirectory branch of `patch`. Returns the next-step result
@@ -242,10 +229,10 @@ var SessionConfigService = class {
 	* messages, it cannot move to a different directory — only re-setting the
 	* same path is idempotent.
 	*/
-	async patchWorkingDirectory(sessionKey, workingDirectory) {
-		const existingRaw = (await this.opts.sessionConfigStore.get(sessionKey))?.workingDirectoryOverride?.trim();
+	async patchWorkingDirectory(conversationId, workingDirectory) {
+		const existingRaw = (await this.opts.sessionConfigStore.get(conversationId))?.workingDirectoryOverride?.trim();
 		const incoming = workingDirectory.trim();
-		if ((await this.opts.sessionStore.load(sessionKey)).length > 0) {
+		if ((await this.opts.sessionStore.load(conversationId)).length > 0) {
 			if (!incoming) return {
 				ok: false,
 				error: "workingDirectory is empty"
@@ -274,9 +261,9 @@ var SessionConfigService = class {
 					if (prev.ok && prev.path === wdNorm.path) return { ok: true };
 				}
 				await mkdir(wdNorm.path, { recursive: true });
-				await this.opts.sessionConfigStore.update(sessionKey, { workingDirectoryOverride: wdNorm.path });
-				this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, wdNorm.path);
-				this.opts.agentManager.removeAgent(sessionKey);
+				await this.opts.sessionConfigStore.update(conversationId, { workingDirectoryOverride: wdNorm.path });
+				this.opts.agentManager.setSessionWorkspaceOverride(conversationId, wdNorm.path);
+				this.opts.agentManager.removeAgent(conversationId);
 				return { ok: true };
 			case false: return {
 				ok: false,

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

@@ -4,7 +4,7 @@
  * The previous implementation kept the "current" session context in a single
  * mutable field on the class. That meant bus-inbound and direct-stream paths
  * concurrently handling different sessions could overwrite each other's view
- * of "current session", with tools reading the wrong sessionKey at execution
+ * of "current session", with tools reading the wrong conversationId at execution
  * time (the only thing masking it was the inbound consumer being serial).
  *
  * The new manager uses `AsyncLocalStorage`, so each async chain sees its own
@@ -17,7 +17,7 @@
 import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
 import type { InboundMessage } from '../../infra/bus/index.js';
 export interface SessionContext {
-    sessionKey: string;
+    conversationId: string;
     channel: string;
     chatId: string;
     senderId: string;

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

@@ -6,7 +6,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 * The previous implementation kept the "current" session context in a single
 * mutable field on the class. That meant bus-inbound and direct-stream paths
 * concurrently handling different sessions could overwrite each other's view
-* of "current session", with tools reading the wrong sessionKey at execution
+* of "current session", with tools reading the wrong conversationId at execution
 * time (the only thing masking it was the inbound consumer being serial).
 *
 * The new manager uses `AsyncLocalStorage`, so each async chain sees its own
@@ -47,7 +47,7 @@ var SessionContextManager = class {
 	static extractFromMessage(msg) {
 		const metadata = msg.metadata || {};
 		return {
-			sessionKey: metadata.sessionKey || `${msg.channel}:${msg.chat_id}`,
+			conversationId: metadata.conversationId || `${msg.channel}:${msg.chat_id}`,
 			channel: msg.channel,
 			chatId: msg.chat_id,
 			senderId: metadata.senderId || "",

package/dist/src/agent/session/session-hydrator.d.ts

@@ -30,12 +30,12 @@ export declare class SessionHydrator {
      * Load the effective workspace into AgentManager. Managed environment roots
      * must already exist; ordinary project and agent workspaces may be created.
      */
-    workspace(sessionKey: string): Promise<void>;
+    workspace(conversationId: string): Promise<void>;
     /** Apply persisted `modelOverride` to ModelManager (no-op when none stored). */
-    model(sessionKey: string): Promise<void>;
+    model(conversationId: string): Promise<void>;
     /**
      * Resolve the effective thinking level (request override > per-session
      * override > agent default) and apply it to the live agent instance.
      */
-    thinking(sessionKey: string, requestOverride?: string | null): Promise<void>;
+    thinking(conversationId: string, requestOverride?: string | null): Promise<void>;
 }

package/dist/src/agent/session/session-hydrator.js

@@ -33,45 +33,45 @@ var SessionHydrator = class {
 	* Load the effective workspace into AgentManager. Managed environment roots
 	* must already exist; ordinary project and agent workspaces may be created.
 	*/
-	async workspace(sessionKey) {
+	async workspace(conversationId) {
 		const cfg = this.opts.getConfig();
 		if (!cfg) return;
-		const loaded = await this.opts.sessionConfigStore.get(sessionKey);
-		const project = getProjectForSession(sessionKey);
-		const environment = getExecutionEnvironmentForSession(sessionKey);
+		const loaded = await this.opts.sessionConfigStore.get(conversationId);
+		const project = getProjectForSession(conversationId);
+		const environment = getExecutionEnvironmentForSession(conversationId);
 		const projectWorkspace = projectWorkspacePath(project);
 		if (environment) {
 			if (environment.status !== "ready") throw new Error(`Execution environment ${environment.id} is ${environment.status}`);
 			if (!await stat(environment.rootPath).then((value) => value.isDirectory()).catch(() => false)) throw new Error(`Execution environment root is unavailable: ${environment.rootPath}`);
-			this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, environment.rootPath);
-		} else if (projectWorkspace) this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, projectWorkspace);
+			this.opts.agentManager.setSessionWorkspaceOverride(conversationId, environment.rootPath);
+		} else if (projectWorkspace) this.opts.agentManager.setSessionWorkspaceOverride(conversationId, projectWorkspace);
 		else if (loaded?.workingDirectoryOverride?.trim()) {
 			const wdStored = normalizeWorkingDirectoryInput(loaded.workingDirectoryOverride);
-			if (wdStored.ok) this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, wdStored.path);
+			if (wdStored.ok) this.opts.agentManager.setSessionWorkspaceOverride(conversationId, wdStored.path);
 			else {
-				log.warn({ sessionKey }, "Invalid stored workingDirectoryOverride; ignoring");
-				this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, null);
+				log.warn({ conversationId }, "Invalid stored workingDirectoryOverride; ignoring");
+				this.opts.agentManager.setSessionWorkspaceOverride(conversationId, null);
 			}
-		} else this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, null);
-		const effective = effectiveWorkspacePathForSession(cfg, sessionKey, loaded, project);
+		} else this.opts.agentManager.setSessionWorkspaceOverride(conversationId, null);
+		const effective = effectiveWorkspacePathForSession(cfg, conversationId, loaded, project);
 		if (!environment) await mkdir(effective, { recursive: true });
 	}
 	/** Apply persisted `modelOverride` to ModelManager (no-op when none stored). */
-	async model(sessionKey) {
-		const cfg = await this.opts.sessionConfigStore.get(sessionKey);
-		if (cfg?.modelOverride) this.opts.modelManager.restoreSessionModel(sessionKey, cfg.modelOverride, cfg.fixedModel === true);
+	async model(conversationId) {
+		const cfg = await this.opts.sessionConfigStore.get(conversationId);
+		if (cfg?.modelOverride) this.opts.modelManager.restoreSessionModel(conversationId, cfg.modelOverride, cfg.fixedModel === true);
 	}
 	/**
 	* Resolve the effective thinking level (request override > per-session
 	* override > agent default) and apply it to the live agent instance.
 	*/
-	async thinking(sessionKey, requestOverride) {
-		const level = await resolveEffectiveThinkingLevel(this.opts.sessionConfigStore, sessionKey, requestOverride, void 0);
-		if ((await this.opts.sessionConfigStore.get(sessionKey))?.fixedModel) {
-			const model = this.opts.modelManager.getResolvedModelForSession(sessionKey);
+	async thinking(conversationId, requestOverride) {
+		const level = await resolveEffectiveThinkingLevel(this.opts.sessionConfigStore, conversationId, requestOverride, void 0);
+		if ((await this.opts.sessionConfigStore.get(conversationId))?.fixedModel) {
+			const model = this.opts.modelManager.getResolvedModelForSession(conversationId);
 			if (!getModelThinking(model).options.includes(level)) throw new Error(`Thinking level ${level} is not supported by ${model.provider}/${model.id}`);
 		}
-		this.opts.agentManager.setThinkingLevel(sessionKey, level);
+		this.opts.agentManager.setThinkingLevel(conversationId, level);
 	}
 };
 //#endregion

package/dist/src/agent/session/session-inspector.d.ts

@@ -35,7 +35,7 @@ export interface SessionInspectorOptions {
      * Nominal context window the session is budgeted against. Derived from the
      * effective session model metadata, defaulting to 128k.
      */
-    getContextWindow: (sessionKey: string) => number;
+    getContextWindow: (conversationId: string) => number;
 }
 export interface SessionContextUsage {
     estimatedTokens: number;
@@ -70,25 +70,25 @@ export declare class SessionInspector {
      * pass (`force: true` by default) and evicts the in-memory agent so the
      * next turn reloads from the compacted transcript.
      */
-    compact(sessionKey: string, options?: {
+    compact(conversationId: string, options?: {
         instructions?: string;
         force?: boolean;
     }): Promise<CompactionResult>;
     /** One-shot LLM answer for `/btw`: transcript as background, not persisted. */
-    btwQuery(sessionKey: string, question: string, options?: BtwQueryOptions): Promise<{
+    btwQuery(conversationId: string, question: string, options?: BtwQueryOptions): Promise<{
         text: string;
         error?: string;
     }>;
     /** Cheap stats used by both the report and other callers. */
-    stats(sessionKey: string, messages: AgentMessage[]): {
+    stats(conversationId: string, messages: AgentMessage[]): {
         windowStats: ReturnType<SessionStore['getWindowStats']>;
         compactionStats: ReturnType<SessionStore['getCompactionStats']>;
         tokenEstimate: ReturnType<SessionStore['estimateTokenUsage']>;
     };
     /** Rough context usage for TUI footer (estimated tokens vs nominal budget). */
-    contextUsage(sessionKey: string): Promise<SessionContextUsage>;
+    contextUsage(conversationId: string): Promise<SessionContextUsage>;
     /** Markdown or JSON summary for `/context`. */
-    report(sessionKey: string, mode: 'list' | 'detail' | 'json'): Promise<string>;
+    report(conversationId: string, mode: 'list' | 'detail' | 'json'): Promise<string>;
     /** Resolved thinking / model / workspace for the Web UI. */
-    agentConfig(sessionKey: string): Promise<SessionAgentConfigView>;
+    agentConfig(conversationId: string): Promise<SessionAgentConfigView>;
 }

package/dist/src/agent/session/session-inspector.js

@@ -22,48 +22,48 @@ var SessionInspector = class {
 	constructor(opts) {
 		this.opts = opts;
 	}
-	async ensureEffectiveSessionModel(sessionKey) {
-		await this.opts.sessionHydrator.model(sessionKey);
+	async ensureEffectiveSessionModel(conversationId) {
+		await this.opts.sessionHydrator.model(conversationId);
 		const cfg = this.opts.getConfig();
 		if (!cfg) return;
-		const profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);
+		const profile = resolveEffectiveAgentProfileForSession(cfg, conversationId);
 		const profileModelRef = profile.primaryModelRef?.trim();
-		if (profileModelRef) this.opts.modelManager.setSessionProfileDefault(sessionKey, profileModelRef, profile.fallbacks);
+		if (profileModelRef) this.opts.modelManager.setSessionProfileDefault(conversationId, profileModelRef, profile.fallbacks);
 	}
-	async contextWindowForSession(sessionKey) {
-		await this.ensureEffectiveSessionModel(sessionKey);
-		return this.opts.getContextWindow(sessionKey);
+	async contextWindowForSession(conversationId) {
+		await this.ensureEffectiveSessionModel(conversationId);
+		return this.opts.getContextWindow(conversationId);
 	}
 	/**
 	* Manual compaction triggered by a user / API. Always forces a compaction
 	* pass (`force: true` by default) and evicts the in-memory agent so the
 	* next turn reloads from the compacted transcript.
 	*/
-	async compact(sessionKey, options) {
-		const messages = await this.opts.sessionStore.load(sessionKey);
-		await this.ensureEffectiveSessionModel(sessionKey);
+	async compact(conversationId, options) {
+		const messages = await this.opts.sessionStore.load(conversationId);
+		await this.ensureEffectiveSessionModel(conversationId);
 		const policy = resolveCompactionPolicy(this.opts.getConfig());
-		const sessionModel = this.opts.modelManager.getResolvedModelForSession(sessionKey);
+		const sessionModel = this.opts.modelManager.getResolvedModelForSession(conversationId);
 		const model = policy.model ? resolveModel(policy.model) : sessionModel;
 		const primaryRef = `${model.provider}/${model.id}`;
-		const fallbackModels = this.opts.modelManager.getFallbackCandidatesForSession(sessionKey).map((candidate) => resolveModel(`${candidate.provider}/${candidate.model}`)).filter((candidate) => `${candidate.provider}/${candidate.id}` !== primaryRef);
-		const result = await this.opts.sessionStore.compact(sessionKey, messages, model, options?.instructions, options?.force ?? true, { fallbackModels });
-		if (result.compacted) this.opts.agentManager.removeAgent(sessionKey);
+		const fallbackModels = this.opts.modelManager.getFallbackCandidatesForSession(conversationId).map((candidate) => resolveModel(`${candidate.provider}/${candidate.model}`)).filter((candidate) => `${candidate.provider}/${candidate.id}` !== primaryRef);
+		const result = await this.opts.sessionStore.compact(conversationId, messages, model, options?.instructions, options?.force ?? true, { fallbackModels });
+		if (result.compacted) this.opts.agentManager.removeAgent(conversationId);
 		log.info({
-			sessionKey,
+			conversationId,
 			result
 		}, "Manual compaction complete");
 		return result;
 	}
 	/** One-shot LLM answer for `/btw`: transcript as background, not persisted. */
-	btwQuery(sessionKey, question, options) {
+	btwQuery(conversationId, question, options) {
 		const config = this.opts.getConfig();
-		const profile = config ? resolveEffectiveAgentProfileForSession(config, sessionKey) : void 0;
+		const profile = config ? resolveEffectiveAgentProfileForSession(config, conversationId) : void 0;
 		return runBtwQuery({
-			sessionKey,
+			conversationId,
 			question,
 			sessionStore: this.opts.sessionStore,
-			modelForSession: options?.modelRef?.trim() || this.opts.modelManager.getModelForSession(sessionKey),
+			modelForSession: options?.modelRef?.trim() || this.opts.modelManager.getModelForSession(conversationId),
 			log,
 			maxTokens: options?.maxTokens,
 			temperature: options?.temperature,
@@ -76,18 +76,18 @@ var SessionInspector = class {
 		});
 	}
 	/** Cheap stats used by both the report and other callers. */
-	stats(sessionKey, messages) {
+	stats(conversationId, messages) {
 		return {
 			windowStats: this.opts.sessionStore.getWindowStats(messages),
-			compactionStats: this.opts.sessionStore.getCompactionStats(sessionKey),
-			tokenEstimate: this.opts.sessionStore.estimateTokenUsage(sessionKey, messages)
+			compactionStats: this.opts.sessionStore.getCompactionStats(conversationId),
+			tokenEstimate: this.opts.sessionStore.estimateTokenUsage(conversationId, messages)
 		};
 	}
 	/** Rough context usage for TUI footer (estimated tokens vs nominal budget). */
-	async contextUsage(sessionKey) {
-		const messages = await this.opts.sessionStore.load(sessionKey);
-		const contextWindow = await this.contextWindowForSession(sessionKey);
-		const estimatedTokens = await this.opts.sessionStore.estimateTokenUsage(sessionKey, messages);
+	async contextUsage(conversationId) {
+		const messages = await this.opts.sessionStore.load(conversationId);
+		const contextWindow = await this.contextWindowForSession(conversationId);
+		const estimatedTokens = await this.opts.sessionStore.estimateTokenUsage(conversationId, messages);
 		return {
 			estimatedTokens,
 			contextWindow,
@@ -95,20 +95,20 @@ var SessionInspector = class {
 		};
 	}
 	/** Markdown or JSON summary for `/context`. */
-	async report(sessionKey, mode) {
+	async report(conversationId, mode) {
 		const cfg = this.opts.getConfig();
 		if (!cfg) throw new Error("SessionInspector requires a config snapshot to render report");
-		const messages = await this.opts.sessionStore.load(sessionKey);
-		const cw = await this.contextWindowForSession(sessionKey);
-		const computed = this.stats(sessionKey, messages);
-		const model = this.opts.modelManager.getModelForSession(sessionKey);
-		const workspace = effectiveWorkspacePathForSession(cfg, sessionKey, await this.opts.sessionConfigStore.get(sessionKey), getProjectForSession(sessionKey));
-		const estTokens = await this.opts.sessionStore.estimateTokenUsage(sessionKey, messages);
-		const profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);
+		const messages = await this.opts.sessionStore.load(conversationId);
+		const cw = await this.contextWindowForSession(conversationId);
+		const computed = this.stats(conversationId, messages);
+		const model = this.opts.modelManager.getModelForSession(conversationId);
+		const workspace = effectiveWorkspacePathForSession(cfg, conversationId, await this.opts.sessionConfigStore.get(conversationId), getProjectForSession(conversationId));
+		const estTokens = await this.opts.sessionStore.estimateTokenUsage(conversationId, messages);
+		const profile = resolveEffectiveAgentProfileForSession(cfg, conversationId);
 		const deniedTools = [...profile.tools.denied].sort((a, b) => a.localeCompare(b));
 		const toolsSummary = deniedTools.length > 0 ? `denied: ${deniedTools.join(", ")}` : "(no denied tools)";
 		return formatSessionContextReport({
-			sessionKey,
+			conversationId,
 			mode,
 			model,
 			workspacePath: workspace,
@@ -126,21 +126,21 @@ var SessionInspector = class {
 		});
 	}
 	/** Resolved thinking / model / workspace for the Web UI. */
-	async agentConfig(sessionKey) {
-		await this.ensureEffectiveSessionModel(sessionKey);
+	async agentConfig(conversationId) {
+		await this.ensureEffectiveSessionModel(conversationId);
 		const cfg = this.opts.getConfig();
 		if (!cfg) throw new Error("SessionInspector requires a config snapshot to resolve agent config");
-		const sc = await this.opts.sessionConfigStore.get(sessionKey);
-		const level = await resolveEffectiveThinkingLevel(this.opts.sessionConfigStore, sessionKey, null, "medium");
+		const sc = await this.opts.sessionConfigStore.get(conversationId);
+		const level = await resolveEffectiveThinkingLevel(this.opts.sessionConfigStore, conversationId, null, "medium");
 		const defReason = resolveConfiguredActivityDetailDefault(cfg);
-		const reasoningLevel = await resolveEffectiveReasoningLevel(this.opts.sessionConfigStore, sessionKey, defReason);
-		const verboseLevel = await resolveVerboseLevel(this.opts.sessionConfigStore, sessionKey, "full");
-		const model = this.opts.modelManager.getModelForSession(sessionKey);
-		const project = getProjectForSession(sessionKey);
-		const environment = getExecutionEnvironmentForSession(sessionKey);
+		const reasoningLevel = await resolveEffectiveReasoningLevel(this.opts.sessionConfigStore, conversationId, defReason);
+		const verboseLevel = await resolveVerboseLevel(this.opts.sessionConfigStore, conversationId, "full");
+		const model = this.opts.modelManager.getModelForSession(conversationId);
+		const project = getProjectForSession(conversationId);
+		const environment = getExecutionEnvironmentForSession(conversationId);
 		const projectWorkspace = projectWorkspacePath(project);
 		const hasSessionWorkspaceOverride = Boolean(sc?.workingDirectoryOverride?.trim());
-		const effectiveWorkspacePath = effectiveWorkspacePathForSession(cfg, sessionKey, sc, project);
+		const effectiveWorkspacePath = effectiveWorkspacePathForSession(cfg, conversationId, sc, project);
 		const isDefaultWorkspaceRoot = effectiveWorkspacePath === resolveDefaultAgentWorkspaceDir();
 		return {
 			thinkingLevel: level,

package/dist/src/agent/session/session-lifecycle.d.ts

@@ -37,9 +37,9 @@ export declare class SessionLifecycleManager {
     /**
      * Get the start time for a session
      */
-    getSessionStartTime(sessionKey: string): number | undefined;
+    getSessionStartTime(conversationId: string): number | undefined;
     /**
      * Check if a session is currently active
      */
-    isSessionActive(sessionKey: string): boolean;
+    isSessionActive(conversationId: string): boolean;
 }