@xopcai/xopc 0.0.285 → 0.0.291

package/dist/src/gateway/hono/routes/shares.js

@@ -217,7 +217,7 @@ function registerSharePublicRoutes(app, service) {
 				}, 410);
 				logShareAudit("share.access", {
 					shareId: record.id,
-					sourceSessionId: record.sourceSessionId,
+					sourceTranscriptId: record.sourceTranscriptId,
 					tokenPrefix: token.slice(0, 8),
 					clientIp,
 					snapshotRevision: record.snapshotRevision
@@ -272,7 +272,7 @@ function registerSharePublicRoutes(app, service) {
 		} catch {
 			logShareAudit("share.access_denied", {
 				shareId: record.id,
-				...record.kind === "note" ? { noteId: record.sourceNoteId } : { sourceSessionId: record.sourceSessionId },
+				...record.kind === "note" ? { noteId: record.sourceNoteId } : { sourceTranscriptId: record.sourceTranscriptId },
 				tokenPrefix: token.slice(0, 8),
 				clientIp,
 				reason: "artifact_missing"
@@ -557,13 +557,13 @@ function registerShareRoutes(authenticated, deps) {
 	});
 	authenticated.get("/api/sessions/:key/shares", async (c) => {
 		const metadata = await service.sessionIndexInstance.getSessionMetadata(c.req.param("key"));
-		if (!metadata?.sessionId) return c.json({
+		if (!metadata?.transcriptId) return c.json({
 			ok: false,
 			error: { message: "Session not found" }
 		}, 404);
 		const urlCtx = getShareUrlContext(service);
 		const now = Date.now();
-		const items = sessionShares.list(metadata.sessionId).map((record) => {
+		const items = sessionShares.list(metadata.transcriptId).map((record) => {
 			const resolved = resolveShareUrl(record.token, urlCtx);
 			return {
 				id: record.id,
@@ -596,13 +596,13 @@ function registerShareRoutes(authenticated, deps) {
 	authenticated.post("/api/sessions/:key/shares", async (c) => {
 		const principalId = getGatewayPrincipal(c).principalId;
 		const body = await c.req.json().catch(() => ({}));
-		if (typeof body.expectedSessionId !== "string" || typeof body.expectedCutoffSeq !== "number" || typeof body.expectedMetadataUpdatedAt !== "string") return c.json({
+		if (typeof body.expectedTranscriptId !== "string" || typeof body.expectedCutoffSeq !== "number" || typeof body.expectedMetadataUpdatedAt !== "string") return c.json({
 			ok: false,
 			error: { message: "Share preview fingerprint is required" }
 		}, 400);
 		try {
 			const record = await sessionShares.create(c.req.param("key"), {
-				expectedSessionId: body.expectedSessionId,
+				expectedTranscriptId: body.expectedTranscriptId,
 				expectedCutoffSeq: body.expectedCutoffSeq,
 				expectedMetadataUpdatedAt: body.expectedMetadataUpdatedAt,
 				ttlMs: typeof body.ttlMs === "number" ? body.ttlMs : void 0,
@@ -646,13 +646,13 @@ function registerShareRoutes(authenticated, deps) {
 	});
 	authenticated.post("/api/sessions/:key/shares/:shareId/refresh", async (c) => {
 		const body = await c.req.json().catch(() => ({}));
-		if (typeof body.expectedSessionId !== "string" || typeof body.expectedCutoffSeq !== "number" || typeof body.expectedMetadataUpdatedAt !== "string") return c.json({
+		if (typeof body.expectedTranscriptId !== "string" || typeof body.expectedCutoffSeq !== "number" || typeof body.expectedMetadataUpdatedAt !== "string") return c.json({
 			ok: false,
 			error: { message: "Share preview fingerprint is required" }
 		}, 400);
 		try {
 			const record = await sessionShares.refresh(c.req.param("key"), c.req.param("shareId"), {
-				expectedSessionId: body.expectedSessionId,
+				expectedTranscriptId: body.expectedTranscriptId,
 				expectedCutoffSeq: body.expectedCutoffSeq,
 				expectedMetadataUpdatedAt: body.expectedMetadataUpdatedAt,
 				includeToolActivities: typeof body.includeToolActivities === "boolean" ? body.includeToolActivities : void 0,
@@ -692,7 +692,7 @@ function registerShareRoutes(authenticated, deps) {
 	});
 	authenticated.get("/api/sessions/:key/hosted-shares", async (c) => {
 		const metadata = await service.sessionIndexInstance.getSessionMetadata(c.req.param("key"));
-		if (!metadata?.sessionId) return c.json({
+		if (!metadata?.transcriptId) return c.json({
 			ok: false,
 			error: { message: "Session not found" }
 		}, 404);
@@ -700,7 +700,7 @@ function registerShareRoutes(authenticated, deps) {
 			await hostedBindings.reconcile(await hostedPublisher.listPublications());
 			return c.json({
 				ok: true,
-				payload: { shares: (await hostedBindings.list(metadata.sessionId)).map(hostedBindingResponse) }
+				payload: { shares: (await hostedBindings.list(metadata.transcriptId)).map(hostedBindingResponse) }
 			});
 		} catch (err) {
 			return hostedShareErrorResponse(c, err);
@@ -708,7 +708,7 @@ function registerShareRoutes(authenticated, deps) {
 	});
 	authenticated.post("/api/sessions/:key/hosted-shares", async (c) => {
 		const body = await c.req.json().catch(() => ({}));
-		if (typeof body.expectedSessionId !== "string" || typeof body.expectedCutoffSeq !== "number" || typeof body.expectedMetadataUpdatedAt !== "string") return c.json({
+		if (typeof body.expectedTranscriptId !== "string" || typeof body.expectedCutoffSeq !== "number" || typeof body.expectedMetadataUpdatedAt !== "string") return c.json({
 			ok: false,
 			error: { message: "Share preview fingerprint is required" }
 		}, 400);
@@ -724,15 +724,15 @@ function registerShareRoutes(authenticated, deps) {
 				kind: "session_document",
 				source: {
 					kind: "session",
-					id: snapshot.sessionId,
+					id: snapshot.transcriptId,
 					version: String(snapshot.cutoffSeq)
 				},
 				revisionSources: { [String(result.snapshotRevision)]: {
 					kind: "session",
-					id: snapshot.sessionId,
+					id: snapshot.transcriptId,
 					version: String(snapshot.cutoffSeq)
 				} },
-				sessionId: snapshot.sessionId,
+				transcriptId: snapshot.transcriptId,
 				cutoffSeq: snapshot.cutoffSeq,
 				title: snapshot.manifest.title,
 				description: snapshot.manifest.description ?? null,
@@ -755,11 +755,11 @@ function registerShareRoutes(authenticated, deps) {
 	});
 	authenticated.post("/api/sessions/:key/hosted-shares/:shareId/refresh", async (c) => {
 		const body = await c.req.json().catch(() => ({}));
-		if (typeof body.expectedSessionId !== "string" || typeof body.expectedCutoffSeq !== "number" || typeof body.expectedMetadataUpdatedAt !== "string") return c.json({
+		if (typeof body.expectedTranscriptId !== "string" || typeof body.expectedCutoffSeq !== "number" || typeof body.expectedMetadataUpdatedAt !== "string") return c.json({
 			ok: false,
 			error: { message: "Share preview fingerprint is required" }
 		}, 400);
-		const previous = (await hostedBindings.list(body.expectedSessionId)).find((binding) => binding.id === c.req.param("shareId") && !binding.revoked);
+		const previous = (await hostedBindings.list(body.expectedTranscriptId)).find((binding) => binding.id === c.req.param("shareId") && !binding.revoked);
 		if (!previous) return c.json({
 			ok: false,
 			error: { message: "Hosted share not found" }
@@ -778,14 +778,14 @@ function registerShareRoutes(authenticated, deps) {
 				kind: "session_document",
 				source: {
 					kind: "session",
-					id: snapshot.sessionId,
+					id: snapshot.transcriptId,
 					version: String(snapshot.cutoffSeq)
 				},
 				revisionSources: {
 					...previous.revisionSources,
 					[String(result.snapshotRevision)]: {
 						kind: "session",
-						id: snapshot.sessionId,
+						id: snapshot.transcriptId,
 						version: String(snapshot.cutoffSeq)
 					}
 				},
@@ -808,11 +808,11 @@ function registerShareRoutes(authenticated, deps) {
 	});
 	authenticated.delete("/api/sessions/:key/hosted-shares/:shareId", async (c) => {
 		const metadata = await service.sessionIndexInstance.getSessionMetadata(c.req.param("key"));
-		if (!metadata?.sessionId) return c.json({
+		if (!metadata?.transcriptId) return c.json({
 			ok: false,
 			error: { message: "Session not found" }
 		}, 404);
-		const binding = (await hostedBindings.list(metadata.sessionId)).find((item) => item.id === c.req.param("shareId"));
+		const binding = (await hostedBindings.list(metadata.transcriptId)).find((item) => item.id === c.req.param("shareId"));
 		if (!binding) return c.json({
 			ok: false,
 			error: { message: "Hosted share not found" }
@@ -947,7 +947,7 @@ function registerShareRoutes(authenticated, deps) {
 			error: { message: "Static site path is required" }
 		}, 400);
 		try {
-			const workspaceRoot = await resolveWorkspaceRootForShare(service, typeof body.sessionKey === "string" ? body.sessionKey : void 0, typeof body.agentId === "string" ? body.agentId : void 0);
+			const workspaceRoot = await resolveWorkspaceRootForShare(service, typeof body.conversationId === "string" ? body.conversationId : void 0, typeof body.agentId === "string" ? body.agentId : void 0);
 			if (!workspaceRoot) return c.json({
 				ok: false,
 				error: { message: "Workspace not configured" }
@@ -960,7 +960,7 @@ function registerShareRoutes(authenticated, deps) {
 				spaFallback: typeof body.spaFallback === "boolean" ? body.spaFallback : void 0,
 				ttlMs: typeof body.ttlMs === "number" ? body.ttlMs : 864e5,
 				maxViews: body.maxViews === null ? null : typeof body.maxViews === "number" ? body.maxViews : null,
-				sessionKey: typeof body.sessionKey === "string" ? body.sessionKey : void 0,
+				conversationId: typeof body.conversationId === "string" ? body.conversationId : void 0,
 				agentId: typeof body.agentId === "string" ? body.agentId : void 0
 			}, {
 				builder: hostedSiteBuilder,
@@ -986,7 +986,7 @@ function registerShareRoutes(authenticated, deps) {
 			error: { message: "Hosted publication not found" }
 		}, 404);
 		try {
-			const workspaceRoot = previous.workspaceContext?.workspaceRoot ?? await resolveWorkspaceRootForShare(service, previous.workspaceContext?.sessionKey, previous.workspaceContext?.agentId);
+			const workspaceRoot = previous.workspaceContext?.workspaceRoot ?? await resolveWorkspaceRootForShare(service, previous.workspaceContext?.conversationId, previous.workspaceContext?.agentId);
 			if (!workspaceRoot) return c.json({
 				ok: false,
 				error: { message: "Workspace not configured" }
@@ -1147,7 +1147,7 @@ function registerShareRoutes(authenticated, deps) {
 			ok: false,
 			error: { message: "Provide exactly one of path, fileId or uri" }
 		}, 400);
-		const sessionKey = typeof body.sessionKey === "string" ? body.sessionKey.trim() : void 0;
+		const conversationId = typeof body.conversationId === "string" ? body.conversationId.trim() : void 0;
 		const agentId = typeof body.agentId === "string" ? body.agentId.trim() : void 0;
 		const taskId = typeof body.taskId === "string" ? body.taskId.trim() : void 0;
 		const fileName = typeof body.fileName === "string" ? basename(body.fileName.trim().replace(/\\/g, "/")) : void 0;
@@ -1159,12 +1159,12 @@ function registerShareRoutes(authenticated, deps) {
 				path = target.resource.relativePath || ".";
 			} else if (uri) {
 				const media = await resolveScopedMediaReference(service, uri, {
-					sessionKey,
+					conversationId,
 					taskId
 				});
 				workspaceRoot = dirname(media.path);
 				path = basename(media.path);
-			} else workspaceRoot = await resolveWorkspaceRootForShare(service, sessionKey, agentId);
+			} else workspaceRoot = await resolveWorkspaceRootForShare(service, conversationId, agentId);
 			if (!workspaceRoot) throw new Error("Workspace not configured");
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
@@ -1190,7 +1190,7 @@ function registerShareRoutes(authenticated, deps) {
 				ttlMs,
 				maxViews,
 				description,
-				sessionKey,
+				conversationId,
 				agentId,
 				workspaceRoot,
 				gatewayTokenHash: hashPrincipal(principalId),
@@ -1250,7 +1250,7 @@ function registerShareRoutes(authenticated, deps) {
 			ok: false,
 			error: { message: "Missing path or fileId" }
 		}, 400);
-		const sessionKey = typeof body.sessionKey === "string" ? body.sessionKey.trim() : void 0;
+		const conversationId = typeof body.conversationId === "string" ? body.conversationId.trim() : void 0;
 		const agentId = typeof body.agentId === "string" ? body.agentId.trim() : void 0;
 		const mode = typeof body.mode === "string" && [
 			"auto",
@@ -1271,7 +1271,7 @@ function registerShareRoutes(authenticated, deps) {
 				const target = await getGatewayFileSpaceService(service).resource(fileId);
 				workspaceRoot = target.space.root;
 				path = target.resource.relativePath || ".";
-			} else workspaceRoot = await resolveWorkspaceRootForShare(service, sessionKey, agentId);
+			} else workspaceRoot = await resolveWorkspaceRootForShare(service, conversationId, agentId);
 			if (!workspaceRoot) return c.json({
 				ok: false,
 				error: { message: "Workspace not configured" }
@@ -1319,7 +1319,7 @@ function registerShareRoutes(authenticated, deps) {
 						spaFallback: true,
 						ttlMs,
 						maxViews: maxViews ?? null,
-						sessionKey,
+						conversationId,
 						agentId
 					}, {
 						builder: hostedSiteBuilder,
@@ -1372,7 +1372,7 @@ function registerShareRoutes(authenticated, deps) {
 					subdomain: typeof body.subdomain === "string" ? body.subdomain : void 0,
 					spaFallback: true,
 					rewriteMode: "html-css",
-					sessionKey,
+					conversationId,
 					agentId,
 					workspaceRoot,
 					gatewayTokenHash: tokenHash
@@ -1482,7 +1482,7 @@ function registerShareRoutes(authenticated, deps) {
 					snapshotRevision: r.snapshotRevision,
 					attachmentCount: r.attachmentCount
 				} : r.kind === "session" ? {
-					sourceSessionId: r.sourceSessionId,
+					sourceTranscriptId: r.sourceTranscriptId,
 					cutoffSeq: r.cutoffSeq,
 					snapshotRevision: r.snapshotRevision,
 					messageCount: r.messageCount,
@@ -1615,13 +1615,13 @@ function createSessionShareService(service, store) {
 }
 function createSessionShareSource(service) {
 	return {
-		getMetadata: (sessionKey) => service.sessionIndexInstance.getSessionMetadata(sessionKey),
-		getSnapshot: async (sessionKey) => loadCompactionSourceSnapshot(sessionKey)
+		getMetadata: (conversationId) => service.sessionIndexInstance.getSessionMetadata(conversationId),
+		getSnapshot: async (conversationId) => loadCompactionSourceSnapshot(conversationId)
 	};
 }
 function hostedBuildInput(body) {
 	return {
-		expectedSessionId: String(body.expectedSessionId),
+		expectedTranscriptId: String(body.expectedTranscriptId),
 		expectedCutoffSeq: Number(body.expectedCutoffSeq),
 		expectedMetadataUpdatedAt: String(body.expectedMetadataUpdatedAt),
 		description: typeof body.description === "string" ? body.description.trim() || void 0 : void 0,
@@ -1887,10 +1887,10 @@ function relPathFromAbs(workspaceRoot, abs) {
 	if (abs.startsWith(`${root}\\`)) return abs.slice(root.length + 1).replace(/\\/g, "/");
 	return abs.split(/[\\/]/).pop() ?? abs;
 }
-async function resolveWorkspaceRootForShare(service, sessionKey, agentId) {
+async function resolveWorkspaceRootForShare(service, conversationId, agentId) {
 	const cfg = service.currentConfig;
-	if (sessionKey) try {
-		return await service.sessions.getEffectiveWorkspacePath(sessionKey);
+	if (conversationId) try {
+		return await service.sessions.getEffectiveWorkspacePath(conversationId);
 	} catch {}
 	const { getWorkspacePath } = await import("../../../config/workspace-path-helpers.js");
 	const { resolveAgentWorkspaceDir, normalizeAgentId, resolveDefaultAgentId } = await import("../../../agent/agent-scope.js");

package/dist/src/gateway/hono/routes/side-chats.js

@@ -1,4 +1,5 @@
 import { chooseModelThinking } from "../../../../packages/gateway-contract/src/model-selection.js";
+import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { init_providers, resolveModel } from "../../../providers/index.js";
 import { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.js";
 import { getModelThinking } from "../../../providers/model-thinking.js";
@@ -7,12 +8,13 @@ import { SideChatError, parseThinkingLevel } from "../../side-chat/manager.js";
 import "../../side-chat/index.js";
 import { createGatewayRouteLogger, logRouteError } from "../lib/route-logger.js";
 //#region src/gateway/hono/routes/side-chats.ts
+init_src();
 init_providers();
 const CLIENT_HEADER = "x-xopc-client-instance-id";
 const log = createGatewayRouteLogger("SideChats");
 function registerSideChatRoutes(authenticated, deps) {
 	const { service } = deps;
-	authenticated.post("/api/sessions/:parentSessionKey/side-chats", deps.chatRateLimitMiddleware, async (c) => {
+	authenticated.post("/api/sessions/:parentConversationId/side-chats", deps.chatRateLimitMiddleware, async (c) => {
 		try {
 			const body = await c.req.json().catch(() => ({}));
 			const clientInstanceId = readClientInstanceId(c, body.clientInstanceId);
@@ -25,7 +27,7 @@ function registerSideChatRoutes(authenticated, deps) {
 				throw new SideChatError(error instanceof Error ? error.message : "Invalid selections", "INVALID_REQUEST");
 			}
 			const sideChat = await service.sideChats.create({
-				parentSessionKey: c.req.param("parentSessionKey"),
+				parentConversationId: c.req.param("parentConversationId"),
 				clientInstanceId,
 				selections,
 				config: {

package/dist/src/gateway/hono/routes/site-shares.js

@@ -29,10 +29,10 @@ function buildShareUrls(record, publicHostSuffix, service) {
 function registerSiteShareRoutes(authenticated, deps) {
 	const { service } = deps;
 	const store = getSiteShareStore(resolveSiteShareConfig(service));
-	async function resolveWorkspaceRoot(sessionKey, agentId) {
+	async function resolveWorkspaceRoot(conversationId, agentId) {
 		const cfg = service.currentConfig;
-		if (sessionKey) try {
-			return await service.sessions.getEffectiveWorkspacePath(sessionKey);
+		if (conversationId) try {
+			return await service.sessions.getEffectiveWorkspacePath(conversationId);
 		} catch {}
 		const { getWorkspacePath } = await import("../../../config/workspace-path-helpers.js");
 		const { resolveAgentWorkspaceDir, normalizeAgentId, resolveDefaultAgentId } = await import("../../../agent/agent-scope.js");
@@ -57,7 +57,7 @@ function registerSiteShareRoutes(authenticated, deps) {
 			ok: false,
 			error: { message: "kind must be 'static' or 'proxy'" }
 		}, 400);
-		const sessionKey = typeof body.sessionKey === "string" ? body.sessionKey.trim() : void 0;
+		const conversationId = typeof body.conversationId === "string" ? body.conversationId.trim() : void 0;
 		const agentId = typeof body.agentId === "string" ? body.agentId.trim() : void 0;
 		const path = typeof body.path === "string" ? body.path.trim() : void 0;
 		const upstreamUrl = typeof body.upstreamUrl === "string" ? body.upstreamUrl.trim() : void 0;
@@ -70,7 +70,7 @@ function registerSiteShareRoutes(authenticated, deps) {
 		const forwardWebSocket = typeof body.forwardWebSocket === "boolean" ? body.forwardWebSocket : void 0;
 		let workspaceRoot = null;
 		if (kind === "static") {
-			workspaceRoot = await resolveWorkspaceRoot(sessionKey, agentId);
+			workspaceRoot = await resolveWorkspaceRoot(conversationId, agentId);
 			if (!workspaceRoot) return c.json({
 				ok: false,
 				error: { message: "Workspace not configured" }
@@ -89,7 +89,7 @@ function registerSiteShareRoutes(authenticated, deps) {
 				spaFallback,
 				rewriteMode,
 				forwardWebSocket,
-				sessionKey,
+				conversationId,
 				agentId,
 				workspaceRoot,
 				gatewayTokenHash: hashPrincipal(principalId)

package/dist/src/gateway/hono/routes/tasks.js

@@ -1,9 +1,10 @@
-import { runSqliteWriteTransaction } from "../../../storage/sqlite/transaction.js";
+import { init_transaction, runSqliteWriteTransaction } from "../../../storage/sqlite/transaction.js";
 import { TaskPhaseSchema } from "../../../../packages/gateway-contract/src/task-lifecycle.js";
 import { TaskBoardPositionRequestSchema, TaskCommandRequestSchema, TaskContextInputSchema, TaskCreateRequestSchema, TaskDependencyUpdateRequestSchema, TaskHandoffRequestSchema, TaskPatchRequestSchema } from "../../../../packages/gateway-contract/src/tasks.js";
 import { ProjectMonitoringUpdateSchema } from "../../../../packages/gateway-contract/src/project-monitoring.js";
-import { enqueueTaskChangedEvent } from "../../../tasks/task-change-events.js";
-import { TaskRunRepository } from "../../../tasks/task-run-repository.js";
+import { init_src } from "../../../../packages/gateway-contract/src/index.js";
+import { enqueueTaskChangedEvent, init_task_change_events } from "../../../tasks/task-change-events.js";
+import { TaskRunRepository, init_task_run_repository } from "../../../tasks/task-run-repository.js";
 import { TaskRepository } from "../../../tasks/task-repository.js";
 import { TaskConversationRepository } from "../../../tasks/task-conversation-repository.js";
 import { TaskReadModelProjector } from "../../../tasks/task-read-model-projector.js";
@@ -21,6 +22,10 @@ import { submitSessionInput } from "./session-input-handler.js";
 import { patchChatModelConfig } from "./chat-model-config.js";
 import { TaskConversationQueryService } from "../../service/task-conversation-query-service.js";
 //#region src/gateway/hono/routes/tasks.ts
+init_src();
+init_transaction();
+init_task_change_events();
+init_task_run_repository();
 function registerTaskRoutes(authenticated, deps) {
 	const taskRateLimit = deps.taskRateLimitMiddleware ?? deps.strictRateLimitMiddleware;
 	const application = new TaskApplicationService();
@@ -39,7 +44,7 @@ function registerTaskRoutes(authenticated, deps) {
 	const handoffs = new TaskHandoffService({
 		getConfig: () => deps.service.currentConfig,
 		sessionIndex: deps.service.sessionIndexInstance,
-		getActiveRunId: (sessionKey) => deps.service.getActiveWebchatRunId(sessionKey),
+		getActiveRunId: (conversationId) => deps.service.getActiveWebchatRunId(conversationId),
 		abortRun: (runId) => deps.service.abortAgentRun(runId)
 	});
 	authenticated.get("/api/tasks", (c) => {
@@ -189,7 +194,7 @@ function registerTaskRoutes(authenticated, deps) {
 				conversation: result.conversation,
 				...result.fromAgentId ? { fromAgentId: result.fromAgentId } : {},
 				toAgentId: result.toAgentId,
-				activeSessionKey: result.activeSessionKey,
+				activeConversationId: result.activeConversationId,
 				assignmentEpoch: result.assignmentEpoch
 			});
 		} catch (error) {
@@ -202,22 +207,22 @@ function registerTaskRoutes(authenticated, deps) {
 	});
 	authenticated.post("/api/tasks/:id/inputs", deps.chatRateLimitMiddleware, async (c) => {
 		const active = conversations.getActiveSession(c.req.param("id"));
-		if (!active?.sessionKey) return c.json({
+		if (!active?.conversationId) return c.json({
 			ok: false,
 			error: {
 				code: "NOT_FOUND",
 				message: "Task has no active conversation"
 			}
 		}, 404);
-		const expectedSessionKey = c.req.header("X-Xopc-Expected-Session-Key")?.trim();
-		if (expectedSessionKey && expectedSessionKey !== active.sessionKey) return c.json({
+		const expectedConversationId = c.req.header("X-Xopc-Expected-Session-Key")?.trim();
+		if (expectedConversationId && expectedConversationId !== active.conversationId) return c.json({
 			ok: false,
 			error: {
 				code: "CONFLICT",
 				message: "Task executor changed; refresh the conversation"
 			}
 		}, 409);
-		return submitSessionInput(c, deps, active.sessionKey);
+		return submitSessionInput(c, deps, active.conversationId);
 	});
 	authenticated.patch("/api/tasks/:id/conversation/config", taskRateLimit, async (c) => {
 		const body = await c.req.json().catch(() => null);
@@ -226,11 +231,11 @@ function registerTaskRoutes(authenticated, deps) {
 			error: "Invalid configuration"
 		}, 400);
 		const active = conversations.getActiveSession(c.req.param("id"));
-		if (!active?.sessionKey) return c.json({
+		if (!active?.conversationId) return c.json({
 			ok: false,
 			error: "Task has no active conversation"
 		}, 404);
-		return patchChatModelConfig(c, deps.service, active.sessionKey, body);
+		return patchChatModelConfig(c, deps.service, active.conversationId, body);
 	});
 	authenticated.get("/api/tasks/:id/conversation/history", async (c) => {
 		const parsedLimit = Number.parseInt(c.req.query("limit") ?? "50", 10);
@@ -409,8 +414,8 @@ function registerTaskRoutes(authenticated, deps) {
 		}
 		if (parsed.data.command?.type === "add_wait" && parsed.data.command.wait.kind === "paused" || parsed.data.command?.type === "close" || parsed.data.command?.type === "resolve_wait" && parsed.data.command.resolution?.kind === "task_approval" && parsed.data.command.resolution.decision === "deny") {
 			const activeRun = runs.getActiveRoot(c.req.param("id"));
-			if (activeRun?.sessionKey) {
-				const liveRunId = deps.service.getActiveWebchatRunId(activeRun.sessionKey);
+			if (activeRun?.conversationId) {
+				const liveRunId = deps.service.getActiveWebchatRunId(activeRun.conversationId);
 				if (liveRunId) await deps.service.abortAgentRun(liveRunId);
 			}
 		}

package/dist/src/gateway/hono/routes/tui.js

@@ -2,8 +2,8 @@ import { collectTuiStartupResources } from "../../../tui/tui-startup-resources.j
 //#region src/gateway/hono/routes/tui.ts
 function registerTuiRoutes(authenticated, deps) {
 	authenticated.get("/api/tui/startup-resources", (c) => {
-		const sessionKey = c.req.query("sessionKey")?.trim() || void 0;
-		const payload = collectTuiStartupResources(deps.service.currentConfig, sessionKey);
+		const conversationId = c.req.query("conversationId")?.trim() || void 0;
+		const payload = collectTuiStartupResources(deps.service.currentConfig, conversationId);
 		return c.json({
 			ok: true,
 			payload

package/dist/src/gateway/hono/routes/user-model.js

@@ -388,7 +388,7 @@ function registerUserModelRoutes(authenticated, deps) {
 			context: {
 				agentId: c.req.query("agentId") ?? "main",
 				workspaceId: c.req.query("workspaceId") ?? "",
-				sessionId: c.req.query("sessionId") ?? "",
+				conversationId: c.req.query("sessionId") ?? "",
 				...c.req.query("projectId") ? { projectId: c.req.query("projectId") } : {}
 			},
 			recordClass: "memory",

package/dist/src/gateway/hono/routes/voice.js

@@ -1,3 +1,5 @@
+import { voiceSelectionSchema } from "../../../../packages/realtime-protocol/src/voice-catalog.js";
+import { createVoiceSessionRequestSchema, init_voice } from "../../../../packages/realtime-protocol/src/voice.js";
 import { getDefaultModelSync, init_providers, resolveModel } from "../../../providers/index.js";
 import { completeWithResolvedCredentials } from "../../../providers/model-call.js";
 import { resolveTtsProviderConfigSlice } from "../../../voice/tts/config-slice.js";
@@ -14,15 +16,16 @@ import "../../../voice/stt/index.js";
 import { listSttProvidersForApi } from "../../../voice/stt/list-providers.js";
 import "../../../voice/tts/index.js";
 import { withModelConfigLock } from "../../../session/model-config-lock.js";
-import { createVoiceSessionRequestSchema } from "../../../../packages/realtime-protocol/src/voice.js";
 import { resolveOmniRoute } from "../../../voice/realtime/omniRoute.js";
 import { VoiceSessionCreationError, resolveStreamingStt, resolveStreamingTts } from "../../../voice/realtime/runtime.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
 import { createGatewayRouteLogger } from "../lib/route-logger.js";
+import { selectPlatformVoice, voiceSettingsCatalog } from "../../../voice/platform-settings.js";
 import { listLocalVoiceModelStatuses, removeLocalVoiceModel, startLocalVoiceModelInstall } from "../../../voice/local/model-manager.js";
 import { listTtsProvidersForApi } from "../../../voice/tts/list-providers.js";
 import { z } from "zod";
 //#region src/gateway/hono/routes/voice.ts
+init_voice();
 init_providers();
 const log = createGatewayRouteLogger("Voice");
 function readVoiceApiKeyFromConfigFileOnly(cfg, kind, providerId) {
@@ -117,6 +120,57 @@ async function refineTranscript(raw, config, signal) {
 }
 function registerVoiceRoutes(authenticated, deps) {
 	const { service, strictRateLimitMiddleware } = deps;
+	authenticated.get("/api/voice/catalog", (c) => c.json({
+		ok: true,
+		payload: voiceSettingsCatalog(service.currentConfig)
+	}));
+	authenticated.post("/api/voice/catalog/refresh", strictRateLimitMiddleware, async (c) => {
+		const result = await service.getModelCatalogSync().refreshNow();
+		if (result.error || result.state !== "ready") return c.json({
+			ok: false,
+			error: {
+				code: "CATALOG_REFRESH_FAILED",
+				message: "Voice catalog could not be refreshed"
+			}
+		}, 503);
+		return c.json({
+			ok: true,
+			payload: voiceSettingsCatalog(service.currentConfig)
+		});
+	});
+	authenticated.put("/api/voice/selection", strictRateLimitMiddleware, async (c) => {
+		const parsed = z.strictObject({
+			revision: z.string(),
+			selection: voiceSelectionSchema
+		}).safeParse(await c.req.json().catch(() => null));
+		if (!parsed.success) return c.json({
+			ok: false,
+			error: { message: "Invalid voice selection" }
+		}, 400);
+		return withModelConfigLock("__voice_settings__", async () => {
+			if (voiceSettingsCatalog(service.currentConfig).revision !== parsed.data.revision) return c.json({
+				ok: false,
+				error: { message: "Voice settings changed; refresh before saving" }
+			}, 409);
+			try {
+				const next = selectPlatformVoice(service.currentConfig, parsed.data.selection);
+				const result = await service.saveConfig(next);
+				if (!result.saved) return c.json({
+					ok: false,
+					error: { message: result.error }
+				}, 500);
+				return c.json({
+					ok: true,
+					payload: voiceSettingsCatalog(service.currentConfig)
+				});
+			} catch (error) {
+				return c.json({
+					ok: false,
+					error: { message: error instanceof Error ? error.message : "Voice selection failed" }
+				}, 400);
+			}
+		});
+	});
 	authenticated.get("/api/voice/realtime/status", async (c) => {
 		const config = service.currentConfig;
 		const stt = resolveStreamingStt(config);
@@ -223,7 +277,7 @@ function registerVoiceRoutes(authenticated, deps) {
 			}
 			const principal = getGatewayPrincipal(c);
 			const create = () => service.voiceRealtime.createSession(parsed.data, principal.principalId);
-			const payload = parsed.data.sessionKey ? await withModelConfigLock(parsed.data.sessionKey, create) : await create();
+			const payload = parsed.data.conversationId ? await withModelConfigLock(parsed.data.conversationId, create) : await create();
 			return c.json({
 				ok: true,
 				payload

package/dist/src/gateway/hono/routes/workflows.js

@@ -289,7 +289,7 @@ function registerWorkflowRoutes(authenticated, deps) {
 		const body = await readJsonBody(c.req.raw);
 		const definitionId = body.definitionId?.trim();
 		if (!definitionId) return c.json({ error: "definitionId is required" }, 400);
-		const parentSessionKey = body.parentSessionKey?.trim() || void 0;
+		const parentConversationId = body.parentConversationId?.trim() || void 0;
 		const taskRunId = body.taskRunId?.trim();
 		const projectId = body.projectId?.trim();
 		if (projectId && !service.projects.get(projectId)) return c.json({ error: "Project not found" }, 404);
@@ -315,7 +315,7 @@ function registerWorkflowRoutes(authenticated, deps) {
 			input: body.inputEnvelope ? void 0 : body.input,
 			inputEnvelope: body.inputEnvelope,
 			goal: body.goal,
-			parentSessionKey,
+			parentConversationId,
 			source: normalizeWorkflowRunSource(body.source),
 			concurrency: normalizePositiveInteger(body.concurrency),
 			maxSubagents: normalizePositiveInteger(body.maxSubagents),
@@ -328,7 +328,7 @@ function registerWorkflowRoutes(authenticated, deps) {
 		}, result.httpStatus);
 		return c.json({
 			runId: result.runId,
-			sessionKey: result.sessionKey
+			conversationId: result.conversationId
 		}, 202);
 	});
 	authenticated.get("/api/workflows/runs", async (c) => {
@@ -374,10 +374,10 @@ function registerWorkflowRoutes(authenticated, deps) {
 		const normalizedWorkflowAgentId = workflowAgentId.startsWith("agent-") ? workflowAgentId : `agent-${workflowAgentId}`;
 		const agent = view.agents.find((item) => item.id === workflowAgentId || item.id === normalizedWorkflowAgentId);
 		if (!agent) return c.json({ error: "Workflow agent not found" }, 404);
-		const session = await service.sessions.getSession(agent.sessionKey);
+		const session = await service.sessions.getSession(agent.conversationId);
 		if (!session || session.sessionType !== "workflow-subagent") return c.json({ error: "Workflow agent session not found" }, 404);
 		return c.json({
-			sessionKey: agent.sessionKey,
+			conversationId: agent.conversationId,
 			metadata: {
 				sessionType: session.sessionType,
 				workflowRunId: session.workflowRunId,
@@ -456,7 +456,7 @@ function registerWorkflowRoutes(authenticated, deps) {
 		}, result.httpStatus);
 		return c.json({
 			runId: result.runId,
-			sessionKey: result.sessionKey
+			conversationId: result.conversationId
 		}, 202);
 	});
 	authenticated.post("/api/workflows/runs/:runId/replay", async (c) => {
@@ -475,7 +475,7 @@ function registerWorkflowRoutes(authenticated, deps) {
 		}, result.httpStatus);
 		return c.json({
 			runId: result.runId,
-			sessionKey: result.sessionKey
+			conversationId: result.conversationId
 		}, 202);
 	});
 }

package/dist/src/gateway/media-access.d.ts

@@ -1,6 +1,6 @@
 import type { GatewayService } from './service.js';
 /** Resolve media only when the supplied session or task references it. */
 export declare function resolveScopedMediaReference(service: GatewayService, uri: string, scope: {
-    sessionKey?: string;
+    conversationId?: string;
     taskId?: string;
 }): Promise<import("../media/media-reference.js").ResolvedMediaReference>;

package/dist/src/gateway/media-access.js

@@ -7,10 +7,10 @@ import { messagesReferenceMediaUri } from "../media/session-references.js";
 //#region src/gateway/media-access.ts
 /** Resolve media only when the supplied session or task references it. */
 async function resolveScopedMediaReference(service, uri, scope) {
-	const { sessionKey, taskId } = scope;
-	if (!sessionKey && !taskId) throw new FileServiceError(400, "Missing media scope");
+	const { conversationId, taskId } = scope;
+	if (!conversationId && !taskId) throw new FileServiceError(400, "Missing media scope");
 	const media = await resolveMediaReference(uri);
-	const sessionReferencesUri = sessionKey ? messagesReferenceMediaUri(await service.sessionIndexInstance.loadMessages(sessionKey), media.uri) || pendingTranscriptReferencesMediaUri(sessionKey, media.uri) : false;
+	const sessionReferencesUri = conversationId ? messagesReferenceMediaUri(await service.sessionIndexInstance.loadMessages(conversationId), media.uri) || pendingTranscriptReferencesMediaUri(conversationId, media.uri) : false;
 	const taskReferencesUri = taskId && new TaskRepository().get(taskId) ? new TaskContextRepository().list(taskId).some((edge) => edge.targetKind === "file" && edge.targetId === media.uri) : false;
 	if (!sessionReferencesUri && !taskReferencesUri) throw new FileServiceError(404, "Not found");
 	return media;