@xopcai/xopc 0.0.86 → 0.0.87

package/dist/src/session/resolve-session.js

@@ -0,0 +1,93 @@
+import { SessionConfigSchema, init_schema } from "../config/schema.js";
+import { init_agent_scope, resolveDefaultAgentId } from "../agent/agent-scope.js";
+import { init_agent_session_key, normalizeAgentId, resolveAgentIdFromSessionKey } from "../routing/agent-session-key.js";
+import { init_session_key, parseSessionKey } from "../routing/session-key.js";
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { init_paths, resolveSessionsMapPath } from "../config/paths.js";
+import { readSessionsJsonFile } from "./parity/sessions-json-file.js";
+import { normalizeThinkLevel, normalizeVerboseLevel } from "../agent/transcript/thinking-types.js";
+import { evaluateSessionFreshness, resolveSessionResetPolicy } from "./reset-policy.js";
+import { resolveChannelResetConfig, resolveSessionResetType } from "./reset-type.js";
+import { resolveSessionLifecycleTimestamps } from "./lifecycle-timestamps.js";
+import { randomUUID } from "node:crypto";
+//#region src/session/resolve-session.ts
+init_schema();
+init_paths();
+init_agent_scope();
+init_agent_session_key();
+init_session_key();
+init_logger();
+const log = createLogger("ResolveSession");
+async function resolveSessionKeyForRequest(opts) {
+	const defaultAgentId = resolveDefaultAgentId(opts.cfg);
+	const explicitKey = opts.sessionKey?.trim();
+	const requestedSessionId = opts.sessionId?.trim();
+	const storeAgentId = explicitKey ? resolveAgentIdFromSessionKey(explicitKey) : opts.agentId?.trim() ? normalizeAgentId(opts.agentId) : defaultAgentId;
+	const storePath = resolveSessionsMapPath(opts.cfg, storeAgentId);
+	const sessionStore = await readSessionsJsonFile(storePath);
+	let sessionKey = explicitKey;
+	if (requestedSessionId && !sessionKey) {
+		for (const [key, entry] of Object.entries(sessionStore)) if (entry?.sessionId === requestedSessionId) {
+			sessionKey = key;
+			break;
+		}
+	}
+	if (requestedSessionId && !sessionKey) sessionKey = `agent:${normalizeAgentId(opts.agentId ?? storeAgentId)}:explicit:${requestedSessionId}`;
+	return {
+		sessionKey,
+		sessionStore,
+		storePath
+	};
+}
+async function resolveSession(opts) {
+	const sessionCfg = opts.cfg.session ?? SessionConfigSchema.parse({});
+	const { sessionKey, sessionStore, storePath } = await resolveSessionKeyForRequest(opts);
+	const now = Date.now();
+	const sessionEntry = sessionKey ? sessionStore[sessionKey] : void 0;
+	const parsed = sessionKey ? parseSessionKey(sessionKey) : null;
+	const peerKind = parsed?.peerKind;
+	const resetType = resolveSessionResetType({
+		sessionKey,
+		isGroup: peerKind === "group" || peerKind === "channel",
+		isThread: Boolean(parsed?.threadId)
+	});
+	const meta = sessionEntry?.pluginExtensions?.xopc?.metadata;
+	const resetPolicy = resolveSessionResetPolicy({
+		sessionCfg,
+		resetType,
+		resetOverride: resolveChannelResetConfig({
+			sessionCfg,
+			channel: parsed?.source ?? meta?.sourceChannel
+		})
+	});
+	const lifecycle = resolveSessionLifecycleTimestamps({ entry: sessionEntry });
+	const fresh = (sessionEntry ? evaluateSessionFreshness({
+		updatedAt: sessionEntry.updatedAt,
+		...lifecycle,
+		now,
+		policy: resetPolicy
+	}) : { fresh: false }).fresh;
+	const sessionId = opts.sessionId?.trim() || (fresh ? sessionEntry?.sessionId : void 0) || randomUUID();
+	const isNewSession = !fresh && !opts.sessionId?.trim();
+	if (isNewSession && sessionKey) log.debug({
+		sessionKey,
+		previousSessionId: sessionEntry?.sessionId,
+		sessionId,
+		resetType
+	}, "Session reset boundary — new transcript id for turn");
+	return {
+		sessionId,
+		sessionKey,
+		sessionEntry,
+		sessionStore,
+		storePath,
+		isNewSession,
+		persistedThinking: fresh && sessionEntry?.thinkingLevel ? normalizeThinkLevel(sessionEntry.thinkingLevel) : void 0,
+		persistedVerbose: fresh && sessionEntry?.verboseLevel ? normalizeVerboseLevel(sessionEntry.verboseLevel) : void 0
+	};
+}
+//#endregion
+export { resolveSession, resolveSessionKeyForRequest };
+
+//# sourceMappingURL=resolve-session.js.map

