@xopcai/xopc 0.0.285 → 0.0.286

package/dist/src/projects/types.d.ts

@@ -59,7 +59,7 @@ export interface SidebarProjectListQuery {
     status?: ProjectStatus | ProjectStatus[];
     updatedAfter?: number;
     includePinned?: boolean;
-    includeSessionKey?: string;
+    includeConversationId?: string;
     limit?: number;
     offset?: number;
 }

package/dist/src/projects/workflow-bind.js

@@ -1,5 +1,6 @@
-import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
 //#region src/projects/workflow-bind.ts
+init_transaction();
 function bindWorkflowRunToProject(runId, projectId) {
 	const db = getSqliteDatabase();
 	if (!db.prepare(`SELECT 1 FROM projects WHERE project_id = ?`).get(projectId)) throw new Error(`Project not found: ${projectId}`);

package/dist/src/projects/workspace.d.ts

@@ -1,5 +1,5 @@
 import type { Config } from '../config/schema.js';
 import type { Project } from './types.js';
-export declare function resolveProjectWorkspacePath(config: Config, sessionKey: string, project: Project | null): string;
-export declare function getProjectForSession(sessionKey: string): Project | null;
-export declare function getProjectWorkspacePathForSession(sessionKey: string): string | null;
+export declare function resolveProjectWorkspacePath(config: Config, conversationId: string, project: Project | null): string;
+export declare function getProjectForSession(conversationId: string): Project | null;
+export declare function getProjectWorkspacePathForSession(conversationId: string): string | null;

package/dist/src/projects/workspace.js

@@ -5,19 +5,19 @@ import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.
 import { projectWorkspacePath } from "../session/session-workspace.js";
 import { ProjectStore } from "./project-store.js";
 //#region src/projects/workspace.ts
-function resolveProjectWorkspacePath(config, sessionKey, project) {
+function resolveProjectWorkspacePath(config, conversationId, project) {
 	const projectWorkspace = projectWorkspacePath(project);
 	if (projectWorkspace) return projectWorkspace;
-	return resolveEffectiveAgentProfileForSession(config, sessionKey).resolvedWorkspacePath;
+	return resolveEffectiveAgentProfileForSession(config, conversationId).resolvedWorkspacePath;
 }
-function getProjectForSession(sessionKey) {
+function getProjectForSession(conversationId) {
 	if (!isXopcDatabaseOpen()) return null;
-	const projectId = getSessionMetadata(sessionKey)?.projectId;
+	const projectId = getSessionMetadata(conversationId)?.projectId;
 	if (!projectId) return null;
 	return new ProjectStore().get(projectId);
 }
-function getProjectWorkspacePathForSession(sessionKey) {
-	return projectWorkspacePath(getProjectForSession(sessionKey));
+function getProjectWorkspacePathForSession(conversationId) {
+	return projectWorkspacePath(getProjectForSession(conversationId));
 }
 //#endregion
 export { getProjectForSession, getProjectWorkspacePathForSession, resolveProjectWorkspacePath };

package/dist/src/providers/model-reference-auditor.js

@@ -43,7 +43,7 @@ function collectReferences(config, sessionConfigs) {
 	const out = [];
 	collectModelPolicy(out, config.agents.defaults.models, "agents.defaults.models");
 	for (const agent of config.agents.list) collectModelPolicy(out, agent.models, `agents.list.${agent.id}.models`);
-	for (const [sessionKey, sessionConfig] of sessionConfigs) addRef(out, sessionConfig.modelOverride, `sessions.${sessionKey}.modelOverride`);
+	for (const [conversationId, sessionConfig] of sessionConfigs) addRef(out, sessionConfig.modelOverride, `sessions.${conversationId}.modelOverride`);
 	return out;
 }
 function suggestedRef(ref, catalog) {

package/dist/src/providers/prompt-cache-lifecycle.d.ts

@@ -1,9 +1,9 @@
 import type { Api, Model } from '@earendil-works/pi-ai';
 import type { PromptCachePolicy } from './prompt-cache-plan.js';
 export declare function resolvePromptCacheTtlMs(model: Model<Api>, policy: PromptCachePolicy): number;
-export declare function recordPromptCacheTouch(sessionKey: string, model: Model<Api>, usage: {
+export declare function recordPromptCacheTouch(conversationId: string, model: Model<Api>, usage: {
     cacheRead?: number;
     cacheWrite?: number;
 }, now?: number): void;
-export declare function isPromptCacheExpired(sessionKey: string, model: Model<Api>, policy: PromptCachePolicy, now?: number): boolean;
+export declare function isPromptCacheExpired(conversationId: string, model: Model<Api>, policy: PromptCachePolicy, now?: number): boolean;
 export declare function clearPromptCacheTouches(): void;

package/dist/src/providers/prompt-cache-lifecycle.js

@@ -1,16 +1,16 @@
 //#region src/providers/prompt-cache-lifecycle.ts
 const cacheTouchByScope = /* @__PURE__ */ new Map();
 const MAX_CACHE_TOUCHES = 512;
-function scopeKey(sessionKey, model) {
-	return `${sessionKey}\0${model.provider}/${model.id}`;
+function scopeKey(conversationId, model) {
+	return `${conversationId}\0${model.provider}/${model.id}`;
 }
 function resolvePromptCacheTtlMs(model, policy) {
 	if (model.api === "openai-responses" && /^gpt-5\.6(?:-|$)/.test(model.id)) return 30 * 6e4;
 	return policy.lifetime === "long" ? 60 * 6e4 : 5 * 6e4;
 }
-function recordPromptCacheTouch(sessionKey, model, usage, now = Date.now()) {
+function recordPromptCacheTouch(conversationId, model, usage, now = Date.now()) {
 	if ((usage.cacheRead ?? 0) <= 0 && (usage.cacheWrite ?? 0) <= 0) return;
-	const key = scopeKey(sessionKey, model);
+	const key = scopeKey(conversationId, model);
 	cacheTouchByScope.delete(key);
 	cacheTouchByScope.set(key, now);
 	while (cacheTouchByScope.size > MAX_CACHE_TOUCHES) {
@@ -19,9 +19,9 @@ function recordPromptCacheTouch(sessionKey, model, usage, now = Date.now()) {
 		cacheTouchByScope.delete(oldest);
 	}
 }
-function isPromptCacheExpired(sessionKey, model, policy, now = Date.now()) {
+function isPromptCacheExpired(conversationId, model, policy, now = Date.now()) {
 	if (policy.mode === "off") return false;
-	const touchedAt = cacheTouchByScope.get(scopeKey(sessionKey, model));
+	const touchedAt = cacheTouchByScope.get(scopeKey(conversationId, model));
 	return touchedAt !== void 0 && now - touchedAt >= resolvePromptCacheTtlMs(model, policy);
 }
 function clearPromptCacheTouches() {

package/dist/src/realtime/broker.js

@@ -20,7 +20,7 @@ var RealtimeBroker = class {
 		realtimeEventNameSchema.parse(event);
 		const state = this.ensureTopic(topic);
 		const message = {
-			protocolVersion: 1,
+			protocolVersion: 2,
 			messageId: crypto.randomUUID(),
 			kind: "realtime.event",
 			sentAt: now,
@@ -70,7 +70,7 @@ var RealtimeBroker = class {
 	replayFrom(topic, state, afterSeq) {
 		const currentSeq = state.nextSeq - 1;
 		if (afterSeq > currentSeq) return [{
-			protocolVersion: 1,
+			protocolVersion: 2,
 			messageId: crypto.randomUUID(),
 			kind: "realtime.gap",
 			sentAt: Date.now(),
@@ -84,7 +84,7 @@ var RealtimeBroker = class {
 		if (currentSeq <= afterSeq) return [];
 		const earliestSeq = state.events[0]?.payload.seq;
 		if (earliestSeq === void 0 || afterSeq + 1 < earliestSeq) return [{
-			protocolVersion: 1,
+			protocolVersion: 2,
 			messageId: crypto.randomUUID(),
 			kind: "realtime.gap",
 			sentAt: Date.now(),

package/dist/src/realtime/runtime.js

@@ -18,7 +18,7 @@ const MAX_SUBSCRIPTIONS = 100;
 const MAX_CONNECTIONS = 100;
 function serverMessage(kind, payload) {
 	return {
-		protocolVersion: 1,
+		protocolVersion: 2,
 		messageId: crypto.randomUUID(),
 		kind,
 		sentAt: Date.now(),

package/dist/src/retrieval/queryProfile.d.ts

@@ -1,6 +1,6 @@
 export type RetrievalTimeHint = 'current' | 'recent' | 'historical' | 'future';
 export interface RetrievalScope {
-    sessionKey?: string;
+    conversationId?: string;
     workspaceId?: string;
     projectId?: string;
 }

package/dist/src/routing/agent-session-key.d.ts

@@ -1,58 +1,29 @@
-/**
- * OpenClaw-aligned agent session keys: `agent:{agentId}:{rest}`
- */
-export { getSubagentDepth, isAcpSessionKey, isCronSessionKey, isSubagentSessionKey, parseAgentSessionKey, parseThreadSessionSuffix, type ParsedAgentSessionKey, } from './session-key-utils.js';
-export { DEFAULT_ACCOUNT_ID, normalizeAccountId, normalizeOptionalAccountId, } from './account-id.js';
+export { DEFAULT_ACCOUNT_ID, normalizeAccountId, normalizeOptionalAccountId } from './account-id.js';
 export declare const DEFAULT_AGENT_ID = "main";
 export declare const DEFAULT_MAIN_KEY = "main";
-export type SessionKeyShape = 'missing' | 'agent' | 'legacy_or_alias' | 'malformed_agent';
 export type PeerKind = 'direct' | 'group' | 'channel' | 'dm';
 export declare function normalizeMainKey(value: string | undefined | null): string;
-export declare function toAgentRequestSessionKey(storeKey: string | undefined | null): string | undefined;
-export declare function toAgentStoreSessionKey(params: {
-    agentId: string;
-    requestKey: string | undefined | null;
-    mainKey?: string | undefined;
-}): string;
-export declare function resolveAgentIdFromSessionKey(sessionKey: string | undefined | null): string;
-export declare function classifySessionKeyShape(sessionKey: string | undefined | null): SessionKeyShape;
 export declare function normalizeAgentId(value: string | undefined | null): string;
 export declare function isValidAgentId(value: string | undefined | null): boolean;
 export declare function sanitizeAgentId(value: string | undefined | null): string;
-export declare function buildAgentMainSessionKey(params: {
+export declare function getConversation(conversationId: string | null | undefined): import("../session/types.js").SessionMetadata;
+export declare function resolveAgentIdFromConversationId(conversationId: string): string;
+export declare function resolveAgentMainConversationId(params: {
     agentId: string;
-    mainKey?: string | undefined;
+    mainKey?: string;
 }): string;
-export declare function buildAgentPeerSessionKey(params: {
+export declare function resolveAgentPeerConversationId(params: {
     agentId: string;
-    mainKey?: string | undefined;
+    mainKey?: string;
     channel: string;
     accountId?: string | null;
     peerKind?: PeerKind | null;
     peerId?: string | null;
+    threadId?: string;
     identityLinks?: Record<string, string[]>;
     dmScope?: 'main' | 'per-peer' | 'per-channel-peer' | 'per-account-channel-peer';
 }): string;
-export declare function buildGroupHistoryKey(params: {
-    channel: string;
-    accountId?: string | null;
-    peerKind: 'group' | 'channel';
-    peerId: string;
-}): string;
-export declare function resolveThreadSessionKeys(params: {
-    baseSessionKey: string;
-    threadId?: string | null;
-    parentSessionKey?: string;
-    useSuffix?: boolean;
-    normalizeThreadId?: (threadId: string) => string;
-}): {
-    sessionKey: string;
-    parentSessionKey?: string;
-};
-export declare function scopedHeartbeatWakeOptions<T extends object>(sessionKey: string, wakeOptions: T): T | (T & {
-    sessionKey: string;
-});
-/** Default CLI/TUI main session key. */
-export declare function defaultMainSessionKey(agentId?: string, mainKey?: string): string;
-export declare function assertAgentSessionKey(sessionKey: string): void;
-export declare function normalizeSessionKey(sessionKey: string | undefined | null): string;
+export declare function defaultMainConversationId(agentId?: string, mainKey?: string): string;
+export declare function isCronConversationId(id: string | null | undefined): boolean;
+export declare function isSubagentConversationId(id: string | null | undefined): boolean;
+export declare function assertAgentConversationId(id: string): void;

package/dist/src/routing/agent-session-key.js

@@ -1,40 +1,13 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
-import { init_string_coerce, normalizeLowercaseStringOrEmpty } from "../utils/string-coerce.js";
 import { DEFAULT_ACCOUNT_ID, init_account_id, normalizeAccountId, normalizeOptionalAccountId } from "./account-id.js";
-import { getSubagentDepth, init_session_key_utils, isAcpSessionKey, isCronSessionKey, isSubagentSessionKey, parseAgentSessionKey, parseThreadSessionSuffix } from "./session-key-utils.js";
+import { validateConversationId } from "../../packages/gateway-contract/src/conversation-identity.js";
+import { init_src } from "../../packages/gateway-contract/src/index.js";
+import { init_conversation_repository, requireConversation, resolveRoutedConversation } from "../storage/sqlite/conversation-repository.js";
+import { init_string_coerce, normalizeLowercaseStringOrEmpty } from "../utils/string-coerce.js";
 //#region src/routing/agent-session-key.ts
-function normalizeToken(value) {
-	return normalizeLowercaseStringOrEmpty(value);
-}
 function normalizeMainKey(value) {
 	return normalizeLowercaseStringOrEmpty(value) || "main";
 }
-function toAgentRequestSessionKey(storeKey) {
-	const raw = (storeKey ?? "").trim();
-	if (!raw) return;
-	return parseAgentSessionKey(raw)?.rest ?? raw;
-}
-function toAgentStoreSessionKey(params) {
-	const raw = (params.requestKey ?? "").trim();
-	const lowered = normalizeLowercaseStringOrEmpty(raw);
-	if (!raw || lowered === "main") return buildAgentMainSessionKey({
-		agentId: params.agentId,
-		mainKey: params.mainKey
-	});
-	const parsed = parseAgentSessionKey(raw);
-	if (parsed) return `agent:${parsed.agentId}:${parsed.rest}`;
-	if (lowered.startsWith("agent:")) return lowered;
-	return `agent:${normalizeAgentId(params.agentId)}:${lowered}`;
-}
-function resolveAgentIdFromSessionKey(sessionKey) {
-	return normalizeAgentId(parseAgentSessionKey(sessionKey)?.agentId ?? "main");
-}
-function classifySessionKeyShape(sessionKey) {
-	const raw = (sessionKey ?? "").trim();
-	if (!raw) return "missing";
-	if (parseAgentSessionKey(raw)) return "agent";
-	return normalizeLowercaseStringOrEmpty(raw).startsWith("agent:") ? "malformed_agent" : "legacy_or_alias";
-}
 function normalizeAgentId(value) {
 	const trimmed = (value ?? "").trim();
 	if (!trimmed) return DEFAULT_AGENT_ID;
@@ -49,107 +22,53 @@ function isValidAgentId(value) {
 function sanitizeAgentId(value) {
 	return normalizeAgentId(value);
 }
-function buildAgentMainSessionKey(params) {
-	return `agent:${normalizeAgentId(params.agentId)}:${normalizeMainKey(params.mainKey)}`;
-}
-function buildAgentPeerSessionKey(params) {
-	const rawKind = params.peerKind ?? "direct";
-	const peerKind = rawKind === "dm" ? "direct" : rawKind;
-	if (peerKind === "direct") {
-		const dmScope = params.dmScope ?? "main";
-		let peerId = (params.peerId ?? "").trim();
-		const linkedPeerId = dmScope === "main" ? null : resolveLinkedPeerId({
-			identityLinks: params.identityLinks,
-			channel: params.channel,
-			peerId
-		});
-		if (linkedPeerId) peerId = linkedPeerId;
-		peerId = normalizeLowercaseStringOrEmpty(peerId);
-		if (dmScope === "per-account-channel-peer" && peerId) {
-			const channel = normalizeLowercaseStringOrEmpty(params.channel) || "unknown";
-			const accountId = normalizeAccountId(params.accountId);
-			return `agent:${normalizeAgentId(params.agentId)}:${channel}:${accountId}:direct:${peerId}`;
-		}
-		if (dmScope === "per-channel-peer" && peerId) {
-			const channel = normalizeLowercaseStringOrEmpty(params.channel) || "unknown";
-			return `agent:${normalizeAgentId(params.agentId)}:${channel}:direct:${peerId}`;
-		}
-		if (dmScope === "per-peer" && peerId) return `agent:${normalizeAgentId(params.agentId)}:direct:${peerId}`;
-		return buildAgentMainSessionKey({
-			agentId: params.agentId,
-			mainKey: params.mainKey
-		});
-	}
-	const channel = normalizeLowercaseStringOrEmpty(params.channel) || "unknown";
-	const peerId = normalizeLowercaseStringOrEmpty(params.peerId) || "unknown";
-	return `agent:${normalizeAgentId(params.agentId)}:${channel}:${peerKind}:${peerId}`;
+function getConversation(conversationId) {
+	return conversationId ? requireConversation(conversationId) : null;
 }
-function resolveLinkedPeerId(params) {
-	const identityLinks = params.identityLinks;
-	if (!identityLinks) return null;
-	const peerId = params.peerId.trim();
-	if (!peerId) return null;
-	const candidates = /* @__PURE__ */ new Set();
-	const rawCandidate = normalizeToken(peerId);
-	if (rawCandidate) candidates.add(rawCandidate);
-	const channel = normalizeToken(params.channel);
-	if (channel) {
-		const scopedCandidate = normalizeToken(`${channel}:${peerId}`);
-		if (scopedCandidate) candidates.add(scopedCandidate);
-	}
-	if (candidates.size === 0) return null;
-	for (const [canonical, ids] of Object.entries(identityLinks)) {
-		const canonicalName = canonical.trim();
-		if (!canonicalName || !Array.isArray(ids)) continue;
-		for (const id of ids) {
-			const normalized = normalizeToken(id);
-			if (normalized && candidates.has(normalized)) return canonicalName;
-		}
-	}
-	return null;
+function resolveAgentIdFromConversationId(conversationId) {
+	return requireConversation(conversationId).agentId;
 }
-function buildGroupHistoryKey(params) {
-	const channel = normalizeToken(params.channel) || "unknown";
-	const accountId = normalizeAccountId(params.accountId);
-	const peerId = normalizeLowercaseStringOrEmpty(params.peerId) || "unknown";
-	return `${channel}:${accountId}:${params.peerKind}:${peerId}`;
-}
-function resolveThreadSessionKeys(params) {
-	const threadId = (params.threadId ?? "").trim();
-	if (!threadId) return {
-		sessionKey: params.baseSessionKey,
-		parentSessionKey: void 0
-	};
-	const normalizedThread = params.normalizeThreadId?.(threadId) ?? normalizeLowercaseStringOrEmpty(threadId);
-	return {
-		sessionKey: params.useSuffix ?? true ? `${params.baseSessionKey}:thread:${normalizedThread}` : params.baseSessionKey,
-		parentSessionKey: params.parentSessionKey
-	};
+function resolveAgentMainConversationId(params) {
+	return resolveRoutedConversation({
+		agentId: params.agentId,
+		source: "cli",
+		peerKind: "direct",
+		peerId: params.mainKey || "main",
+		dmScope: "main",
+		mainKey: params.mainKey
+	});
 }
-function scopedHeartbeatWakeOptions(sessionKey, wakeOptions) {
-	return parseAgentSessionKey(sessionKey) ? {
-		...wakeOptions,
-		sessionKey
-	} : wakeOptions;
+function resolveAgentPeerConversationId(params) {
+	return resolveRoutedConversation({
+		...params,
+		source: params.channel,
+		accountId: params.accountId ?? void 0,
+		peerKind: params.peerKind ?? "direct",
+		peerId: params.peerId ?? "",
+		dmScope: params.dmScope ?? "main"
+	});
 }
-/** Default CLI/TUI main session key. */
-function defaultMainSessionKey(agentId, mainKey) {
-	return buildAgentMainSessionKey({
-		agentId: agentId ?? "main",
+function defaultMainConversationId(agentId = DEFAULT_AGENT_ID, mainKey) {
+	return resolveAgentMainConversationId({
+		agentId,
 		mainKey
 	});
 }
-function assertAgentSessionKey(sessionKey) {
-	if (!parseAgentSessionKey(sessionKey)) throw new Error(`Invalid agent session key (expected agent:{id}:{rest}): ${sessionKey}`);
+function isCronConversationId(id) {
+	return !!id && requireConversation(id).sessionType === "cron";
+}
+function isSubagentConversationId(id) {
+	return !!id && requireConversation(id).sessionType === "workflow-subagent";
 }
-function normalizeSessionKey(sessionKey) {
-	return (sessionKey ?? "").trim().toLowerCase();
+function assertAgentConversationId(id) {
+	validateConversationId(id);
 }
 var DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, VALID_ID_RE, INVALID_CHARS_RE, LEADING_DASH_RE, TRAILING_DASH_RE;
 var init_agent_session_key = __esmMin((() => {
+	init_src();
+	init_conversation_repository();
 	init_string_coerce();
 	init_account_id();
-	init_session_key_utils();
 	DEFAULT_AGENT_ID = "main";
 	DEFAULT_MAIN_KEY = "main";
 	VALID_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
@@ -159,4 +78,4 @@ var init_agent_session_key = __esmMin((() => {
 }));
 //#endregion
 init_agent_session_key();
-export { DEFAULT_ACCOUNT_ID, DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, assertAgentSessionKey, buildAgentMainSessionKey, buildAgentPeerSessionKey, buildGroupHistoryKey, classifySessionKeyShape, defaultMainSessionKey, getSubagentDepth, init_agent_session_key, isAcpSessionKey, isCronSessionKey, isSubagentSessionKey, isValidAgentId, normalizeAccountId, normalizeAgentId, normalizeMainKey, normalizeOptionalAccountId, normalizeSessionKey, parseAgentSessionKey, parseThreadSessionSuffix, resolveAgentIdFromSessionKey, resolveThreadSessionKeys, sanitizeAgentId, scopedHeartbeatWakeOptions, toAgentRequestSessionKey, toAgentStoreSessionKey };
+export { DEFAULT_ACCOUNT_ID, DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, assertAgentConversationId, defaultMainConversationId, getConversation, init_agent_session_key, isCronConversationId, isSubagentConversationId, isValidAgentId, normalizeAccountId, normalizeAgentId, normalizeMainKey, normalizeOptionalAccountId, resolveAgentIdFromConversationId, resolveAgentMainConversationId, resolveAgentPeerConversationId, sanitizeAgentId };

package/dist/src/routing/conversation-route.d.ts

@@ -0,0 +1,28 @@
+export type DirectConversationScope = 'main' | 'per-peer' | 'per-channel-peer' | 'per-account-channel-peer';
+export interface ConversationRouteInput {
+    agentId: string;
+    source: string;
+    accountId?: string;
+    peerKind: string;
+    peerId: string;
+    threadId?: string | null;
+    scopeId?: string | null;
+    mainKey?: string;
+    dmScope?: DirectConversationScope;
+    identityLinks?: Record<string, string[]>;
+}
+export interface ConversationRoute {
+    agentId: string;
+    scope: DirectConversationScope | 'group';
+    channel: string;
+    accountId: string;
+    peerKind: string;
+    peerId: string;
+    threadId: string;
+    scopeId: string;
+}
+export declare function resolveLinkedConversationPeer(peerId: string, source: string, links?: Record<string, string[]>): string;
+/** Computes routing equivalence, independently of conversation identity or storage. */
+export declare function resolveConversationRoute(input: ConversationRouteInput): ConversationRoute;
+/** A collision-free lookup tuple; never a public conversation identifier. */
+export declare function conversationRouteKey(route: ConversationRoute): string;

package/dist/src/routing/conversation-route.js

@@ -0,0 +1,50 @@
+import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+import { init_account_id, normalizeAccountId } from "./account-id.js";
+//#region src/routing/conversation-route.ts
+function normalized(value) {
+	return value?.trim().toLowerCase() ?? "";
+}
+function resolveLinkedConversationPeer(peerId, source, links) {
+	const peer = normalized(peerId);
+	const candidates = new Set([peer, `${normalized(source)}:${peer}`]);
+	for (const [canonical, aliases] of Object.entries(links ?? {})) if (canonical.trim() && aliases.some((alias) => candidates.has(normalized(alias)))) return normalized(canonical);
+	return peer;
+}
+/** Computes routing equivalence, independently of conversation identity or storage. */
+function resolveConversationRoute(input) {
+	const agentId = normalized(input.agentId);
+	if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(agentId)) throw new Error("Invalid conversation agent ID");
+	const direct = input.peerKind === "direct" || input.peerKind === "dm";
+	const scope = direct ? input.dmScope ?? "per-account-channel-peer" : "group";
+	const peer = scope === "main" ? normalized(input.mainKey) || "main" : direct ? resolveLinkedConversationPeer(input.peerId, input.source, input.identityLinks) : normalized(input.peerId);
+	if (!peer) throw new Error("Conversation route requires a peer ID");
+	return {
+		agentId,
+		scope,
+		channel: scope === "main" || scope === "per-peer" ? "" : normalized(input.source) || "unknown",
+		accountId: scope === "per-account-channel-peer" ? normalizeAccountId(input.accountId) : "",
+		peerKind: direct ? "direct" : normalized(input.peerKind),
+		peerId: peer,
+		threadId: normalized(input.threadId),
+		scopeId: input.scopeId ? normalized(input.scopeId).replace(/[^a-z0-9_-]+/g, "-").slice(0, 64) || "default" : ""
+	};
+}
+/** A collision-free lookup tuple; never a public conversation identifier. */
+function conversationRouteKey(route) {
+	return JSON.stringify([
+		route.agentId,
+		route.scope,
+		route.channel,
+		route.accountId,
+		route.peerKind,
+		route.peerId,
+		route.threadId,
+		route.scopeId
+	]);
+}
+var init_conversation_route = __esmMin((() => {
+	init_account_id();
+}));
+//#endregion
+init_conversation_route();
+export { conversationRouteKey, init_conversation_route, resolveConversationRoute, resolveLinkedConversationPeer };

package/dist/src/routing/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Session key helpers, binding rules, and route resolution.
  */
-export { buildSessionKey, parseSessionKey, sanitizeSegment, isValidSegment, isSubagentSessionKey, isCronSessionKey, getSubagentDepth, buildSubagentSessionKey, getParentSessionKey, normalizeSessionKey, buildAgentMainSessionKey, buildAgentPeerSessionKey, defaultMainSessionKey, parseAgentSessionKey, resolveAgentIdFromSessionKey, toAgentStoreSessionKey, assertAgentSessionKey, normalizeAgentId, normalizeMainKey, DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, type BuildSessionKeyParams, type ParsedSessionKey, } from './session-key.js';
+export { resolveConversationId, getConversationRouting, sanitizeSegment, isValidSegment, isSubagentConversationId, isCronConversationId, getParentConversationId, normalizeConversationId, resolveAgentMainConversationId, resolveAgentPeerConversationId, defaultMainConversationId, getConversation, resolveAgentIdFromConversationId, assertAgentConversationId, normalizeAgentId, normalizeMainKey, DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, type BuildConversationIdParams, } from './session-key.js';
 export { normalizeAccountId, normalizeOptionalAccountId, isValidAccountId, sanitizeAccountId, DEFAULT_ACCOUNT_ID, } from './account-id.js';
 export { globMatch, matchesBinding, parseBindingRules, parseBindingRule, resolveRoute as resolveBindingRoute, type BindingMatch, type BindingRule, type RouteInput, type RouteResult, } from './bindings.js';
-export { applyIdentityLinks, getDefaultAgentId, agentExists, pickFirstExistingAgentId, buildRouteSessionKey, deriveLastRoutePolicy, resolveRoute, resolveRouteFromSessionKey, type IdentityLinks, type SessionConfig, type AgentConfig, type RoutingConfig, type ResolveRouteInput, type ResolveRouteResult, type RouteContext, } from './resolve-route.js';
+export { applyIdentityLinks, getDefaultAgentId, agentExists, pickFirstExistingAgentId, buildRouteConversationId, resolveRoute, resolveRouteFromConversationId, type IdentityLinks, type SessionConfig, type AgentConfig, type RoutingConfig, type ResolveRouteInput, type ResolveRouteResult, type RouteContext, } from './resolve-route.js';

package/dist/src/routing/index.js

@@ -1,13 +1,13 @@
 import { DEFAULT_ACCOUNT_ID, init_account_id, isValidAccountId, normalizeAccountId, normalizeOptionalAccountId, sanitizeAccountId } from "./account-id.js";
-import { getSubagentDepth, isCronSessionKey, isSubagentSessionKey, parseAgentSessionKey } from "./session-key-utils.js";
-import { DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, assertAgentSessionKey, buildAgentMainSessionKey, buildAgentPeerSessionKey, defaultMainSessionKey, normalizeAgentId, normalizeMainKey, normalizeSessionKey, resolveAgentIdFromSessionKey, toAgentStoreSessionKey } from "./agent-session-key.js";
-import { buildSessionKey, buildSubagentSessionKey, getParentSessionKey, init_session_key, isValidSegment, parseSessionKey, sanitizeSegment } from "./session-key.js";
+import { getConversationRouting } from "../storage/sqlite/conversation-repository.js";
+import { DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, assertAgentConversationId, defaultMainConversationId, getConversation, isCronConversationId, isSubagentConversationId, normalizeAgentId, normalizeMainKey, resolveAgentIdFromConversationId, resolveAgentMainConversationId, resolveAgentPeerConversationId } from "./agent-session-key.js";
+import { getParentConversationId, init_session_key, isValidSegment, normalizeConversationId, resolveConversationId, sanitizeSegment } from "./session-key.js";
 import { globMatch, init_bindings, matchesBinding, parseBindingRule, parseBindingRules, resolveRoute } from "./bindings.js";
-import { agentExists, applyIdentityLinks, buildRouteSessionKey, deriveLastRoutePolicy, getDefaultAgentId, init_resolve_route, pickFirstExistingAgentId, resolveRoute as resolveRoute$1, resolveRouteFromSessionKey } from "./resolve-route.js";
+import { agentExists, applyIdentityLinks, buildRouteConversationId, getDefaultAgentId, init_resolve_route, pickFirstExistingAgentId, resolveRoute as resolveRoute$1, resolveRouteFromConversationId } from "./resolve-route.js";
 //#region src/routing/index.ts
 init_session_key();
 init_account_id();
 init_bindings();
 init_resolve_route();
 //#endregion
-export { DEFAULT_ACCOUNT_ID, DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, agentExists, applyIdentityLinks, assertAgentSessionKey, buildAgentMainSessionKey, buildAgentPeerSessionKey, buildRouteSessionKey, buildSessionKey, buildSubagentSessionKey, defaultMainSessionKey, deriveLastRoutePolicy, getDefaultAgentId, getParentSessionKey, getSubagentDepth, globMatch, isCronSessionKey, isSubagentSessionKey, isValidAccountId, isValidSegment, matchesBinding, normalizeAccountId, normalizeAgentId, normalizeMainKey, normalizeOptionalAccountId, normalizeSessionKey, parseAgentSessionKey, parseBindingRule, parseBindingRules, parseSessionKey, pickFirstExistingAgentId, resolveAgentIdFromSessionKey, resolveRoute as resolveBindingRoute, resolveRoute$1 as resolveRoute, resolveRouteFromSessionKey, sanitizeAccountId, sanitizeSegment, toAgentStoreSessionKey };
+export { DEFAULT_ACCOUNT_ID, DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, agentExists, applyIdentityLinks, assertAgentConversationId, buildRouteConversationId, defaultMainConversationId, getConversation, getConversationRouting, getDefaultAgentId, getParentConversationId, globMatch, isCronConversationId, isSubagentConversationId, isValidAccountId, isValidSegment, matchesBinding, normalizeAccountId, normalizeAgentId, normalizeConversationId, normalizeMainKey, normalizeOptionalAccountId, parseBindingRule, parseBindingRules, pickFirstExistingAgentId, resolveAgentIdFromConversationId, resolveAgentMainConversationId, resolveAgentPeerConversationId, resolveRoute as resolveBindingRoute, resolveConversationId, resolveRoute$1 as resolveRoute, resolveRouteFromConversationId, sanitizeAccountId, sanitizeSegment };

package/dist/src/routing/resolve-route.d.ts

@@ -78,9 +78,8 @@ export interface ResolveRouteInput extends RouteInput {
  */
 export interface ResolveRouteResult extends RouteResult {
     /** Active session key for this turn */
-    sessionKey: string;
+    conversationId: string;
     /** Main session key (DM merge target) */
-    mainSessionKey: string;
     /** Whether routing used the main or a per-session key */
     lastRoutePolicy: 'main' | 'session';
 }
@@ -101,13 +100,9 @@ export declare function agentExists(agentId: string, config: RoutingConfig): boo
  */
 export declare function pickFirstExistingAgentId(agentId: string, config: RoutingConfig): string;
 /**
- * Thin wrapper around `buildSessionKey` for route inputs.
+ * Thin wrapper around `resolveConversationId` for route inputs.
  */
-export declare function buildRouteSessionKey(agentId: string, channel: string, accountId: string, peerKind: string, peerId: string, threadId?: string | null, scopeId?: string | null): string;
-/**
- * Map session vs main key to policy label.
- */
-export declare function deriveLastRoutePolicy(sessionKey: string, mainSessionKey: string): 'main' | 'session';
+export declare function buildRouteConversationId(agentId: string, channel: string, accountId: string, peerKind: string, peerId: string, threadId?: string | null, scopeId?: string | null): string;
 /**
  * Resolve agent and session keys from channel context and config.
  */
@@ -115,7 +110,7 @@ export declare function resolveRoute(input: ResolveRouteInput): ResolveRouteResu
 /**
  * Parse basic routing fields from a session key string.
  */
-export declare function resolveRouteFromSessionKey(sessionKey: string, _config: RoutingConfig): {
+export declare function resolveRouteFromConversationId(conversationId: string, _config: RoutingConfig): {
     agentId: string;
     source: string;
     accountId: string;