export const DEFAULT_AGENT_ID = "main"; export const DEFAULT_MAIN_KEY = "main"; export const DEFAULT_ACCOUNT_ID = "default"; function normalizeToken(value: string | undefined | null): string { return (value ?? "").trim().toLowerCase(); } export function normalizeMainKey(value: string | undefined | null): string { const trimmed = (value ?? "").trim(); return trimmed ? trimmed : DEFAULT_MAIN_KEY; } export type ParsedAgentSessionKey = { agentId: string; rest: string; }; export function resolveAgentIdFromSessionKey(sessionKey: string | undefined | null): string { const parsed = parseAgentSessionKey(sessionKey); return normalizeAgentId(parsed?.agentId ?? DEFAULT_AGENT_ID); } export function normalizeAgentId(value: string | undefined | null): string { const trimmed = (value ?? "").trim(); if (!trimmed) return DEFAULT_AGENT_ID; // Keep it path-safe + shell-friendly. if (/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(trimmed)) return trimmed; // Best-effort fallback: collapse invalid characters to "-" return ( trimmed .toLowerCase() .replace(/[^a-z0-9_-]+/g, "-") .replace(/^-+/, "") .replace(/-+$/, "") .slice(0, 64) || DEFAULT_AGENT_ID ); } export function normalizeAccountId(value: string | undefined | null): string { const trimmed = (value ?? "").trim(); if (!trimmed) return DEFAULT_ACCOUNT_ID; if (/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(trimmed)) return trimmed; return ( trimmed .toLowerCase() .replace(/[^a-z0-9_-]+/g, "-") .replace(/^-+/, "") .replace(/-+$/, "") .slice(0, 64) || DEFAULT_ACCOUNT_ID ); } export function parseAgentSessionKey( sessionKey: string | undefined | null, ): ParsedAgentSessionKey | null { const raw = (sessionKey ?? "").trim(); if (!raw) return null; const parts = raw.split(":").filter(Boolean); if (parts.length < 3) return null; if (parts[0] !== "agent") return null; const agentId = parts[1]?.trim(); const rest = parts.slice(2).join(":"); if (!agentId || !rest) return null; return { agentId, rest }; } export function isSubagentSessionKey(sessionKey: string | undefined | null): boolean { const raw = (sessionKey ?? "").trim(); if (!raw) return false; if (raw.toLowerCase().startsWith("subagent:")) return true; const parsed = parseAgentSessionKey(raw); return Boolean((parsed?.rest ?? "").toLowerCase().startsWith("subagent:")); } export function buildAgentMainSessionKey(params: { agentId: string; mainKey?: string | undefined; }): string { const agentId = normalizeAgentId(params.agentId); const mainKey = normalizeMainKey(params.mainKey); return `agent:${agentId}:${mainKey}`; } export function buildAgentPeerSessionKey(params: { agentId: string; mainKey?: string | undefined; channel: string; peerKind?: "dm" | "group" | "channel" | null; peerId?: string | null; identityLinks?: Record; /** DM session scope. */ dmScope?: "main" | "per-peer" | "per-channel-peer"; }): string { const peerKind = params.peerKind ?? "dm"; if (peerKind === "dm") { 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; if (dmScope === "per-channel-peer" && peerId) { const channel = (params.channel ?? "").trim().toLowerCase() || "unknown"; return `agent:${normalizeAgentId(params.agentId)}:${channel}:dm:${peerId}`; } if (dmScope === "per-peer" && peerId) { return `agent:${normalizeAgentId(params.agentId)}:dm:${peerId}`; } return buildAgentMainSessionKey({ agentId: params.agentId, mainKey: params.mainKey, }); } const channel = (params.channel ?? "").trim().toLowerCase() || "unknown"; const peerId = (params.peerId ?? "").trim() || "unknown"; return `agent:${normalizeAgentId(params.agentId)}:${channel}:${peerKind}:${peerId}`; } function resolveLinkedPeerId(params: { identityLinks?: Record; channel: string; peerId: string; }): string | null { const identityLinks = params.identityLinks; if (!identityLinks) return null; const peerId = params.peerId.trim(); if (!peerId) return null; const candidates = 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) continue; if (!Array.isArray(ids)) continue; for (const id of ids) { const normalized = normalizeToken(id); if (normalized && candidates.has(normalized)) { return canonicalName; } } } return null; } export function buildGroupHistoryKey(params: { channel: string; accountId?: string | null; peerKind: "group" | "channel"; peerId: string; }): string { const channel = normalizeToken(params.channel) || "unknown"; const accountId = normalizeAccountId(params.accountId); const peerId = params.peerId.trim() || "unknown"; return `${channel}:${accountId}:${params.peerKind}:${peerId}`; } export function resolveThreadSessionKeys(params: { baseSessionKey: string; threadId?: string | null; parentSessionKey?: string; useSuffix?: boolean; }): { sessionKey: string; parentSessionKey?: string } { const threadId = (params.threadId ?? "").trim(); if (!threadId) { return { sessionKey: params.baseSessionKey, parentSessionKey: undefined }; } const useSuffix = params.useSuffix ?? true; const sessionKey = useSuffix ? `${params.baseSessionKey}:thread:${threadId}` : params.baseSessionKey; return { sessionKey, parentSessionKey: params.parentSessionKey }; }