package/dist/src/session/resolve-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-session.js","names":[],"sources":["../../../src/session/resolve-session.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\n\nimport { SessionConfigSchema, type Config } from '../config/schema.js';\nimport { resolveSessionsMapPath } from '../config/paths.js';\nimport { resolveDefaultAgentId } from '../agent/agent-scope.js';\nimport {\n  normalizeAgentId,\n  resolveAgentIdFromSessionKey,\n} from '../routing/agent-session-key.js';\nimport { parseSessionKey } from '../routing/session-key.js';\nimport {\n  normalizeThinkLevel,\n  normalizeVerboseLevel,\n  type ThinkLevel,\n  type VerboseLevel,\n} from '../agent/transcript/thinking-types.js';\nimport { createLogger } from '../utils/logger.js';\n\nimport { resolveSessionLifecycleTimestamps } from './lifecycle-timestamps.js';\nimport { readSessionsJsonFile } from './parity/sessions-json-file.js';\nimport type { XopcSessionDiskEntry } from './parity/xopc-session-disk-entry.js';\nimport {\n  evaluateSessionFreshness,\n  resolveSessionResetPolicy,\n} from './reset-policy.js';\nimport { resolveChannelResetConfig, resolveSessionResetType } from './reset-type.js';\n\nconst log = createLogger('ResolveSession');\n\nexport type SessionResolution = {\n  sessionId: string;\n  sessionKey?: string;\n  sessionEntry?: XopcSessionDiskEntry;\n  sessionStore: Record<string, XopcSessionDiskEntry>;\n  storePath: string;\n  isNewSession: boolean;\n  persistedThinking?: ThinkLevel;\n  persistedVerbose?: VerboseLevel;\n};\n\nexport type SessionKeyResolution = {\n  sessionKey?: string;\n  sessionStore: Record<string, XopcSessionDiskEntry>;\n  storePath: string;\n};\n\nexport async function resolveSessionKeyForRequest(opts: {\n  cfg: Config;\n  sessionKey?: string;\n  sessionId?: string;\n  agentId?: string;\n}): Promise<SessionKeyResolution> {\n  const defaultAgentId = resolveDefaultAgentId(opts.cfg);\n  const explicitKey = opts.sessionKey?.trim();\n  const requestedSessionId = opts.sessionId?.trim();\n  const storeAgentId = explicitKey\n    ? resolveAgentIdFromSessionKey(explicitKey)\n    : opts.agentId?.trim()\n      ? normalizeAgentId(opts.agentId)\n      : defaultAgentId;\n  const storePath = resolveSessionsMapPath(opts.cfg, storeAgentId);\n  const sessionStore = await readSessionsJsonFile<XopcSessionDiskEntry>(storePath);\n\n  let sessionKey = explicitKey;\n  if (requestedSessionId && !sessionKey) {\n    for (const [key, entry] of Object.entries(sessionStore)) {\n      if (entry?.sessionId === requestedSessionId) {\n        sessionKey = key;\n        break;\n      }\n    }\n  }\n  if (requestedSessionId && !sessionKey) {\n    sessionKey = `agent:${normalizeAgentId(opts.agentId ?? storeAgentId)}:explicit:${requestedSessionId}`;\n  }\n\n  return { sessionKey, sessionStore, storePath };\n}\n\nexport async function resolveSession(opts: {\n  cfg: Config;\n  sessionKey?: string;\n  sessionId?: string;\n  agentId?: string;\n}): Promise<SessionResolution> {\n  const sessionCfg = opts.cfg.session ?? SessionConfigSchema.parse({});\n  const { sessionKey, sessionStore, storePath } = await resolveSessionKeyForRequest(opts);\n  const now = Date.now();\n  const sessionEntry = sessionKey ? sessionStore[sessionKey] : undefined;\n\n  const parsed = sessionKey ? parseSessionKey(sessionKey) : null;\n  const peerKind = parsed?.peerKind;\n  const resetType = resolveSessionResetType({\n    sessionKey,\n    isGroup: peerKind === 'group' || peerKind === 'channel',\n    isThread: Boolean(parsed?.threadId),\n  });\n  const meta = sessionEntry?.pluginExtensions?.xopc?.metadata;\n  const channelReset = resolveChannelResetConfig({\n    sessionCfg,\n    channel: parsed?.source ?? meta?.sourceChannel,\n  });\n  const resetPolicy = resolveSessionResetPolicy({\n    sessionCfg,\n    resetType,\n    resetOverride: channelReset,\n  });\n  const lifecycle = resolveSessionLifecycleTimestamps({ entry: sessionEntry });\n  const freshness = sessionEntry\n    ? evaluateSessionFreshness({\n        updatedAt: sessionEntry.updatedAt,\n        ...lifecycle,\n        now,\n        policy: resetPolicy,\n      })\n    : { fresh: false };\n  const fresh = freshness.fresh;\n  const sessionId =\n    opts.sessionId?.trim() || (fresh ? sessionEntry?.sessionId : undefined) || randomUUID();\n  const isNewSession = !fresh && !opts.sessionId?.trim();\n\n  if (isNewSession && sessionKey) {\n    log.debug(\n      { sessionKey, previousSessionId: sessionEntry?.sessionId, sessionId, resetType },\n      'Session reset boundary — new transcript id for turn',\n    );\n  }\n\n  const persistedThinking =\n    fresh && sessionEntry?.thinkingLevel\n      ? normalizeThinkLevel(sessionEntry.thinkingLevel)\n      : undefined;\n  const persistedVerbose =\n    fresh && sessionEntry?.verboseLevel\n      ? normalizeVerboseLevel(sessionEntry.verboseLevel)\n      : undefined;\n\n  return {\n    sessionId,\n    sessionKey,\n    sessionEntry,\n    sessionStore,\n    storePath,\n    isNewSession,\n    persistedThinking,\n    persistedVerbose,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;aAEuE;YACX;kBACI;wBAIvB;kBACmB;aAOV;AAWlD,MAAM,MAAM,aAAa,iBAAiB;AAmB1C,eAAsB,4BAA4B,MAKhB;CAChC,MAAM,iBAAiB,sBAAsB,KAAK,IAAI;CACtD,MAAM,cAAc,KAAK,YAAY,MAAM;CAC3C,MAAM,qBAAqB,KAAK,WAAW,MAAM;CACjD,MAAM,eAAe,cACjB,6BAA6B,YAAY,GACzC,KAAK,SAAS,MAAM,GAClB,iBAAiB,KAAK,QAAQ,GAC9B;CACN,MAAM,YAAY,uBAAuB,KAAK,KAAK,aAAa;CAChE,MAAM,eAAe,MAAM,qBAA2C,UAAU;CAEhF,IAAI,aAAa;AACjB,KAAI,sBAAsB,CAAC;OACpB,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,aAAa,CACrD,KAAI,OAAO,cAAc,oBAAoB;AAC3C,gBAAa;AACb;;;AAIN,KAAI,sBAAsB,CAAC,WACzB,cAAa,SAAS,iBAAiB,KAAK,WAAW,aAAa,CAAC,YAAY;AAGnF,QAAO;EAAE;EAAY;EAAc;EAAW;;AAGhD,eAAsB,eAAe,MAKN;CAC7B,MAAM,aAAa,KAAK,IAAI,WAAW,oBAAoB,MAAM,EAAE,CAAC;CACpE,MAAM,EAAE,YAAY,cAAc,cAAc,MAAM,4BAA4B,KAAK;CACvF,MAAM,MAAM,KAAK,KAAK;CACtB,MAAM,eAAe,aAAa,aAAa,cAAc,KAAA;CAE7D,MAAM,SAAS,aAAa,gBAAgB,WAAW,GAAG;CAC1D,MAAM,WAAW,QAAQ;CACzB,MAAM,YAAY,wBAAwB;EACxC;EACA,SAAS,aAAa,WAAW,aAAa;EAC9C,UAAU,QAAQ,QAAQ,SAAS;EACpC,CAAC;CACF,MAAM,OAAO,cAAc,kBAAkB,MAAM;CAKnD,MAAM,cAAc,0BAA0B;EAC5C;EACA;EACA,eAPmB,0BAA0B;GAC7C;GACA,SAAS,QAAQ,UAAU,MAAM;GAClC,CAI4B;EAC5B,CAAC;CACF,MAAM,YAAY,kCAAkC,EAAE,OAAO,cAAc,CAAC;CAS5E,MAAM,SARY,eACd,yBAAyB;EACvB,WAAW,aAAa;EACxB,GAAG;EACH;EACA,QAAQ;EACT,CAAC,GACF,EAAE,OAAO,OAAO,EACI;CACxB,MAAM,YACJ,KAAK,WAAW,MAAM,KAAK,QAAQ,cAAc,YAAY,KAAA,MAAc,YAAY;CACzF,MAAM,eAAe,CAAC,SAAS,CAAC,KAAK,WAAW,MAAM;AAEtD,KAAI,gBAAgB,WAClB,KAAI,MACF;EAAE;EAAY,mBAAmB,cAAc;EAAW;EAAW;EAAW,EAChF,sDACD;AAYH,QAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA,mBAfA,SAAS,cAAc,gBACnB,oBAAoB,aAAa,cAAc,GAC/C,KAAA;EAcJ,kBAZA,SAAS,cAAc,eACnB,sBAAsB,aAAa,aAAa,GAChD,KAAA;EAWL"}

package/dist/src/session/session-title.js

@@ -1,4 +1,5 @@
-import { init_session_key, isCronSessionKey, parseSessionKey } from "../routing/session-key.js";
+import { isCronSessionKey } from "../routing/session-key-utils.js";
+import { init_session_key, parseSessionKey } from "../routing/session-key.js";
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { init_providers, resolveModel } from "../providers/index.js";
@@ -139,7 +140,7 @@ async function maybeAutoTitleSessionStore(sessionStore, sessionKey, modelRef) {
 	if (!messages.length) return;
 	let meta = await sessionStore.getMetadata(sessionKey);
 	if (!meta) {
-		await sessionStore.save(sessionKey, messages);
+		await sessionStore.saveMessages(sessionKey, messages);
 		meta = await sessionStore.getMetadata(sessionKey);
 	}
 	if (!meta) {

package/dist/src/session/session-title.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-title.js","names":[],"sources":["../../../src/session/session-title.ts"],"sourcesContent":["/**\n * LLM-generated session titles (webchat and any path using SessionStore).\n */\n\nimport type { AgentMessage } from '@earendil-works/pi-agent-core';\nimport { complete, type UserMessage } from '@earendil-works/pi-ai';\n\nimport { stripSessionStartupContextFromUserText } from '../agent/reply/startup-context.js';\nimport { stripInboundFileMetadataFromText } from '../channels/attachments/inbound-persist.js';\nimport { stripEnvelopeTimestampPrefix } from '../channels/envelope-timestamp.js';\nimport { isCronSessionKey, parseSessionKey } from '../routing/session-key.js';\nimport { resolveModel } from '../providers/index.js';\nimport { createLogger } from '../utils/logger.js';\nimport { readAgentMessageContent } from '../agent/memory/agent-message-access.js';\nimport type { SessionStore } from './store.js';\n\nconst log = createLogger('SessionAutoTitle');\n\nconst MAX_TITLE_LEN = 80;\n\n/** Collect visible text from any content block that exposes `text` (pi-ai / OpenAI / Anthropic shapes). */\nfunction extractTextFromMessage(m: AgentMessage): string {\n  const raw = readAgentMessageContent(m);\n  if (typeof raw === 'string') return raw.trim();\n  if (Array.isArray(raw)) {\n    const parts: string[] = [];\n    for (const c of raw) {\n      if (c && typeof c === 'object') {\n        const o = c as unknown as Record<string, unknown>;\n        const type = typeof o.type === 'string' ? o.type : '';\n        if (type === 'toolCall' || type === 'tool_use' || type === 'tool_result') continue;\n        if (typeof o.text === 'string' && o.text.trim()) {\n          parts.push(o.text.trim());\n        }\n      }\n    }\n    return parts.join(' ').trim();\n  }\n  return '';\n}\n\nfunction firstUserText(messages: AgentMessage[]): string {\n  const u = messages.find((m) => m.role === 'user');\n  if (!u) return '';\n  const raw = extractTextFromMessage(u);\n  // User turns include `formatInboundFileTextBlock` text blocks; do not feed [File:…] into title LLM / fallback.\n  // Inbound pipeline / webchat prepends `[YYYY-MM-DD HH:MM TZ]`; strip so titles are not timestamp-led.\n  return stripInboundFileMetadataFromText(\n    stripEnvelopeTimestampPrefix(stripSessionStartupContextFromUserText(raw)),\n  );\n}\n\n/** First assistant message that has visible text (skips tool-only assistant rows). */\nfunction firstAssistantText(messages: AgentMessage[]): string {\n  for (const m of messages) {\n    if (m.role === 'assistant') {\n      const t = extractTextFromMessage(m);\n      if (t.length > 0) return t;\n    }\n  }\n  return '';\n}\n\nexport function isWebchatSessionKey(sessionKey: string): boolean {\n  const p = parseSessionKey(sessionKey);\n  if (p?.source === 'webchat') return true;\n  return sessionKey.includes(':webchat:');\n}\n\n/** Whether to run LLM/fallback session naming for this key (excludes cron, heartbeat). */\nexport function shouldAutoTitleSessionKey(sessionKey: string): boolean {\n  const raw = (sessionKey ?? '').trim();\n  if (!raw) return false;\n  if (isCronSessionKey(raw)) return false;\n  if (raw.toLowerCase().startsWith('heartbeat:')) return false;\n  return true;\n}\n\nexport function sanitizeSessionTitle(raw: string): string {\n  let s = raw.trim();\n  if ((s.startsWith('\"') && s.endsWith('\"')) || (s.startsWith(\"'\") && s.endsWith(\"'\"))) {\n    s = s.slice(1, -1).trim();\n  }\n  const lineBreak = s.indexOf('\\n');\n  if (lineBreak !== -1) s = s.slice(0, lineBreak).trim();\n  if (s.length > MAX_TITLE_LEN) s = s.slice(0, MAX_TITLE_LEN - 1).trimEnd() + '…';\n  return s;\n}\n\n/** Non-LLM title: first line of first user text, else first assistant line. */\nexport function fallbackTitleFromMessages(messages: AgentMessage[]): string | null {\n  const u = firstUserText(messages);\n  if (u) {\n    const line = u.split(/\\n/)[0]?.trim();\n    if (line) return sanitizeSessionTitle(line);\n  }\n  const a = firstAssistantText(messages);\n  if (a) {\n    const line = a.split(/\\n/)[0]?.trim();\n    if (line) return sanitizeSessionTitle(line);\n  }\n  return null;\n}\n\n/**\n * Returns a title string, or null if generation should be skipped or failed.\n */\nexport async function generateSessionTitleFromMessages(\n  modelRef: string,\n  messages: AgentMessage[],\n  signal?: AbortSignal,\n): Promise<string | null> {\n  const userText = firstUserText(messages);\n  const assistantText = firstAssistantText(messages);\n  if (!userText && !assistantText) return null;\n\n  let model: ReturnType<typeof resolveModel>;\n  try {\n    model = resolveModel(modelRef);\n  } catch (err) {\n    log.warn({ err, modelRef }, 'Cannot resolve model for session title');\n    return null;\n  }\n\n  const prompt =\n    userText && assistantText\n      ? `You label chat sessions. Given the first user message and the start of the assistant reply, output ONE short title (max 8 words). No quotes. No punctuation at the end. Use the same language as the user when possible.\n\nUser: ${userText.slice(0, 2000)}\n\nAssistant: ${assistantText.slice(0, 2000)}\n\nTitle:`\n      : userText\n        ? `The assistant reply only used tools (no visible text yet). Output ONE short title (max 8 words) based only on the user's first message. No quotes. No punctuation at the end. Use the same language as the user.\n\nUser: ${userText.slice(0, 2000)}\n\nTitle:`\n        : `Output ONE short title (max 8 words) for this assistant reply. No quotes. No punctuation at the end.\n\nAssistant: ${assistantText!.slice(0, 2000)}\n\nTitle:`;\n\n  const userMsg: UserMessage = { role: 'user', content: prompt, timestamp: Date.now() };\n\n  try {\n    const result = await complete(\n      model,\n      { messages: [userMsg] },\n      {\n        maxTokens: 64,\n        temperature: 0.35,\n        signal: signal as AbortSignal,\n      },\n    );\n\n    let text = '';\n    if (Array.isArray(result.content)) {\n      for (const c of result.content) {\n        if (c && typeof c === 'object' && (c as { type?: string }).type === 'text') {\n          text += String((c as { text?: string }).text || '');\n        }\n      }\n    }\n\n    const cleaned = sanitizeSessionTitle(text);\n    return cleaned.length > 0 ? cleaned : null;\n  } catch (err) {\n    log.warn({ err }, 'Session title LLM call failed');\n    return null;\n  }\n}\n\n/**\n * If the session is still unnamed, set `name` (LLM when possible, else first-line fallback).\n * Skips cron/heartbeat keys. Ensures index row exists by re-saving when metadata is missing (fixes index lag).\n */\nexport async function maybeAutoTitleSessionStore(\n  sessionStore: SessionStore,\n  sessionKey: string,\n  modelRef: string | undefined,\n): Promise<void> {\n  if (!shouldAutoTitleSessionKey(sessionKey)) return;\n\n  let messages = await sessionStore.load(sessionKey);\n  if (!messages.length) return;\n\n  let meta = await sessionStore.getMetadata(sessionKey);\n  if (!meta) {\n    await sessionStore.save(sessionKey, messages);\n    meta = await sessionStore.getMetadata(sessionKey);\n  }\n  if (!meta) {\n    log.warn({ sessionKey }, 'Session title: metadata missing after save');\n    return;\n  }\n  if (meta.name && meta.name.trim().length > 0) return;\n\n  let title: string | null = null;\n  const ref = modelRef?.trim();\n  if (ref) {\n    const controller = new AbortController();\n    const timeout = setTimeout(() => controller.abort(), 25_000);\n    try {\n      title = await generateSessionTitleFromMessages(ref, messages, controller.signal);\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n  if (!title) {\n    title = fallbackTitleFromMessages(messages);\n  }\n  if (!title) return;\n\n  try {\n    await sessionStore.updateMetadata(sessionKey, { name: title });\n  } catch (err) {\n    log.warn({ err, sessionKey }, 'Session title: updateMetadata failed');\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"session-title.js","names":[],"sources":["../../../src/session/session-title.ts"],"sourcesContent":["/**\n * LLM-generated session titles (webchat and any path using SessionStore).\n */\n\nimport type { AgentMessage } from '@earendil-works/pi-agent-core';\nimport { complete, type UserMessage } from '@earendil-works/pi-ai';\n\nimport { stripSessionStartupContextFromUserText } from '../agent/reply/startup-context.js';\nimport { stripInboundFileMetadataFromText } from '../channels/attachments/inbound-persist.js';\nimport { stripEnvelopeTimestampPrefix } from '../channels/envelope-timestamp.js';\nimport { isCronSessionKey, parseSessionKey } from '../routing/session-key.js';\nimport { resolveModel } from '../providers/index.js';\nimport { createLogger } from '../utils/logger.js';\nimport { readAgentMessageContent } from '../agent/memory/agent-message-access.js';\nimport type { SessionStore } from './store.js';\n\nconst log = createLogger('SessionAutoTitle');\n\nconst MAX_TITLE_LEN = 80;\n\n/** Collect visible text from any content block that exposes `text` (pi-ai / OpenAI / Anthropic shapes). */\nfunction extractTextFromMessage(m: AgentMessage): string {\n  const raw = readAgentMessageContent(m);\n  if (typeof raw === 'string') return raw.trim();\n  if (Array.isArray(raw)) {\n    const parts: string[] = [];\n    for (const c of raw) {\n      if (c && typeof c === 'object') {\n        const o = c as unknown as Record<string, unknown>;\n        const type = typeof o.type === 'string' ? o.type : '';\n        if (type === 'toolCall' || type === 'tool_use' || type === 'tool_result') continue;\n        if (typeof o.text === 'string' && o.text.trim()) {\n          parts.push(o.text.trim());\n        }\n      }\n    }\n    return parts.join(' ').trim();\n  }\n  return '';\n}\n\nfunction firstUserText(messages: AgentMessage[]): string {\n  const u = messages.find((m) => m.role === 'user');\n  if (!u) return '';\n  const raw = extractTextFromMessage(u);\n  // User turns include `formatInboundFileTextBlock` text blocks; do not feed [File:…] into title LLM / fallback.\n  // Inbound pipeline / webchat prepends `[YYYY-MM-DD HH:MM TZ]`; strip so titles are not timestamp-led.\n  return stripInboundFileMetadataFromText(\n    stripEnvelopeTimestampPrefix(stripSessionStartupContextFromUserText(raw)),\n  );\n}\n\n/** First assistant message that has visible text (skips tool-only assistant rows). */\nfunction firstAssistantText(messages: AgentMessage[]): string {\n  for (const m of messages) {\n    if (m.role === 'assistant') {\n      const t = extractTextFromMessage(m);\n      if (t.length > 0) return t;\n    }\n  }\n  return '';\n}\n\nexport function isWebchatSessionKey(sessionKey: string): boolean {\n  const p = parseSessionKey(sessionKey);\n  if (p?.source === 'webchat') return true;\n  return sessionKey.includes(':webchat:');\n}\n\n/** Whether to run LLM/fallback session naming for this key (excludes cron, heartbeat). */\nexport function shouldAutoTitleSessionKey(sessionKey: string): boolean {\n  const raw = (sessionKey ?? '').trim();\n  if (!raw) return false;\n  if (isCronSessionKey(raw)) return false;\n  if (raw.toLowerCase().startsWith('heartbeat:')) return false;\n  return true;\n}\n\nexport function sanitizeSessionTitle(raw: string): string {\n  let s = raw.trim();\n  if ((s.startsWith('\"') && s.endsWith('\"')) || (s.startsWith(\"'\") && s.endsWith(\"'\"))) {\n    s = s.slice(1, -1).trim();\n  }\n  const lineBreak = s.indexOf('\\n');\n  if (lineBreak !== -1) s = s.slice(0, lineBreak).trim();\n  if (s.length > MAX_TITLE_LEN) s = s.slice(0, MAX_TITLE_LEN - 1).trimEnd() + '…';\n  return s;\n}\n\n/** Non-LLM title: first line of first user text, else first assistant line. */\nexport function fallbackTitleFromMessages(messages: AgentMessage[]): string | null {\n  const u = firstUserText(messages);\n  if (u) {\n    const line = u.split(/\\n/)[0]?.trim();\n    if (line) return sanitizeSessionTitle(line);\n  }\n  const a = firstAssistantText(messages);\n  if (a) {\n    const line = a.split(/\\n/)[0]?.trim();\n    if (line) return sanitizeSessionTitle(line);\n  }\n  return null;\n}\n\n/**\n * Returns a title string, or null if generation should be skipped or failed.\n */\nexport async function generateSessionTitleFromMessages(\n  modelRef: string,\n  messages: AgentMessage[],\n  signal?: AbortSignal,\n): Promise<string | null> {\n  const userText = firstUserText(messages);\n  const assistantText = firstAssistantText(messages);\n  if (!userText && !assistantText) return null;\n\n  let model: ReturnType<typeof resolveModel>;\n  try {\n    model = resolveModel(modelRef);\n  } catch (err) {\n    log.warn({ err, modelRef }, 'Cannot resolve model for session title');\n    return null;\n  }\n\n  const prompt =\n    userText && assistantText\n      ? `You label chat sessions. Given the first user message and the start of the assistant reply, output ONE short title (max 8 words). No quotes. No punctuation at the end. Use the same language as the user when possible.\n\nUser: ${userText.slice(0, 2000)}\n\nAssistant: ${assistantText.slice(0, 2000)}\n\nTitle:`\n      : userText\n        ? `The assistant reply only used tools (no visible text yet). Output ONE short title (max 8 words) based only on the user's first message. No quotes. No punctuation at the end. Use the same language as the user.\n\nUser: ${userText.slice(0, 2000)}\n\nTitle:`\n        : `Output ONE short title (max 8 words) for this assistant reply. No quotes. No punctuation at the end.\n\nAssistant: ${assistantText!.slice(0, 2000)}\n\nTitle:`;\n\n  const userMsg: UserMessage = { role: 'user', content: prompt, timestamp: Date.now() };\n\n  try {\n    const result = await complete(\n      model,\n      { messages: [userMsg] },\n      {\n        maxTokens: 64,\n        temperature: 0.35,\n        signal: signal as AbortSignal,\n      },\n    );\n\n    let text = '';\n    if (Array.isArray(result.content)) {\n      for (const c of result.content) {\n        if (c && typeof c === 'object' && (c as { type?: string }).type === 'text') {\n          text += String((c as { text?: string }).text || '');\n        }\n      }\n    }\n\n    const cleaned = sanitizeSessionTitle(text);\n    return cleaned.length > 0 ? cleaned : null;\n  } catch (err) {\n    log.warn({ err }, 'Session title LLM call failed');\n    return null;\n  }\n}\n\n/**\n * If the session is still unnamed, set `name` (LLM when possible, else first-line fallback).\n * Skips cron/heartbeat keys. Ensures index row exists by re-saving when metadata is missing (fixes index lag).\n */\nexport async function maybeAutoTitleSessionStore(\n  sessionStore: SessionStore,\n  sessionKey: string,\n  modelRef: string | undefined,\n): Promise<void> {\n  if (!shouldAutoTitleSessionKey(sessionKey)) return;\n\n  let messages = await sessionStore.load(sessionKey);\n  if (!messages.length) return;\n\n  let meta = await sessionStore.getMetadata(sessionKey);\n  if (!meta) {\n    await sessionStore.saveMessages(sessionKey, messages);\n    meta = await sessionStore.getMetadata(sessionKey);\n  }\n  if (!meta) {\n    log.warn({ sessionKey }, 'Session title: metadata missing after save');\n    return;\n  }\n  if (meta.name && meta.name.trim().length > 0) return;\n\n  let title: string | null = null;\n  const ref = modelRef?.trim();\n  if (ref) {\n    const controller = new AbortController();\n    const timeout = setTimeout(() => controller.abort(), 25_000);\n    try {\n      title = await generateSessionTitleFromMessages(ref, messages, controller.signal);\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n  if (!title) {\n    title = fallbackTitleFromMessages(messages);\n  }\n  if (!title) return;\n\n  try {\n    await sessionStore.updateMetadata(sessionKey, { name: title });\n  } catch (err) {\n    log.warn({ err, sessionKey }, 'Session title: updateMetadata failed');\n  }\n}\n"],"mappings":"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"}

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

@@ -89,6 +89,15 @@ export declare class SessionStore {
     loadTranscriptRows(key: string): Promise<TranscriptStoredRow[]>;
     getMetadata(key: string): Promise<SessionMetadata | null>;
     updateMetadata(key: string, updates: Partial<SessionMetadata>): Promise<void>;
+    /**
+     * Reset transcript for an existing session key: archive the current JSONL as
+     * `*.reset.*`, assign a new `sessionId`, and preserve per-session overrides
+     * on the disk entry (thinking/verbose) and in `sessions/config/*.json`.
+     */
+    reset(key: string): Promise<{
+        sessionId: string;
+        previousSessionId: string;
+    } | null>;
     delete(key: string): Promise<boolean>;
     deleteMany(keys: string[]): Promise<{
         success: string[];
@@ -112,8 +121,8 @@ export declare class SessionStore {
     syncSessionsJsonFromTranscriptUpdate(update: SessionTranscriptUpdate): Promise<void>;
     appendTranscriptContextEntry(key: string, entry: Omit<XopcTranscriptContextEntry, 'kind'> & Partial<Pick<XopcTranscriptContextEntry, 'kind'>>): Promise<void>;
     /**
-     * @deprecated Runtime agent turns must persist via {@link guardSessionManager} + appendMessage.
-     * Retained for compaction, tests, and admin tools until fully removed.
+     * Bulk write entry point used by compaction, tests, and admin tools.
+     * Runtime agent turns must persist via {@link guardSessionManager} + appendMessage.
      */
     saveMessages(key: string, messages: AgentMessage[]): Promise<void>;
     getWindowStats(messages: AgentMessage[]): {
@@ -152,8 +161,6 @@ export declare class SessionStore {
     load(key: string, options?: {
         fromArchive?: boolean;
     }): Promise<AgentMessage[]>;
-    /** @deprecated See {@link saveMessages}. */
-    save(key: string, messages: AgentMessage[]): Promise<void>;
     estimateTokenUsage(_key: string, messages: AgentMessage[]): Promise<number>;
     searchInSession(key: string, keyword: string): Promise<Message[]>;
     exportSession(key: string, format: ExportFormat): Promise<string>;

package/dist/src/session/store.js

@@ -452,6 +452,61 @@ var SessionStore = class {
 			}, "Session metadata updated");
 		});
 	}
+	/**
+	* Reset transcript for an existing session key: archive the current JSONL as
+	* `*.reset.*`, assign a new `sessionId`, and preserve per-session overrides
+	* on the disk entry (thinking/verbose) and in `sessions/config/*.json`.
+	*/
+	async reset(key) {
+		return this.runStoreMutation(async () => {
+			const existing = await this.getDiskEntry(key);
+			if (!existing?.pluginExtensions?.xopc?.metadata) return null;
+			const previousSessionId = existing.sessionId;
+			const keySessionsDir = this.resolveSessionsDirForKey(key);
+			const abs = this.transcriptPathForEntry(existing, keySessionsDir);
+			if (existsSync(abs)) try {
+				archiveFileOnDisk(abs, "reset");
+			} catch (err) {
+				log.warn({
+					err,
+					key
+				}, "Transcript archive on reset failed");
+			}
+			const sessionId = randomUUID();
+			validateSessionId(sessionId);
+			const now = Date.now();
+			await writeTranscriptJsonl({
+				absPath: resolveSessionTranscriptPathInDir(sessionId, keySessionsDir),
+				sessionId,
+				cwd: process.cwd(),
+				rows: []
+			});
+			await withSessionsJsonLock(this.resolveStorePathForKey(key), async (map) => {
+				const e = map[key];
+				if (!e?.pluginExtensions?.xopc?.metadata) return;
+				e.sessionId = sessionId;
+				e.sessionFile = `${sessionId}.jsonl`;
+				e.updatedAt = now;
+				e.sessionStartedAt = now;
+				e.lastInteractionAt = void 0;
+				patchSessionsJsonEntryStats(e, buildSessionsJsonStatsPatch(0, 0));
+				const meta = e.pluginExtensions.xopc.metadata;
+				meta.transcriptId = sessionId;
+				meta.updatedAt = new Date(now).toISOString();
+				map[key] = e;
+			});
+			invalidateSessionSearchIndexCache();
+			log.info({
+				key,
+				previousSessionId,
+				sessionId
+			}, "Session reset");
+			return {
+				sessionId,
+				previousSessionId
+			};
+		});
+	}
 	async delete(key) {
 		return this.runStoreMutation(async () => {
 			const entry = await this.getDiskEntry(key);
@@ -688,8 +743,8 @@ var SessionStore = class {
 		});
 	}
 	/**
-	* @deprecated Runtime agent turns must persist via {@link guardSessionManager} + appendMessage.
-	* Retained for compaction, tests, and admin tools until fully removed.
+	* Bulk write entry point used by compaction, tests, and admin tools.
+	* Runtime agent turns must persist via {@link guardSessionManager} + appendMessage.
 	*/
 	async saveMessages(key, messages) {
 		return this.runStoreMutation(async () => {
@@ -876,10 +931,6 @@ var SessionStore = class {
 	async load(key, options) {
 		return this.loadMessages(key, options);
 	}
-	/** @deprecated See {@link saveMessages}. */
-	async save(key, messages) {
-		return this.saveMessages(key, messages);
-	}
 	async estimateTokenUsage(_key, messages) {
 		return this.estimateTokens(messages);
 	}