@xopcai/xopc 0.0.285 → 0.0.286

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

@@ -1,6 +1,9 @@
 import { deleteBrowserTabBinding } from "../../../storage/sqlite/browser-tab-binding-repository.js";
+import { conversationIdSchema } from "../../../../packages/gateway-contract/src/conversation-identity.js";
 import { SessionDiscoveryQuerySchema } from "../../../../packages/gateway-contract/src/session-identity.js";
-import { buildSessionKey, init_session_key } from "../../../routing/session-key.js";
+import { init_src } from "../../../../packages/gateway-contract/src/index.js";
+import { deleteSessionRecord, init_session_repository } from "../../../storage/sqlite/session-repository.js";
+import { ConversationAlreadyExistsError, createConversation, init_conversation_repository } from "../../../storage/sqlite/conversation-repository.js";
 import { resolveProjectAgentId } from "../../../projects/project-agent.js";
 import "../../../projects/index.js";
 import { messagesToClientHistory } from "../../../session/client-history.js";
@@ -14,7 +17,9 @@ import { getSessionContextSummary } from "../../session-context-summary.js";
 import { respondStartupUnavailable } from "../lib/startup-unavailable.js";
 import { randomUUID } from "node:crypto";
 //#region src/gateway/hono/routes/sessions.ts
