@xopcai/xopc 0.0.85 → 0.0.87

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

@@ -0,0 +1,92 @@
+import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+import { init_string_coerce, normalizeLowercaseStringOrEmpty, normalizeOptionalLowercaseString, normalizeOptionalString } from "../utils/string-coerce.js";
+//#region src/routing/session-key-utils.ts
+/** Parse `agent:{agentId}:{rest}` session keys (OpenClaw canonical form). */
+function parseAgentSessionKey(sessionKey) {
+	const raw = normalizeOptionalLowercaseString(sessionKey);
+	if (!raw) return null;
+	const parts = raw.split(":").filter(Boolean);
+	if (parts.length < 3) return null;
+	if (parts[0] !== "agent") return null;
+	const agentId = normalizeOptionalString(parts[1]);
+	const rest = parts.slice(2).join(":");
+	if (!agentId || !rest) return null;
+	return {
+		agentId: agentId.toLowerCase(),
+		rest
+	};
+}
+function isCronRunSessionKey(sessionKey) {
+	const parsed = parseAgentSessionKey(sessionKey);
+	if (!parsed) return false;
+	return /^cron:[^:]+:run:[^:]+$/.test(parsed.rest);
+}
+function isCronSessionKey(sessionKey) {
+	const parsed = parseAgentSessionKey(sessionKey);
+	if (!parsed) return false;
+	return normalizeOptionalLowercaseString(parsed.rest)?.startsWith("cron:") === true;
+}
+function isSubagentSessionKey(sessionKey) {
+	const raw = normalizeOptionalString(sessionKey);
+	if (!raw) return false;
+	if (normalizeOptionalLowercaseString(raw)?.startsWith("subagent:")) return true;
+	return normalizeOptionalLowercaseString(parseAgentSessionKey(raw)?.rest)?.startsWith("subagent:") === true;
+}
+function getSubagentDepth(sessionKey) {
+	const raw = normalizeOptionalLowercaseString(sessionKey);
+	if (!raw) return 0;
+	return raw.split(":subagent:").length - 1;
+}
+function isAcpSessionKey(sessionKey) {
+	const raw = normalizeOptionalString(sessionKey);
+	if (!raw) return false;
+	if (normalizeLowercaseStringOrEmpty(raw).startsWith("acp:")) return true;
+	return normalizeOptionalLowercaseString(parseAgentSessionKey(raw)?.rest)?.startsWith("acp:") === true;
+}
+function parseThreadSessionSuffix(sessionKey) {
+	const raw = normalizeOptionalString(sessionKey);
+	if (!raw) return {
+		baseSessionKey: void 0,
+		threadId: void 0
+	};
+	const threadIndex = normalizeLowercaseStringOrEmpty(raw).lastIndexOf(":thread:");
+	return {
+		baseSessionKey: threadIndex === -1 ? raw : raw.slice(0, threadIndex),
+		threadId: normalizeOptionalString(threadIndex === -1 ? void 0 : raw.slice(threadIndex + 8))
+	};
+}
+function parseRawSessionConversationRef(sessionKey) {
+	const raw = normalizeOptionalString(sessionKey);
+	if (!raw) return null;
+	const rawParts = raw.split(":").filter(Boolean);
+	const bodyStartIndex = rawParts.length >= 3 && normalizeOptionalLowercaseString(rawParts[0]) === "agent" ? 2 : 0;
+	const parts = rawParts.slice(bodyStartIndex);
+	if (parts.length < 3) return null;
+	const channel = normalizeOptionalLowercaseString(parts[0]);
+	const kind = normalizeOptionalLowercaseString(parts[1]);
+	if (!channel || kind !== "group" && kind !== "channel") return null;
+	const rawId = normalizeOptionalString(parts.slice(2).join(":"));
+	const prefix = normalizeOptionalString(rawParts.slice(0, bodyStartIndex + 2).join(":"));
+	if (!rawId || !prefix) return null;
+	return {
+		channel,
+		kind,
+		rawId,
+		prefix
+	};
+}
+function resolveThreadParentSessionKey(sessionKey) {
+	const { baseSessionKey, threadId } = parseThreadSessionSuffix(sessionKey);
+	if (!threadId) return null;
+	const parent = normalizeOptionalString(baseSessionKey);
+	if (!parent) return null;
+	return parent;
+}
+var init_session_key_utils = __esmMin((() => {
+	init_string_coerce();
+}));
+//#endregion
+init_session_key_utils();
+export { getSubagentDepth, init_session_key_utils, isAcpSessionKey, isCronRunSessionKey, isCronSessionKey, isSubagentSessionKey, parseAgentSessionKey, parseRawSessionConversationRef, parseThreadSessionSuffix, resolveThreadParentSessionKey };
+
+//# sourceMappingURL=session-key-utils.js.map

