@xopcai/xopc 0.0.285 → 0.0.291

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;

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

@@ -1,8 +1,9 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
 import { init_account_id, normalizeAccountId } from "./account-id.js";
-import { buildAgentMainSessionKey, buildAgentPeerSessionKey, init_agent_session_key, normalizeSessionKey } from "./agent-session-key.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../agent/agent-scope.js";
-import { buildSessionKey, init_session_key, parseSessionKey } from "./session-key.js";
+import { getConversationRouting } from "../storage/sqlite/conversation-repository.js";
+import { init_agent_session_key, resolveAgentPeerConversationId } from "./agent-session-key.js";
+import { init_session_key, resolveConversationId } from "./session-key.js";
 import { init_bindings, parseBindingRules, resolveRoute as resolveRoute$1 } from "./bindings.js";
 //#region src/routing/resolve-route.ts
 /**
@@ -47,10 +48,10 @@ function pickFirstExistingAgentId(agentId, config) {
 	return getDefaultAgentId(config);
 }
 /**
-* Thin wrapper around `buildSessionKey` for route inputs.
+* Thin wrapper around `resolveConversationId` for route inputs.
 */
-function buildRouteSessionKey(agentId, channel, accountId, peerKind, peerId, threadId, scopeId) {
-	return buildSessionKey({
+function buildRouteConversationId(agentId, channel, accountId, peerKind, peerId, threadId, scopeId) {
+	return resolveConversationId({
 		agentId,
 		source: channel,
 		accountId,
@@ -62,12 +63,6 @@ function buildRouteSessionKey(agentId, channel, accountId, peerKind, peerId, thr
 	});
 }
 /**
-* Map session vs main key to policy label.
-*/
-function deriveLastRoutePolicy(sessionKey, mainSessionKey) {
-	return sessionKey === mainSessionKey ? "main" : "session";
-}
-/**
 * Resolve agent and session keys from channel context and config.
 */
 function resolveRoute(input) {
@@ -89,62 +84,27 @@ function resolveRoute(input) {
 	}, rules, getDefaultAgentId(config));
 	const agentId = pickFirstExistingAgentId(bindingResult.agentId, config);
 	const dmScope = config.session?.dmScope ?? "main";
-	let sessionKey;
-	let mainSessionKey;
-	const identityLinks = config.session?.identityLinks;
-	const mainKey = void 0;
-	if (peerKind === "dm" || peerKind === "direct") {
-		mainSessionKey = buildAgentMainSessionKey({
-			agentId,
-			mainKey
-		});
-		sessionKey = buildAgentPeerSessionKey({
-			agentId,
-			mainKey,
-			channel,
-			accountId,
-			peerKind: "direct",
-			peerId,
-			identityLinks,
-			dmScope
-		});
-	} else {
-		const mappedKind = peerKind === "group" || peerKind === "channel" ? peerKind : peerKind;
-		sessionKey = buildAgentPeerSessionKey({
-			agentId,
-			mainKey,
-			channel,
-			accountId,
-			peerKind: mappedKind,
-			peerId,
-			identityLinks
-		});
-		mainSessionKey = buildAgentPeerSessionKey({
-			agentId,
-			mainKey,
-			channel,
-			accountId,
-			peerKind: mappedKind,
-			peerId: "main",
-			identityLinks
-		});
-	}
-	if (threadId && !sessionKey.includes(":thread:")) sessionKey = `${sessionKey}:thread:${threadId.toLowerCase()}`;
-	sessionKey = normalizeSessionKey(sessionKey);
-	mainSessionKey = normalizeSessionKey(mainSessionKey);
+	const conversationId = resolveAgentPeerConversationId({
+		agentId,
+		channel,
+		accountId,
+		peerKind,
+		peerId,
+		dmScope,
+		threadId: threadId ?? void 0
+	});
 	return {
 		...bindingResult,
 		agentId,
-		sessionKey,
-		mainSessionKey,
-		lastRoutePolicy: deriveLastRoutePolicy(sessionKey, mainSessionKey)
+		conversationId,
+		lastRoutePolicy: dmScope === "main" && (peerKind === "dm" || peerKind === "direct") ? "main" : "session"
 	};
 }
 /**
 * Parse basic routing fields from a session key string.
 */
-function resolveRouteFromSessionKey(sessionKey, _config) {
-	const parsed = parseSessionKey(sessionKey);
+function resolveRouteFromConversationId(conversationId, _config) {
+	const parsed = getConversationRouting(conversationId);
 	if (!parsed) return null;
 	return {
 		agentId: parsed.agentId,
@@ -163,4 +123,4 @@ var init_resolve_route = __esmMin((() => {
 }));
 //#endregion
 init_resolve_route();
-export { agentExists, applyIdentityLinks, buildRouteSessionKey, deriveLastRoutePolicy, getDefaultAgentId, init_resolve_route, pickFirstExistingAgentId, resolveRoute, resolveRouteFromSessionKey };
+export { agentExists, applyIdentityLinks, buildRouteConversationId, getDefaultAgentId, init_resolve_route, pickFirstExistingAgentId, resolveRoute, resolveRouteFromConversationId };

package/dist/src/routing/resolve-tui-session-key.d.ts

@@ -1,30 +1,22 @@
 import type { Config } from '../config/schema.js';
-export type SessionScope = 'per-sender' | 'global';
 export declare function resolveDefaultTuiAgentId(cfg: Config): string;
-export declare function resolveTuiSessionKey(params: {
+export declare function resolveTuiConversationId(params: {
     raw?: string;
-    sessionScope: SessionScope;
-    currentAgentId: string;
-    sessionMainKey: string;
 }): string;
 export declare function resolveInitialTuiAgentId(params: {
     cfg: Config;
     fallbackAgentId: string;
     explicitAgentId?: string;
-    initialSessionInput?: string;
     cwd?: string;
 }): string;
-export declare function createDefaultTuiSessionKeySuffix(): string;
-/** Resolve TUI startup session key from CLI options and config. */
-export declare function resolveTuiStartupSessionKey(params: {
+/** Resolve TUI startup conversation identity and initial agent from CLI options and config. */
+export declare function resolveTuiStartupConversationId(params: {
     cfg: Config;
     sessionOption?: string;
     agentOption?: string;
     cwd?: string;
-    createSessionKeySuffix?: () => string;
+    createId?: () => string;
 }): {
-    sessionKey: string;
+    conversationId: string;
     agentId: string;
-    sessionScope: SessionScope;
-    sessionMainKey: string;
 };

package/dist/src/routing/resolve-tui-session-key.js

@@ -1,12 +1,12 @@
-import { init_string_coerce, normalizeLowercaseStringOrEmpty } from "../utils/string-coerce.js";
-import { parseAgentSessionKey } from "./session-key-utils.js";
-import { buildAgentMainSessionKey, init_agent_session_key, normalizeAgentId, normalizeMainKey } from "./agent-session-key.js";
+import { validateConversationId } from "../../packages/gateway-contract/src/conversation-identity.js";
+import { init_src } from "../../packages/gateway-contract/src/index.js";
 import { init_agent_scope, listAgentEntries, resolveAgentIdByWorkspacePath, resolveDefaultAgentId } from "../agent/agent-scope.js";
+import { init_agent_session_key, normalizeAgentId } from "./agent-session-key.js";
 import { randomUUID } from "node:crypto";
 //#region src/routing/resolve-tui-session-key.ts
+init_src();
 init_agent_scope();
 init_agent_session_key();
-init_string_coerce();
 function agentExists(cfg, agentId) {
 	const id = normalizeAgentId(agentId);
 	return listAgentEntries(cfg).some((entry) => entry.enabled !== false && normalizeAgentId(entry.id) === id);
@@ -16,53 +16,28 @@ function resolveDefaultTuiAgentId(cfg) {
 	if (configured && agentExists(cfg, configured)) return normalizeAgentId(configured);
 	return resolveDefaultAgentId(cfg);
 }
-function resolveTuiSessionKey(params) {
-	const trimmed = (params.raw ?? "").trim();
-	if (!trimmed) {
-		if (params.sessionScope === "global") return "global";
-		return buildAgentMainSessionKey({
-			agentId: params.currentAgentId,
-			mainKey: params.sessionMainKey
-		});
-	}
-	if (trimmed === "global" || trimmed === "unknown") return trimmed;
-	if (trimmed.startsWith("agent:")) return normalizeLowercaseStringOrEmpty(trimmed);
-	return `agent:${params.currentAgentId}:${normalizeLowercaseStringOrEmpty(trimmed)}`;
+function resolveTuiConversationId(params) {
+	return validateConversationId(params.raw?.trim() || randomUUID());
 }
 function resolveInitialTuiAgentId(params) {
-	const parsed = parseAgentSessionKey((params.initialSessionInput ?? "").trim());
-	if (parsed?.agentId) return normalizeAgentId(parsed.agentId);
 	if (params.explicitAgentId?.trim()) return normalizeAgentId(params.explicitAgentId);
 	const inferredFromWorkspace = resolveAgentIdByWorkspacePath(params.cfg, params.cwd ?? process.cwd());
 	if (inferredFromWorkspace) return inferredFromWorkspace;
 	return normalizeAgentId(params.fallbackAgentId);
 }
-function createDefaultTuiSessionKeySuffix() {
-	return `tui-${randomUUID()}`;
-}
-/** Resolve TUI startup session key from CLI options and config. */
-function resolveTuiStartupSessionKey(params) {
-	const sessionScope = params.cfg.session?.scope ?? "per-sender";
-	const sessionMainKey = normalizeMainKey(params.cfg.session?.mainKey);
+/** Resolve TUI startup conversation identity and initial agent from CLI options and config. */
+function resolveTuiStartupConversationId(params) {
 	const sessionOption = (params.sessionOption ?? "").trim();
 	const agentId = resolveInitialTuiAgentId({
 		cfg: params.cfg,
 		fallbackAgentId: resolveDefaultTuiAgentId(params.cfg),
 		explicitAgentId: params.agentOption,
-		initialSessionInput: sessionOption,
 		cwd: params.cwd ?? process.cwd()
 	});
 	return {
-		sessionKey: resolveTuiSessionKey({
-			raw: sessionOption || (params.createSessionKeySuffix ?? createDefaultTuiSessionKeySuffix)(),
-			sessionScope,
-			currentAgentId: agentId,
-			sessionMainKey
-		}),
-		agentId,
-		sessionScope,
-		sessionMainKey
+		conversationId: resolveTuiConversationId({ raw: sessionOption || (params.createId ?? randomUUID)() }),
+		agentId
 	};
 }
 //#endregion
-export { createDefaultTuiSessionKeySuffix, resolveDefaultTuiAgentId, resolveInitialTuiAgentId, resolveTuiSessionKey, resolveTuiStartupSessionKey };
+export { resolveDefaultTuiAgentId, resolveInitialTuiAgentId, resolveTuiConversationId, resolveTuiStartupConversationId };

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

@@ -1,44 +1,11 @@
-/**
- * Session key parsing helpers for `agent:{agentId}:{rest}` keys.
- *
- * Re-exports the OpenClaw-aligned builder/parser surface from agent-session-key.ts.
- */
-import { defaultMainSessionKey } from './agent-session-key.js';
+import type { ConversationRouteInput } from './conversation-route.js';
 export * from './agent-session-key.js';
-export * from './session-key-utils.js';
+export { getConversationRouting } from '../storage/sqlite/conversation-repository.js';
 export declare function sanitizeSegment(value: string | undefined | null, options?: {
     allowLeadingDash?: boolean;
 }): string;
 export declare function isValidSegment(value: string | undefined | null): boolean;
-/** Structured view of an agent session key rest segment. */
-export interface ParsedSessionKey {
-    agentId: string;
-    source: string;
-    accountId: string;
-    peerKind: string;
-    peerId: string;
-    threadId?: string;
-    scopeId?: string;
-}
-export interface BuildSessionKeyParams {
-    agentId: string;
-    source: string;
-    accountId: string;
-    peerKind: string;
-    peerId: string;
-    threadId?: string | null;
-    scopeId?: string | null;
-    mainKey?: string;
-    dmScope?: 'main' | 'per-peer' | 'per-channel-peer' | 'per-account-channel-peer';
-    identityLinks?: Record<string, string[]>;
-}
-/** Build an OpenClaw-style agent session key from routing segments. */
-export declare function buildSessionKey(params: BuildSessionKeyParams): string;
-/** Parse `agent:{agentId}:{rest}` into routing segments. Returns null for invalid keys. */
-export declare function parseSessionKey(sessionKey: string | undefined | null): ParsedSessionKey | null;
-export interface BuildSubagentSessionKeyParams extends BuildSessionKeyParams {
-    parentSessionKey: string;
-}
-export declare function buildSubagentSessionKey(params: BuildSubagentSessionKeyParams): string;
-export declare function getParentSessionKey(sessionKey: string | undefined | null): string | null;
-export { defaultMainSessionKey };
+export type BuildConversationIdParams = ConversationRouteInput;
+export declare function resolveConversationId(params: ConversationRouteInput): string;
+export declare function getParentConversationId(conversationId: string | undefined | null): string | null;
+export declare function normalizeConversationId(conversationId: string): string;