-init_session_key();
+init_src();
+init_conversation_repository();
+init_session_repository();
 const log = createGatewayRouteLogger("Sessions");
 const SESSION_TYPES = new Set([
 	"chat",
@@ -95,14 +100,14 @@ function registerSessionsRoutes(authenticated, deps) {
 		const inboxOffset = parseOffset(c.req.query("inboxOffset"));
 		const staleDays = parsePositiveInt(c.req.query("staleDays"), DEFAULT_SIDEBAR_STALE_DAYS, 3650);
 		const updatedAfter = Date.now() - staleDays * 24 * 60 * 60 * 1e3;
-		const includeSessionKey = c.req.query("includeSessionKey")?.trim() || void 0;
+		const includeConversationId = c.req.query("includeConversationId")?.trim() || void 0;
 		const projects = service.projects.listWithSidebarSessions({
 			status: "active",
 			limit: projectLimit,
 			offset: projectOffset,
 			updatedAfter,
 			includePinned: true,
-			includeSessionKey
+			includeConversationId
 		});
 		const projectItems = await Promise.all(projects.items.map(async (project) => {
 			const sessions = await service.sessions.listSessions({
@@ -111,7 +116,7 @@ function registerSessionsRoutes(authenticated, deps) {
 				offset: 0,
 				updatedAfter,
 				includePinned: true,
-				includeSessionKey,
+				includeConversationId,
 				sortBy: "updatedAt",
 				sortOrder: "desc"
 			});
@@ -128,7 +133,7 @@ function registerSessionsRoutes(authenticated, deps) {
 			offset: inboxOffset,
 			updatedAfter,
 			includePinned: true,
-			includeSessionKey,
+			includeConversationId,
 			sortBy: "updatedAt",
 			sortOrder: "desc"
 		});
@@ -146,6 +151,10 @@ function registerSessionsRoutes(authenticated, deps) {
 	});
 	authenticated.post("/api/sessions", async (c) => {
 		const body = await c.req.json().catch(() => ({}));
+		if (body.conversationId !== void 0 && !conversationIdSchema.safeParse(body.conversationId).success) return c.json({
+			ok: false,
+			error: "conversationId must be a UUID"
+		}, 400);
 		const channel = typeof body.channel === "string" && body.channel.trim() ? body.channel.trim() : "webchat";
 		const projectId = typeof body.projectId === "string" && body.projectId.trim() ? body.projectId.trim() : void 0;
 		const routingCfg = service.currentConfig;
@@ -163,29 +172,54 @@ function registerSessionsRoutes(authenticated, deps) {
 			ok: false,
 			error: "An execution mode requires a project"
 		}, 400);
-		const agentId = resolveProjectAgentId({
-			config: routingCfg,
-			projects: service.projects,
-			explicitAgentId: typeof body.agentId === "string" ? body.agentId : void 0,
-			projectId
-		});
+		let agentId;
+		try {
+			agentId = resolveProjectAgentId({
+				config: routingCfg,
+				projects: service.projects,
+				explicitAgentId: typeof body.agentId === "string" ? body.agentId : void 0,
+				projectId
+			});
+		} catch (error) {
+			return c.json({
+				ok: false,
+				error: error instanceof Error ? error.message : String(error)
+			}, 400);
+		}
 		const chatId = (typeof body.chat_id === "string" && body.chat_id.trim() ? body.chat_id.trim() : void 0) ?? `chat_${randomUUID()}`;
-		const sessionKey = buildSessionKey({
+		const metadata = {
 			agentId,
-			source: channel,
-			accountId: "default",
-			peerKind: "direct",
-			peerId: chatId
-		});
+			...buildDirectSessionMetadata({
+				agentId,
+				source: channel,
+				accountId: "default",
+				peerId: chatId
+			}),
+			...channel === "tui" ? {
+				hiddenFromSessionList: true,
+				customData: { genericNewChatShell: true }
+			} : {}
+		};
+		let conversationId;
+		try {
+			conversationId = createConversation(metadata, "", body.conversationId).key;
+		} catch (error) {
+			if (error instanceof ConversationAlreadyExistsError) return c.json({
+				ok: false,
+				error: error.message
+			}, 409);
+			throw error;
+		}
 		let environment;
 		if (project && (project.workspaceRoot?.trim() || requestedExecutionMode)) try {
 			environment = await environments.attach({
-				sessionKey,
+				conversationId,
 				project,
 				mode: requestedExecutionMode,
 				baseRef: typeof body.baseRef === "string" ? body.baseRef : void 0
 			});
 		} catch (error) {
+			deleteSessionRecord(conversationId);
 			return c.json({
 				ok: false,
 				code: "execution_environment_unavailable",
@@ -193,16 +227,11 @@ function registerSessionsRoutes(authenticated, deps) {
 			}, 409);
 		}
 		try {
-			await service.sessionIndexInstance.saveMessages(sessionKey, [], { metadata: buildDirectSessionMetadata({
-				agentId,
-				source: channel,
-				accountId: "default",
-				peerId: chatId
-			}) });
-			if (projectId) service.projects.attachSession(sessionKey, projectId);
+			await service.sessionIndexInstance.saveMessages(conversationId, [], { metadata });
+			if (projectId) service.projects.attachSession(conversationId, projectId);
 		} catch (error) {
-			await service.sessions.delete(sessionKey).catch(() => void 0);
-			await environments.release(sessionKey).catch(() => void 0);
+			await service.sessions.delete(conversationId).catch(() => void 0);
+			await environments.release(conversationId).catch(() => void 0);
 			throw error;
 		}
 		const rawInitialConfig = body.initialAgentConfig && typeof body.initialAgentConfig === "object" ? body.initialAgentConfig : {};
@@ -214,13 +243,13 @@ function registerSessionsRoutes(authenticated, deps) {
 			...body.temporary === true ? { userContextMode: "temporary" } : {}
 		};
 		if (channel === "webchat" && model) {
-			const result = await service.sessions.initializeChatModel(sessionKey, model, thinkingLevel);
+			const result = await service.sessions.initializeChatModel(conversationId, model, thinkingLevel);
 			if (!result.ok) {
-				await service.sessions.delete(sessionKey).catch(() => void 0);
-				await environments.release(sessionKey).catch((error) => {
+				await service.sessions.delete(conversationId).catch(() => void 0);
+				await environments.release(conversationId).catch((error) => {
 					log.warn({
 						err: error,
-						sessionKey
+						conversationId
 					}, "Invalid new session model and execution environment cleanup failed");
 				});
 				return c.json({
@@ -232,13 +261,13 @@ function registerSessionsRoutes(authenticated, deps) {
 			delete initialAgentConfig.thinkingLevel;
 		}
 		if (Object.keys(initialAgentConfig).length > 0) {
-			const result = await service.sessions.patchAgentConfig(sessionKey, initialAgentConfig);
+			const result = await service.sessions.patchAgentConfig(conversationId, initialAgentConfig);
 			if (!result.ok) {
-				await service.sessions.delete(sessionKey).catch(() => void 0);
-				await environments.release(sessionKey).catch((error) => {
+				await service.sessions.delete(conversationId).catch(() => void 0);
+				await environments.release(conversationId).catch((error) => {
 					log.warn({
 						err: error,
-						sessionKey
+						conversationId
 					}, "Invalid new session config and execution environment cleanup failed");
 				});
 				return c.json({
@@ -247,10 +276,11 @@ function registerSessionsRoutes(authenticated, deps) {
 				}, 400);
 			}
 		}
-		if (body.createdSurface === "browser_extension") await service.sessions.patch(sessionKey, { customData: { createdSurface: "browser_extension" } });
-		const session = await service.sessions.getSession(sessionKey);
-		const agentConfig = channel === "webchat" ? await service.sessions.getFixedAgentConfig(sessionKey) : void 0;
+		if (body.createdSurface === "browser_extension") await service.sessions.patch(conversationId, { customData: { createdSurface: "browser_extension" } });
+		const session = await service.sessions.getSession(conversationId);
+		const agentConfig = channel === "webchat" ? await service.sessions.getFixedAgentConfig(conversationId) : void 0;
 		return c.json({
+			conversationId,
 			session,
 			agentConfig,
 			...environment ? { environment } : {}
@@ -281,7 +311,7 @@ function registerSessionsRoutes(authenticated, deps) {
 			unassigned: query.unassigned === "true",
 			updatedAfter: query.updatedAfter ? parseInt(query.updatedAfter) : void 0,
 			includePinned: query.includePinned === "true",
-			includeSessionKey: query.includeSessionKey,
+			includeConversationId: query.includeConversationId,
 			limit: query.limit ? parseInt(query.limit) : void 0,
 			offset: query.offset ? parseInt(query.offset) : void 0
 		});
@@ -301,8 +331,8 @@ function registerSessionsRoutes(authenticated, deps) {
 	});
 	authenticated.get("/api/sessions/resolve", async (c) => {
 		const result = await service.sessions.resolveSession({
-			sessionId: c.req.query("sessionId"),
-			sessionKey: c.req.query("sessionKey") ?? c.req.query("key")
+			transcriptId: c.req.query("transcriptId"),
+			conversationId: c.req.query("conversationId")
 		});
 		if (!result) return c.json({
 			ok: false,
@@ -316,9 +346,8 @@ function registerSessionsRoutes(authenticated, deps) {
 	authenticated.post("/api/sessions/resolve", async (c) => {
 		const body = await c.req.json().catch(() => ({}));
 		const result = await service.sessions.resolveSession({
-			sessionId: typeof body.sessionId === "string" ? body.sessionId : void 0,
-			sessionKey: typeof body.sessionKey === "string" ? body.sessionKey : void 0,
-			key: typeof body.key === "string" ? body.key : void 0
+			transcriptId: typeof body.transcriptId === "string" ? body.transcriptId : void 0,
+			conversationId: typeof body.conversationId === "string" ? body.conversationId : void 0
 		});
 		if (!result) return c.json({
 			ok: false,
@@ -572,7 +601,7 @@ function registerSessionsRoutes(authenticated, deps) {
 		} catch (err) {
 			logRouteError(log, c, err, "gateway.route.sessions", {
 				operation: "restoreCompactionBoundary",
-				sessionKey: key
+				conversationId: key
 			});
 			const msg = err instanceof Error ? err.message : String(err);
 			if (msg.includes("not found")) return c.json({
@@ -833,8 +862,8 @@ function registerSessionsRoutes(authenticated, deps) {
 		return c.json({
 			ok: true,
 			reset: true,
-			sessionId: result.sessionId,
-			previousSessionId: result.previousSessionId,
+			transcriptId: result.transcriptId,
+			previousTranscriptId: result.previousTranscriptId,
 			session
 		});
 	});
@@ -851,7 +880,7 @@ function registerSessionsRoutes(authenticated, deps) {
 			await environments.release(key).catch((error) => {
 				log.warn({
 					err: error,
-					sessionKey: key
+					conversationId: key
 				}, "Session deleted but execution environment cleanup failed");
 			});
 		}
@@ -893,7 +922,7 @@ function registerSessionsRoutes(authenticated, deps) {
 	});
 	authenticated.get("/api/subagents/:key", async (c) => {
 		const key = c.req.param("key");
-		if (!key.startsWith("subagent:")) return c.json({ error: "Not a subagent session" }, 400);
+		if ((await service.sessions.getSession(key))?.sessionType !== "workflow-subagent") return c.json({ error: "Not a subagent session" }, 400);
 		const includeRaw = c.req.query("include") ?? "";
 		const includeSet = new Set(includeRaw.split(",").map((s) => s.trim()).filter(Boolean));
 		const session = await service.sessions.getSession(key, {

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)