package/dist/src/routing/session-key-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-key-utils.js","names":[],"sources":["../../../src/routing/session-key-utils.ts"],"sourcesContent":["import {\n  normalizeLowercaseStringOrEmpty,\n  normalizeOptionalLowercaseString,\n  normalizeOptionalString,\n} from '../utils/string-coerce.js';\n\nexport type ParsedAgentSessionKey = {\n  agentId: string;\n  rest: string;\n};\n\nexport type ParsedThreadSessionSuffix = {\n  baseSessionKey: string | undefined;\n  threadId: string | undefined;\n};\n\nexport type RawSessionConversationRef = {\n  channel: string;\n  kind: 'group' | 'channel';\n  rawId: string;\n  prefix: string;\n};\n\n/** Parse `agent:{agentId}:{rest}` session keys (OpenClaw canonical form). */\nexport function parseAgentSessionKey(\n  sessionKey: string | undefined | null,\n): ParsedAgentSessionKey | null {\n  const raw = normalizeOptionalLowercaseString(sessionKey);\n  if (!raw) {\n    return null;\n  }\n  const parts = raw.split(':').filter(Boolean);\n  if (parts.length < 3) {\n    return null;\n  }\n  if (parts[0] !== 'agent') {\n    return null;\n  }\n  const agentId = normalizeOptionalString(parts[1]);\n  const rest = parts.slice(2).join(':');\n  if (!agentId || !rest) {\n    return null;\n  }\n  return { agentId: agentId.toLowerCase(), rest };\n}\n\nexport function isCronRunSessionKey(sessionKey: string | undefined | null): boolean {\n  const parsed = parseAgentSessionKey(sessionKey);\n  if (!parsed) {\n    return false;\n  }\n  return /^cron:[^:]+:run:[^:]+$/.test(parsed.rest);\n}\n\nexport function isCronSessionKey(sessionKey: string | undefined | null): boolean {\n  const parsed = parseAgentSessionKey(sessionKey);\n  if (!parsed) {\n    return false;\n  }\n  return normalizeOptionalLowercaseString(parsed.rest)?.startsWith('cron:') === true;\n}\n\nexport function isSubagentSessionKey(sessionKey: string | undefined | null): boolean {\n  const raw = normalizeOptionalString(sessionKey);\n  if (!raw) {\n    return false;\n  }\n  if (normalizeOptionalLowercaseString(raw)?.startsWith('subagent:')) {\n    return true;\n  }\n  const parsed = parseAgentSessionKey(raw);\n  return normalizeOptionalLowercaseString(parsed?.rest)?.startsWith('subagent:') === true;\n}\n\nexport function getSubagentDepth(sessionKey: string | undefined | null): number {\n  const raw = normalizeOptionalLowercaseString(sessionKey);\n  if (!raw) {\n    return 0;\n  }\n  return raw.split(':subagent:').length - 1;\n}\n\nexport function isAcpSessionKey(sessionKey: string | undefined | null): boolean {\n  const raw = normalizeOptionalString(sessionKey);\n  if (!raw) {\n    return false;\n  }\n  const normalized = normalizeLowercaseStringOrEmpty(raw);\n  if (normalized.startsWith('acp:')) {\n    return true;\n  }\n  const parsed = parseAgentSessionKey(raw);\n  return normalizeOptionalLowercaseString(parsed?.rest)?.startsWith('acp:') === true;\n}\n\nexport function parseThreadSessionSuffix(\n  sessionKey: string | undefined | null,\n): ParsedThreadSessionSuffix {\n  const raw = normalizeOptionalString(sessionKey);\n  if (!raw) {\n    return { baseSessionKey: undefined, threadId: undefined };\n  }\n\n  const lowerRaw = normalizeLowercaseStringOrEmpty(raw);\n  const threadMarker = ':thread:';\n  const threadIndex = lowerRaw.lastIndexOf(threadMarker);\n  const baseSessionKey = threadIndex === -1 ? raw : raw.slice(0, threadIndex);\n  const threadIdRaw = threadIndex === -1 ? undefined : raw.slice(threadIndex + threadMarker.length);\n  const threadId = normalizeOptionalString(threadIdRaw);\n\n  return { baseSessionKey, threadId };\n}\n\nexport function parseRawSessionConversationRef(\n  sessionKey: string | undefined | null,\n): RawSessionConversationRef | null {\n  const raw = normalizeOptionalString(sessionKey);\n  if (!raw) {\n    return null;\n  }\n\n  const rawParts = raw.split(':').filter(Boolean);\n  const bodyStartIndex =\n    rawParts.length >= 3 && normalizeOptionalLowercaseString(rawParts[0]) === 'agent' ? 2 : 0;\n  const parts = rawParts.slice(bodyStartIndex);\n  if (parts.length < 3) {\n    return null;\n  }\n\n  const channel = normalizeOptionalLowercaseString(parts[0]);\n  const kind = normalizeOptionalLowercaseString(parts[1]);\n  if (!channel || (kind !== 'group' && kind !== 'channel')) {\n    return null;\n  }\n\n  const rawId = normalizeOptionalString(parts.slice(2).join(':'));\n  const prefix = normalizeOptionalString(rawParts.slice(0, bodyStartIndex + 2).join(':'));\n  if (!rawId || !prefix) {\n    return null;\n  }\n\n  return { channel, kind, rawId, prefix };\n}\n\nexport function resolveThreadParentSessionKey(\n  sessionKey: string | undefined | null,\n): string | null {\n  const { baseSessionKey, threadId } = parseThreadSessionSuffix(sessionKey);\n  if (!threadId) {\n    return null;\n  }\n  const parent = normalizeOptionalString(baseSessionKey);\n  if (!parent) {\n    return null;\n  }\n  return parent;\n}\n"],"mappings":"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"}

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

@@ -1,74 +1,44 @@
 /**
- * Session key construction and parsing.
+ * Session key parsing helpers for `agent:{agentId}:{rest}` keys.
  *
- * Format: {agentId}:{source}:{accountId}:{peerKind}:{peerId}[:thread:{threadId}][:scope:{scopeId}]
- *
- * Examples:
- * - main:telegram:acc_default:dm:123456
- * - main:discord:acc_work:channel:987654:thread:789
- * - subagent:main:abc123:telegram:acc_default:dm:123456
- */
-/**
- * Sanitize a segment to allowed chars a-z0-9_-
+ * Re-exports the OpenClaw-aligned builder/parser surface from agent-session-key.ts.
  */
+import { defaultMainSessionKey } from './agent-session-key.js';
+export * from './agent-session-key.js';
+export * from './session-key-utils.js';
 export declare function sanitizeSegment(value: string | undefined | null, options?: {
     allowLeadingDash?: boolean;
 }): string;
-/**
- * Whether the segment matches the allowed pattern and length.
- */
 export declare function isValidSegment(value: string | undefined | null): boolean;
-/**
- * Fields used to build a session key.
- */
-export interface BuildSessionKeyParams {
+/** Structured view of an agent session key rest segment. */
+export interface ParsedSessionKey {
     agentId: string;
     source: string;
     accountId: string;
     peerKind: string;
     peerId: string;
-    threadId?: string | null;
-    scopeId?: string | null;
+    threadId?: string;
+    scopeId?: string;
 }
-export declare function buildSessionKey(params: BuildSessionKeyParams): string;
-/**
- * Parsed session key components.
- */
-export interface ParsedSessionKey {
+export interface BuildSessionKeyParams {
     agentId: string;
     source: string;
     accountId: string;
     peerKind: string;
     peerId: string;
-    threadId?: string;
-    scopeId?: 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;
-/**
- * Whether the key refers to a subagent session.
- */
-export declare function isSubagentSessionKey(sessionKey: string | undefined | null): boolean;
-/**
- * Whether the key is a cron-driven session.
- */
-export declare function isCronSessionKey(sessionKey: string | undefined | null): boolean;
-/**
- * Nesting depth from repeated `subagent` prefixes in the colon-separated key.
- * e.g. `subagent:...` => 1, `subagent:subagent:...` => 2
- */
-export declare function getSubagentDepth(sessionKey: string | undefined | null): number;
-/**
- * Parameters for building a subagent session key.
- */
 export interface BuildSubagentSessionKeyParams extends BuildSessionKeyParams {
     parentSessionKey: string;
 }
 export declare function buildSubagentSessionKey(params: BuildSubagentSessionKeyParams): string;
-/**
- * Parent session key without a :thread: suffix, if any.
- */
 export declare function getParentSessionKey(sessionKey: string | undefined | null): string | null;
-/**
- * Normalize a session key (trim + lowercase).
- */
-export declare function normalizeSessionKey(sessionKey: string | undefined | null): string;
+export { defaultMainSessionKey };

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

@@ -1,8 +1,8 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId, normalizeOptionalAccountId } from "./account-id.js";
+import { getSubagentDepth, init_session_key_utils, isAcpSessionKey, isCronRunSessionKey, isCronSessionKey, isSubagentSessionKey, parseAgentSessionKey, parseRawSessionConversationRef, parseThreadSessionSuffix, resolveThreadParentSessionKey } from "./session-key-utils.js";
+import { DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, assertAgentSessionKey, buildAgentMainSessionKey, buildAgentPeerSessionKey, buildGroupHistoryKey, classifySessionKeyShape, defaultMainSessionKey, init_agent_session_key, isValidAgentId, normalizeAgentId, normalizeMainKey, normalizeSessionKey, resolveAgentIdFromSessionKey, resolveThreadSessionKeys, sanitizeAgentId, scopedHeartbeatWakeOptions, toAgentRequestSessionKey, toAgentStoreSessionKey } from "./agent-session-key.js";
 //#region src/routing/session-key.ts
-/**
-* Sanitize a segment to allowed chars a-z0-9_-
-*/
 function sanitizeSegment(value, options) {
 	const trimmed = (value ?? "").trim();
 	if (!trimmed) return "";
@@ -12,148 +12,175 @@ function sanitizeSegment(value, options) {
 	if (!cleaned) return "";
 	return cleaned.slice(0, 64);
 }
-/**
-* Whether the segment matches the allowed pattern and length.
-*/
 function isValidSegment(value) {
 	const trimmed = (value ?? "").trim();
-	if (!trimmed) return false;
-	if (trimmed.length > 64) return false;
+	if (!trimmed || trimmed.length > 64) return false;
 	return VALID_SEGMENT_RE.test(trimmed);
 }
+/** Build an OpenClaw-style agent session key from routing segments. */
 function buildSessionKey(params) {
-	const segments = [
-		sanitizeSegment(params.agentId) || "main",
-		sanitizeSegment(params.source) || "unknown",
-		sanitizeSegment(params.accountId) || "default",
-		sanitizeSegment(params.peerKind) || "unknown",
-		sanitizeSegment(params.peerId, { allowLeadingDash: true }) || "unknown"
-	];
-	if (params.threadId) segments.push("thread", sanitizeSegment(params.threadId, { allowLeadingDash: true }) || "unknown");
-	if (params.scopeId) segments.push("scope", sanitizeSegment(params.scopeId, { allowLeadingDash: true }) || "default");
-	return segments.join(":");
+	const peerKind = params.peerKind === "dm" ? "direct" : params.peerKind;
+	let key = buildAgentPeerSessionKey({
+		agentId: params.agentId,
+		mainKey: params.mainKey,
+		channel: params.source,
+		accountId: params.accountId,
+		peerKind,
+		peerId: params.peerId,
+		identityLinks: params.identityLinks,
+		dmScope: params.dmScope ?? (peerKind === "direct" ? "per-account-channel-peer" : void 0)
+	});
+	if (params.threadId) key = resolveThreadSessionKeys({
+		baseSessionKey: key,
+		threadId: params.threadId
+	}).sessionKey;
+	if (params.scopeId) key = `${key}:scope:${sanitizeSegment(params.scopeId, { allowLeadingDash: true }) || "default"}`;
+	return key;
 }
+/** Parse `agent:{agentId}:{rest}` into routing segments. Returns null for invalid keys. */
 function parseSessionKey(sessionKey) {
 	const raw = (sessionKey ?? "").trim();
 	if (!raw) return null;
-	const parts = raw.split(":").filter(Boolean);
-	/**
-	* Alternate encoding used in some installs / tests: `gateway:{agentId}:{source}:{accountId}:{peerKind}:{peerId}…`
-	* (distinct from normal `{agentId}:{source}:…` where the first segment is the agent id.)
-	*/
-	if (parts.length >= 6 && parts[0]?.toLowerCase() === "gateway") {
-		const agentId = parts[1] ?? "";
-		const source = parts[2] ?? "";
-		const accountId = parts[3] ?? "";
-		const peerKind = parts[4] ?? "";
-		const peerId = parts[5] ?? "";
-		const rest = parts.slice(6);
-		const result = {
-			agentId: agentId.toLowerCase(),
-			source: source.toLowerCase(),
-			accountId: accountId.toLowerCase(),
-			peerKind: peerKind.toLowerCase(),
-			peerId: peerId.toLowerCase()
+	const { baseSessionKey, threadId } = parseThreadSuffix(raw);
+	const agentParsed = parseAgentSessionKey(baseSessionKey);
+	if (!agentParsed) return null;
+	const scopeParts = parseScopeSuffix(agentParsed.rest);
+	const rest = scopeParts.rest;
+	const scopeId = scopeParts.scopeId;
+	const mainKey = normalizeMainKey(void 0);
+	if (rest === mainKey) return {
+		agentId: agentParsed.agentId,
+		source: "cli",
+		accountId: "default",
+		peerKind: "direct",
+		peerId: mainKey,
+		threadId,
+		scopeId
+	};
+	if (rest.startsWith("subagent:")) return parseSubagentRest(agentParsed.agentId, rest, threadId, scopeId);
+	if (rest.startsWith("cron:")) {
+		const parts = rest.split(":");
+		return {
+			agentId: agentParsed.agentId,
+			source: "cron",
+			accountId: "default",
+			peerKind: "direct",
+			peerId: parts.slice(1).join(":") || "cron",
+			threadId,
+			scopeId
 		};
-		let i = 0;
-		while (i < rest.length) {
-			const marker = rest[i]?.toLowerCase();
-			const value = rest[i + 1];
-			if (marker === "thread" && value) {
-				result.threadId = value.toLowerCase();
-				i += 2;
-			} else if (marker === "scope" && value) {
-				result.scopeId = value.toLowerCase();
-				i += 2;
-			} else i++;
-		}
-		return result;
 	}
-	if (parts.length < 5) return null;
-	const [agentId, source, accountId, peerKind, peerId, ...rest] = parts;
-	if (!agentId || !source || !accountId || !peerKind || !peerId) return null;
-	const result = {
-		agentId: agentId.toLowerCase(),
-		source: source.toLowerCase(),
-		accountId: accountId.toLowerCase(),
-		peerKind: peerKind.toLowerCase(),
-		peerId: peerId.toLowerCase()
+	const parts = rest.split(":").filter(Boolean);
+	if (parts.length >= 4 && parts[2] === "direct") return {
+		agentId: agentParsed.agentId,
+		source: parts[0],
+		accountId: parts[1],
+		peerKind: "direct",
+		peerId: parts.slice(3).join(":"),
+		threadId,
+		scopeId
+	};
+	if (parts.length >= 3 && parts[1] === "direct") return {
+		agentId: agentParsed.agentId,
+		source: parts[0],
+		accountId: "default",
+		peerKind: "direct",
+		peerId: parts.slice(2).join(":"),
+		threadId,
+		scopeId
+	};
+	if (parts.length >= 2 && parts[0] === "direct") return {
+		agentId: agentParsed.agentId,
+		source: "cli",
+		accountId: "default",
+		peerKind: "direct",
+		peerId: parts.slice(1).join(":"),
+		threadId,
+		scopeId
+	};
+	if (parts.length >= 3 && (parts[1] === "group" || parts[1] === "channel")) return {
+		agentId: agentParsed.agentId,
+		source: parts[0],
+		accountId: "default",
+		peerKind: parts[1],
+		peerId: parts.slice(2).join(":"),
+		threadId,
+		scopeId
+	};
+	return {
+		agentId: agentParsed.agentId,
+		source: "cli",
+		accountId: "default",
+		peerKind: "direct",
+		peerId: rest,
+		threadId,
+		scopeId
 	};
-	let i = 0;
-	while (i < rest.length) {
-		const marker = rest[i]?.toLowerCase();
-		const value = rest[i + 1];
-		if (marker === "thread" && value) {
-			result.threadId = value.toLowerCase();
-			i += 2;
-		} else if (marker === "scope" && value) {
-			result.scopeId = value.toLowerCase();
-			i += 2;
-		} else i++;
-	}
-	return result;
 }
-/**
-* Whether the key refers to a subagent session.
-*/
-function isSubagentSessionKey(sessionKey) {
-	return parseSessionKey(sessionKey)?.agentId === "subagent";
+function parseThreadSuffix(raw) {
+	const idx = raw.toLowerCase().lastIndexOf(":thread:");
+	if (idx === -1) return { baseSessionKey: raw };
+	return {
+		baseSessionKey: raw.slice(0, idx),
+		threadId: raw.slice(idx + 8)
+	};
 }
-/**
-* Whether the key is a cron-driven session.
-*/
-function isCronSessionKey(sessionKey) {
-	return parseSessionKey(sessionKey)?.source === "cron";
+function parseScopeSuffix(rest) {
+	const idx = rest.toLowerCase().lastIndexOf(":scope:");
+	if (idx === -1) return { rest };
+	return {
+		rest: rest.slice(0, idx),
+		scopeId: rest.slice(idx + 7)
+	};
 }
-/**
-* Nesting depth from repeated `subagent` prefixes in the colon-separated key.
-* e.g. `subagent:...` => 1, `subagent:subagent:...` => 2
-*/
-function getSubagentDepth(sessionKey) {
-	const raw = (sessionKey ?? "").trim();
-	if (!raw) return 0;
-	const parts = raw.split(":");
-	let depth = 0;
-	for (const part of parts) if (part.toLowerCase() === "subagent") depth++;
-	else break;
-	return depth;
+function parseSubagentRest(parentAgentId, rest, threadId, scopeId) {
+	const body = rest.replace(/^subagent:/, "");
+	const parentKey = body ? `agent:${parentAgentId}:${body}` : "";
+	const parentParsed = parentKey ? parseSessionKey(parentKey) : null;
+	if (parentParsed) return {
+		...parentParsed,
+		agentId: "subagent",
+		threadId: threadId ?? parentParsed.threadId,
+		scopeId: scopeId ?? parentParsed.scopeId
+	};
+	return {
+		agentId: "subagent",
+		source: parentAgentId,
+		accountId: "default",
+		peerKind: "direct",
+		peerId: body || "unknown",
+		threadId,
+		scopeId
+	};
 }
 function buildSubagentSessionKey(params) {
-	const parentParsed = parseSessionKey(params.parentSessionKey);
+	const parentParsed = parseAgentSessionKey(params.parentSessionKey);
 	if (!parentParsed) throw new Error(`Invalid parent session key: ${params.parentSessionKey}`);
-	return buildSessionKey({
-		agentId: "subagent",
-		source: parentParsed.agentId,
-		accountId: parentParsed.accountId,
-		peerKind: parentParsed.peerKind,
-		peerId: parentParsed.peerId,
-		threadId: params.threadId,
-		scopeId: params.scopeId
-	});
+	const parentRest = parentParsed.rest;
+	let key = `agent:${normalizeAgentId(parentParsed.agentId)}:subagent:${parentRest}`;
+	if (params.threadId) key = resolveThreadSessionKeys({
+		baseSessionKey: key,
+		threadId: params.threadId
+	}).sessionKey;
+	return key;
 }
-/**
-* Parent session key without a :thread: suffix, if any.
-*/
 function getParentSessionKey(sessionKey) {
 	const parsed = parseSessionKey(sessionKey);
-	if (!parsed) return null;
-	if (!parsed.threadId) return null;
+	if (!parsed?.threadId) return null;
 	return buildSessionKey({
 		agentId: parsed.agentId,
 		source: parsed.source,
 		accountId: parsed.accountId,
 		peerKind: parsed.peerKind,
-		peerId: parsed.peerId
+		peerId: parsed.peerId,
+		scopeId: parsed.scopeId
 	});
 }
-/**
-* Normalize a session key (trim + lowercase).
-*/
-function normalizeSessionKey(sessionKey) {
-	return (sessionKey ?? "").trim().toLowerCase();
-}
 var VALID_SEGMENT_RE, INVALID_CHARS_RE, LEADING_DASH_RE, TRAILING_DASH_RE;
 var init_session_key = __esmMin((() => {
+	init_agent_session_key();
+	init_agent_session_key();
+	init_session_key_utils();
 	VALID_SEGMENT_RE = /^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/i;
 	INVALID_CHARS_RE = /[^a-z0-9_-]+/g;
 	LEADING_DASH_RE = /^-+/;
@@ -161,6 +188,6 @@ var init_session_key = __esmMin((() => {
 }));
 //#endregion
 init_session_key();
-export { buildSessionKey, buildSubagentSessionKey, getParentSessionKey, getSubagentDepth, init_session_key, isCronSessionKey, isSubagentSessionKey, isValidSegment, normalizeSessionKey, parseSessionKey, sanitizeSegment };
+export { DEFAULT_ACCOUNT_ID, DEFAULT_AGENT_ID, DEFAULT_MAIN_KEY, assertAgentSessionKey, buildAgentMainSessionKey, buildAgentPeerSessionKey, buildGroupHistoryKey, buildSessionKey, buildSubagentSessionKey, classifySessionKeyShape, defaultMainSessionKey, getParentSessionKey, getSubagentDepth, init_session_key, isAcpSessionKey, isCronRunSessionKey, isCronSessionKey, isSubagentSessionKey, isValidAgentId, isValidSegment, normalizeAccountId, normalizeAgentId, normalizeMainKey, normalizeOptionalAccountId, normalizeSessionKey, parseAgentSessionKey, parseRawSessionConversationRef, parseSessionKey, parseThreadSessionSuffix, resolveAgentIdFromSessionKey, resolveThreadParentSessionKey, resolveThreadSessionKeys, sanitizeAgentId, sanitizeSegment, scopedHeartbeatWakeOptions, toAgentRequestSessionKey, toAgentStoreSessionKey };
 
 //# sourceMappingURL=session-key.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"session-key.js","names":[],"sources":["../../../src/routing/session-key.ts"],"sourcesContent":["/**\n * Session key construction and parsing.\n *\n * Format: {agentId}:{source}:{accountId}:{peerKind}:{peerId}[:thread:{threadId}][:scope:{scopeId}]\n *\n * Examples:\n * - main:telegram:acc_default:dm:123456\n * - main:discord:acc_work:channel:987654:thread:789\n * - subagent:main:abc123:telegram:acc_default:dm:123456\n */\n\n// Precompiled regexes for segment validation\nconst VALID_SEGMENT_RE = /^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/i;\nconst INVALID_CHARS_RE = /[^a-z0-9_-]+/g;\nconst LEADING_DASH_RE = /^-+/;\nconst TRAILING_DASH_RE = /-+$/;\n\n/**\n * Sanitize a segment to allowed chars a-z0-9_-\n */\nexport function sanitizeSegment(value: string | undefined | null, options?: { allowLeadingDash?: boolean }): string {\n  const trimmed = (value ?? '').trim();\n  if (!trimmed) {\n    return '';\n  }\n  \n  // Strip disallowed characters\n  let cleaned = trimmed\n    .toLowerCase()\n    .replace(INVALID_CHARS_RE, '-');\n  \n  // Trim leading/trailing dashes unless a leading dash is allowed (e.g. negative IDs)\n  if (!options?.allowLeadingDash) {\n    cleaned = cleaned\n      .replace(LEADING_DASH_RE, '')\n      .replace(TRAILING_DASH_RE, '');\n  } else {\n    // When leading dash is allowed, only strip trailing dashes\n    cleaned = cleaned.replace(TRAILING_DASH_RE, '');\n  }\n  \n  if (!cleaned) {\n    return '';\n  }\n  \n  return cleaned.slice(0, 64);\n}\n\n/**\n * Whether the segment matches the allowed pattern and length.\n */\nexport function isValidSegment(value: string | undefined | null): boolean {\n  const trimmed = (value ?? '').trim();\n  if (!trimmed) {\n    return false;\n  }\n  \n  if (trimmed.length > 64) {\n    return false;\n  }\n  \n  return VALID_SEGMENT_RE.test(trimmed);\n}\n\n/**\n * Fields used to build a session key.\n */\nexport interface BuildSessionKeyParams {\n  agentId: string;\n  source: string;\n  accountId: string;\n  peerKind: string;\n  peerId: string;\n  threadId?: string | null;\n  scopeId?: string | null;\n}\n\nexport function buildSessionKey(params: BuildSessionKeyParams): string {\n  const segments = [\n    sanitizeSegment(params.agentId) || 'main',\n    sanitizeSegment(params.source) || 'unknown',\n    sanitizeSegment(params.accountId) || 'default',\n    sanitizeSegment(params.peerKind) || 'unknown',\n    // peerId may start with '-' (e.g. Telegram supergroup id -1001234567890)\n    sanitizeSegment(params.peerId, { allowLeadingDash: true }) || 'unknown',\n  ];\n  \n  if (params.threadId) {\n    segments.push('thread', sanitizeSegment(params.threadId, { allowLeadingDash: true }) || 'unknown');\n  }\n  \n  if (params.scopeId) {\n    segments.push('scope', sanitizeSegment(params.scopeId, { allowLeadingDash: true }) || 'default');\n  }\n  \n  return segments.join(':');\n}\n\n/**\n * Parsed session key components.\n */\nexport interface ParsedSessionKey {\n  agentId: string;\n  source: string;\n  accountId: string;\n  peerKind: string;\n  peerId: string;\n  threadId?: string;\n  scopeId?: string;\n}\n\nexport function parseSessionKey(sessionKey: string | undefined | null): ParsedSessionKey | null {\n  const raw = (sessionKey ?? '').trim();\n  if (!raw) {\n    return null;\n  }\n  \n  const parts = raw.split(':').filter(Boolean);\n\n  /**\n   * Alternate encoding used in some installs / tests: `gateway:{agentId}:{source}:{accountId}:{peerKind}:{peerId}…`\n   * (distinct from normal `{agentId}:{source}:…` where the first segment is the agent id.)\n   */\n  if (parts.length >= 6 && parts[0]?.toLowerCase() === 'gateway') {\n    const agentId = parts[1] ?? '';\n    const source = parts[2] ?? '';\n    const accountId = parts[3] ?? '';\n    const peerKind = parts[4] ?? '';\n    const peerId = parts[5] ?? '';\n    const rest = parts.slice(6);\n    const result: ParsedSessionKey = {\n      agentId: agentId.toLowerCase(),\n      source: source.toLowerCase(),\n      accountId: accountId.toLowerCase(),\n      peerKind: peerKind.toLowerCase(),\n      peerId: peerId.toLowerCase(),\n    };\n    let i = 0;\n    while (i < rest.length) {\n      const marker = rest[i]?.toLowerCase();\n      const value = rest[i + 1];\n      if (marker === 'thread' && value) {\n        result.threadId = value.toLowerCase();\n        i += 2;\n      } else if (marker === 'scope' && value) {\n        result.scopeId = value.toLowerCase();\n        i += 2;\n      } else {\n        i++;\n      }\n    }\n    return result;\n  }\n\n  if (parts.length < 5) {\n    return null;\n  }\n  \n  const [agentId, source, accountId, peerKind, peerId, ...rest] = parts;\n  \n  if (!agentId || !source || !accountId || !peerKind || !peerId) {\n    return null;\n  }\n  \n  const result: ParsedSessionKey = {\n    agentId: agentId.toLowerCase(),\n    source: source.toLowerCase(),\n    accountId: accountId.toLowerCase(),\n    peerKind: peerKind.toLowerCase(),\n    peerId: peerId.toLowerCase(),\n  };\n  \n  // Optional :thread: and :scope: suffix segments\n  let i = 0;\n  while (i < rest.length) {\n    const marker = rest[i]?.toLowerCase();\n    const value = rest[i + 1];\n    \n    if (marker === 'thread' && value) {\n      result.threadId = value.toLowerCase();\n      i += 2;\n    } else if (marker === 'scope' && value) {\n      result.scopeId = value.toLowerCase();\n      i += 2;\n    } else {\n      i++;\n    }\n  }\n  \n  return result;\n}\n\n/**\n * Whether the key refers to a subagent session.\n */\nexport function isSubagentSessionKey(sessionKey: string | undefined | null): boolean {\n  const parsed = parseSessionKey(sessionKey);\n  return parsed?.agentId === 'subagent';\n}\n\n/**\n * Whether the key is a cron-driven session.\n */\nexport function isCronSessionKey(sessionKey: string | undefined | null): boolean {\n  const parsed = parseSessionKey(sessionKey);\n  return parsed?.source === 'cron';\n}\n\n/**\n * Nesting depth from repeated `subagent` prefixes in the colon-separated key.\n * e.g. `subagent:...` => 1, `subagent:subagent:...` => 2\n */\nexport function getSubagentDepth(sessionKey: string | undefined | null): number {\n  const raw = (sessionKey ?? '').trim();\n  if (!raw) {\n    return 0;\n  }\n  \n  const parts = raw.split(':');\n  let depth = 0;\n  \n  for (const part of parts) {\n    if (part.toLowerCase() === 'subagent') {\n      depth++;\n    } else {\n      break;\n    }\n  }\n  \n  return depth;\n}\n\n/**\n * Parameters for building a subagent session key.\n */\nexport interface BuildSubagentSessionKeyParams extends BuildSessionKeyParams {\n  parentSessionKey: string;\n}\n\nexport function buildSubagentSessionKey(params: BuildSubagentSessionKeyParams): string {\n  const parentParsed = parseSessionKey(params.parentSessionKey);\n  if (!parentParsed) {\n    throw new Error(`Invalid parent session key: ${params.parentSessionKey}`);\n  }\n  \n  return buildSessionKey({\n    agentId: 'subagent',\n    source: parentParsed.agentId,\n    accountId: parentParsed.accountId,\n    peerKind: parentParsed.peerKind,\n    peerId: parentParsed.peerId,\n    threadId: params.threadId,\n    scopeId: params.scopeId,\n  });\n}\n\n/**\n * Parent session key without a :thread: suffix, if any.\n */\nexport function getParentSessionKey(sessionKey: string | undefined | null): string | null {\n  const parsed = parseSessionKey(sessionKey);\n  if (!parsed) {\n    return null;\n  }\n  \n  if (!parsed.threadId) {\n    return null;\n  }\n  \n  return buildSessionKey({\n    agentId: parsed.agentId,\n    source: parsed.source,\n    accountId: parsed.accountId,\n    peerKind: parsed.peerKind,\n    peerId: parsed.peerId,\n  });\n}\n\n/**\n * Normalize a session key (trim + lowercase).\n */\nexport function normalizeSessionKey(sessionKey: string | undefined | null): string {\n  return (sessionKey ?? '').trim().toLowerCase();\n}\n"],"mappings":"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"}
+{"version":3,"file":"session-key.js","names":[],"sources":["../../../src/routing/session-key.ts"],"sourcesContent":["/**\n * Session key parsing helpers for `agent:{agentId}:{rest}` keys.\n *\n * Re-exports the OpenClaw-aligned builder/parser surface from agent-session-key.ts.\n */\n\nimport {\n  buildAgentPeerSessionKey,\n  defaultMainSessionKey,\n  normalizeAgentId,\n  normalizeMainKey,\n  parseAgentSessionKey,\n  resolveThreadSessionKeys,\n  type PeerKind,\n} from './agent-session-key.js';\n\nexport * from './agent-session-key.js';\nexport * from './session-key-utils.js';\n\nconst VALID_SEGMENT_RE = /^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/i;\nconst INVALID_CHARS_RE = /[^a-z0-9_-]+/g;\nconst LEADING_DASH_RE = /^-+/;\nconst TRAILING_DASH_RE = /-+$/;\n\nexport function sanitizeSegment(\n  value: string | undefined | null,\n  options?: { allowLeadingDash?: boolean },\n): string {\n  const trimmed = (value ?? '').trim();\n  if (!trimmed) {\n    return '';\n  }\n\n  let cleaned = trimmed.toLowerCase().replace(INVALID_CHARS_RE, '-');\n\n  if (!options?.allowLeadingDash) {\n    cleaned = cleaned.replace(LEADING_DASH_RE, '').replace(TRAILING_DASH_RE, '');\n  } else {\n    cleaned = cleaned.replace(TRAILING_DASH_RE, '');\n  }\n\n  if (!cleaned) {\n    return '';\n  }\n\n  return cleaned.slice(0, 64);\n}\n\nexport function isValidSegment(value: string | undefined | null): boolean {\n  const trimmed = (value ?? '').trim();\n  if (!trimmed || trimmed.length > 64) {\n    return false;\n  }\n  return VALID_SEGMENT_RE.test(trimmed);\n}\n\n/** Structured view of an agent session key rest segment. */\nexport interface ParsedSessionKey {\n  agentId: string;\n  source: string;\n  accountId: string;\n  peerKind: string;\n  peerId: string;\n  threadId?: string;\n  scopeId?: string;\n}\n\nexport interface BuildSessionKeyParams {\n  agentId: string;\n  source: string;\n  accountId: string;\n  peerKind: string;\n  peerId: string;\n  threadId?: string | null;\n  scopeId?: string | null;\n  mainKey?: string;\n  dmScope?: 'main' | 'per-peer' | 'per-channel-peer' | 'per-account-channel-peer';\n  identityLinks?: Record<string, string[]>;\n}\n\n/** Build an OpenClaw-style agent session key from routing segments. */\nexport function buildSessionKey(params: BuildSessionKeyParams): string {\n  const peerKind = (params.peerKind === 'dm' ? 'direct' : params.peerKind) as PeerKind;\n  let key = buildAgentPeerSessionKey({\n    agentId: params.agentId,\n    mainKey: params.mainKey,\n    channel: params.source,\n    accountId: params.accountId,\n    peerKind,\n    peerId: params.peerId,\n    identityLinks: params.identityLinks,\n    dmScope:\n      params.dmScope ??\n      (peerKind === 'direct' ? 'per-account-channel-peer' : undefined),\n  });\n\n  if (params.threadId) {\n    key = resolveThreadSessionKeys({ baseSessionKey: key, threadId: params.threadId }).sessionKey;\n  }\n\n  if (params.scopeId) {\n    key = `${key}:scope:${sanitizeSegment(params.scopeId, { allowLeadingDash: true }) || 'default'}`;\n  }\n\n  return key;\n}\n\n/** Parse `agent:{agentId}:{rest}` into routing segments. Returns null for invalid keys. */\nexport function parseSessionKey(sessionKey: string | undefined | null): ParsedSessionKey | null {\n  const raw = (sessionKey ?? '').trim();\n  if (!raw) {\n    return null;\n  }\n\n  const { baseSessionKey, threadId } = parseThreadSuffix(raw);\n  const agentParsed = parseAgentSessionKey(baseSessionKey);\n  if (!agentParsed) {\n    return null;\n  }\n\n  const scopeParts = parseScopeSuffix(agentParsed.rest);\n  const rest = scopeParts.rest;\n  const scopeId = scopeParts.scopeId;\n\n  const mainKey = normalizeMainKey(undefined);\n  if (rest === mainKey) {\n    return {\n      agentId: agentParsed.agentId,\n      source: 'cli',\n      accountId: 'default',\n      peerKind: 'direct',\n      peerId: mainKey,\n      threadId,\n      scopeId,\n    };\n  }\n\n  if (rest.startsWith('subagent:')) {\n    return parseSubagentRest(agentParsed.agentId, rest, threadId, scopeId);\n  }\n\n  if (rest.startsWith('cron:')) {\n    const parts = rest.split(':');\n    return {\n      agentId: agentParsed.agentId,\n      source: 'cron',\n      accountId: 'default',\n      peerKind: 'direct',\n      peerId: parts.slice(1).join(':') || 'cron',\n      threadId,\n      scopeId,\n    };\n  }\n\n  const parts = rest.split(':').filter(Boolean);\n\n  // channel:account:direct:peer\n  if (parts.length >= 4 && parts[2] === 'direct') {\n    return {\n      agentId: agentParsed.agentId,\n      source: parts[0]!,\n      accountId: parts[1]!,\n      peerKind: 'direct',\n      peerId: parts.slice(3).join(':'),\n      threadId,\n      scopeId,\n    };\n  }\n\n  // channel:direct:peer\n  if (parts.length >= 3 && parts[1] === 'direct') {\n    return {\n      agentId: agentParsed.agentId,\n      source: parts[0]!,\n      accountId: 'default',\n      peerKind: 'direct',\n      peerId: parts.slice(2).join(':'),\n      threadId,\n      scopeId,\n    };\n  }\n\n  // direct:peer\n  if (parts.length >= 2 && parts[0] === 'direct') {\n    return {\n      agentId: agentParsed.agentId,\n      source: 'cli',\n      accountId: 'default',\n      peerKind: 'direct',\n      peerId: parts.slice(1).join(':'),\n      threadId,\n      scopeId,\n    };\n  }\n\n  // channel:group|channel:peer\n  if (parts.length >= 3 && (parts[1] === 'group' || parts[1] === 'channel')) {\n    return {\n      agentId: agentParsed.agentId,\n      source: parts[0]!,\n      accountId: 'default',\n      peerKind: parts[1]!,\n      peerId: parts.slice(2).join(':'),\n      threadId,\n      scopeId,\n    };\n  }\n\n  // Custom rest (e.g. tui-uuid)\n  return {\n    agentId: agentParsed.agentId,\n    source: 'cli',\n    accountId: 'default',\n    peerKind: 'direct',\n    peerId: rest,\n    threadId,\n    scopeId,\n  };\n}\n\nfunction parseThreadSuffix(raw: string): { baseSessionKey: string; threadId?: string } {\n  const lower = raw.toLowerCase();\n  const idx = lower.lastIndexOf(':thread:');\n  if (idx === -1) {\n    return { baseSessionKey: raw };\n  }\n  return {\n    baseSessionKey: raw.slice(0, idx),\n    threadId: raw.slice(idx + ':thread:'.length),\n  };\n}\n\nfunction parseScopeSuffix(rest: string): { rest: string; scopeId?: string } {\n  const lower = rest.toLowerCase();\n  const idx = lower.lastIndexOf(':scope:');\n  if (idx === -1) {\n    return { rest };\n  }\n  return {\n    rest: rest.slice(0, idx),\n    scopeId: rest.slice(idx + ':scope:'.length),\n  };\n}\n\nfunction parseSubagentRest(\n  parentAgentId: string,\n  rest: string,\n  threadId?: string,\n  scopeId?: string,\n): ParsedSessionKey {\n  const body = rest.replace(/^subagent:/, '');\n  const parentKey = body ? `agent:${parentAgentId}:${body}` : '';\n  const parentParsed = parentKey ? parseSessionKey(parentKey) : null;\n  if (parentParsed) {\n    return {\n      ...parentParsed,\n      agentId: 'subagent',\n      threadId: threadId ?? parentParsed.threadId,\n      scopeId: scopeId ?? parentParsed.scopeId,\n    };\n  }\n  return {\n    agentId: 'subagent',\n    source: parentAgentId,\n    accountId: 'default',\n    peerKind: 'direct',\n    peerId: body || 'unknown',\n    threadId,\n    scopeId,\n  };\n}\n\nexport interface BuildSubagentSessionKeyParams extends BuildSessionKeyParams {\n  parentSessionKey: string;\n}\n\nexport function buildSubagentSessionKey(params: BuildSubagentSessionKeyParams): string {\n  const parentParsed = parseAgentSessionKey(params.parentSessionKey);\n  if (!parentParsed) {\n    throw new Error(`Invalid parent session key: ${params.parentSessionKey}`);\n  }\n  const parentRest = parentParsed.rest;\n  let key = `agent:${normalizeAgentId(parentParsed.agentId)}:subagent:${parentRest}`;\n  if (params.threadId) {\n    key = resolveThreadSessionKeys({ baseSessionKey: key, threadId: params.threadId }).sessionKey;\n  }\n  return key;\n}\n\nexport function getParentSessionKey(sessionKey: string | undefined | null): string | null {\n  const parsed = parseSessionKey(sessionKey);\n  if (!parsed?.threadId) {\n    return null;\n  }\n  return buildSessionKey({\n    agentId: parsed.agentId,\n    source: parsed.source,\n    accountId: parsed.accountId,\n    peerKind: parsed.peerKind,\n    peerId: parsed.peerId,\n    scopeId: parsed.scopeId,\n  });\n}\n\nexport { defaultMainSessionKey };\n"],"mappings":"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"}

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

@@ -11,6 +11,12 @@ export { normalizeWorkingDirectoryInput, effectiveWorkspacePathForSession, } fro
 export { SessionStatus, type SessionMetadata, type SessionDetail, type SessionListQuery, type PaginatedResult, type SessionStats, type ExportFormat, type SessionExport, type SessionTranscriptSummary, type CompactionCheckpointSummary, type CompactionCheckpointDetail, } from './types.js';
 export { normalizeCompactionCheckpointId } from './compaction-checkpoints.js';
 export { shouldSkipWebchatInboundByAbortCutoff } from './abort-cutoff.js';
+export { DEFAULT_RESET_AT_HOUR, DEFAULT_RESET_MODE, DEFAULT_IDLE_MINUTES, evaluateSessionFreshness, resolveDailyResetAtMs, resolveSessionResetPolicy, type SessionFreshness, type SessionResetConfig, type SessionResetMode, type SessionResetPolicy, type SessionResetType, } from './reset-policy.js';
+export { isThreadSessionKey, resolveChannelResetConfig, resolveSessionResetType, } from './reset-type.js';
+export { resolveSessionLifecycleTimestamps, type SessionLifecycleEntry } from './lifecycle-timestamps.js';
+export { resolveSession, resolveSessionKeyForRequest, type SessionKeyResolution, type SessionResolution, } from './resolve-session.js';
+export { initSessionTurn, type InitSessionTurnOptions, type InitSessionTurnResult, type SessionResetFn, } from './init-session-turn.js';
+export { DEFAULT_RESET_TRIGGERS, RESET_OVERLAP_COMMANDS, bareResetAckMessage, matchResetTriggers, resolveResetTriggers, shouldSkipResetOverlapCommand, stripLeadingEnvelopeTimestamp, type ResetTriggerMatch, } from './reset-triggers.js';
 export type { CompactionConfig, CompactionResult } from '../agent/memory/compaction.js';
 export type { WindowConfig } from '../agent/memory/window.js';
 export { maybeAutoTitleSessionStore, generateSessionTitleFromMessages, sanitizeSessionTitle, fallbackTitleFromMessages, isWebchatSessionKey, shouldAutoTitleSessionKey, } from './session-title.js';

package/dist/src/session/index.js

@@ -12,6 +12,12 @@ import { SessionConfigStore, resolveReasoningLevel, resolveThinkingLevel, resolv
 import { resolveEffectiveReasoningLevel, resolveEffectiveThinkingLevel } from "./thinking-resolve.js";
 import { effectiveWorkspacePathForSession, normalizeWorkingDirectoryInput } from "./session-workspace.js";
 import { shouldSkipWebchatInboundByAbortCutoff } from "./abort-cutoff.js";
+import { DEFAULT_IDLE_MINUTES, DEFAULT_RESET_AT_HOUR, DEFAULT_RESET_MODE, evaluateSessionFreshness, resolveDailyResetAtMs, resolveSessionResetPolicy } from "./reset-policy.js";
+import { isThreadSessionKey, resolveChannelResetConfig, resolveSessionResetType } from "./reset-type.js";
+import { resolveSessionLifecycleTimestamps } from "./lifecycle-timestamps.js";
+import { resolveSession, resolveSessionKeyForRequest } from "./resolve-session.js";
+import { DEFAULT_RESET_TRIGGERS, RESET_OVERLAP_COMMANDS, bareResetAckMessage, matchResetTriggers, resolveResetTriggers, shouldSkipResetOverlapCommand, stripLeadingEnvelopeTimestamp } from "./reset-triggers.js";
+import { initSessionTurn } from "./init-session-turn.js";
 import { flattenMessageContent, messagesToClientHistory } from "./client-history.js";
 import { CURRENT_SESSION_TRANSCRIPT_VERSION, XOPC_SESSION_TRANSCRIPT_TYPE } from "./transcript-format.js";
-export { CURRENT_SESSION_TRANSCRIPT_VERSION, SessionConfigStore, SessionIndex, SessionSearchIndex, SessionStatus, SessionStore, XOPC_SESSION_TRANSCRIPT_TYPE, applySessionPatchToMetadata, buildSessionContextForLlm, effectiveWorkspacePathForSession, emitSessionTranscriptUpdate, fallbackTitleFromMessages, flattenMessageContent, generateSessionTitleFromMessages, getOrLoadSessionSearchIndex, invalidateSessionSearchIndexCache, isTranscriptContextEntry, isWebchatSessionKey, maybeAutoTitleSessionStore, mergeLlmMessagesPreservingContextRows, messagesToClientHistory, normalizeCompactionCheckpointId, normalizeWorkingDirectoryInput, onSessionTranscriptUpdate, resolveEffectiveReasoningLevel, resolveEffectiveThinkingLevel, resolveReasoningLevel, resolveThinkingLevel, resolveVerboseLevel, sanitizeSessionTitle, shouldAutoTitleSessionKey, shouldSkipWebchatInboundByAbortCutoff, transcriptRowsFromJsonArray };
+export { CURRENT_SESSION_TRANSCRIPT_VERSION, DEFAULT_IDLE_MINUTES, DEFAULT_RESET_AT_HOUR, DEFAULT_RESET_MODE, DEFAULT_RESET_TRIGGERS, RESET_OVERLAP_COMMANDS, SessionConfigStore, SessionIndex, SessionSearchIndex, SessionStatus, SessionStore, XOPC_SESSION_TRANSCRIPT_TYPE, applySessionPatchToMetadata, bareResetAckMessage, buildSessionContextForLlm, effectiveWorkspacePathForSession, emitSessionTranscriptUpdate, evaluateSessionFreshness, fallbackTitleFromMessages, flattenMessageContent, generateSessionTitleFromMessages, getOrLoadSessionSearchIndex, initSessionTurn, invalidateSessionSearchIndexCache, isThreadSessionKey, isTranscriptContextEntry, isWebchatSessionKey, matchResetTriggers, maybeAutoTitleSessionStore, mergeLlmMessagesPreservingContextRows, messagesToClientHistory, normalizeCompactionCheckpointId, normalizeWorkingDirectoryInput, onSessionTranscriptUpdate, resolveChannelResetConfig, resolveDailyResetAtMs, resolveEffectiveReasoningLevel, resolveEffectiveThinkingLevel, resolveReasoningLevel, resolveResetTriggers, resolveSession, resolveSessionKeyForRequest, resolveSessionLifecycleTimestamps, resolveSessionResetPolicy, resolveSessionResetType, resolveThinkingLevel, resolveVerboseLevel, sanitizeSessionTitle, shouldAutoTitleSessionKey, shouldSkipResetOverlapCommand, shouldSkipWebchatInboundByAbortCutoff, stripLeadingEnvelopeTimestamp, transcriptRowsFromJsonArray };

package/dist/src/session/init-session-turn.d.ts

@@ -0,0 +1,30 @@
+import { type Config } from '../config/schema.js';
+export type SessionResetFn = (sessionKey: string) => Promise<{
+    sessionId: string;
+    previousSessionId: string;
+} | null>;
+export type InitSessionTurnResult = {
+    sessionKey: string;
+    sessionId?: string;
+    previousSessionId?: string;
+    isNewSession: boolean;
+    resetTriggered: boolean;
+    staleRollover: boolean;
+    bodyStripped: string;
+    bareReset: boolean;
+    ackMessage?: string;
+};
+export type InitSessionTurnOptions = {
+    cfg: Config;
+    sessionKey: string;
+    body?: string;
+    resetSession: SessionResetFn;
+    /** When true, skip idle/daily implicit rollover (provider-owned CLI sessions). */
+    skipImplicitExpiry?: boolean;
+};
+/**
+ * Turn-start session init: match `resetTriggers`, evaluate freshness, archive +
+ * assign new `sessionId` when stale or explicitly reset. OpenClaw `initSessionState`
+ * equivalent for xopc direct + channel paths.
+ */
+export declare function initSessionTurn(opts: InitSessionTurnOptions): Promise<InitSessionTurnResult>;