@xopcai/xopc 0.0.29 → 0.0.31

package/dist/src/session/search-index.js.map

@@ -1 +1 @@
-{"version":3,"file":"search-index.js","names":[],"sources":["../../../src/session/search-index.ts"],"sourcesContent":["/**\n * In-memory inverted index over session transcript JSON files on disk.\n */\n\nimport { readdir, readFile } from 'node:fs/promises';\nimport { basename, join } from 'node:path';\n\nimport type { AgentMessage } from '@mariozechner/pi-agent-core';\n\nimport { FILENAMES } from '../config/paths.js';\nimport { fileStemToSessionKey } from './session-file-key.js';\n\ninterface IndexedSession {\n  key: string;\n  messages: AgentMessage[];\n  wordIndex: Map<string, Set<number>>;\n}\n\nexport class SessionSearchIndex {\n  private sessions = new Map<string, IndexedSession>();\n  private globalWordIndex = new Map<string, Set<string>>();\n\n  /**\n   * Scan `sessionsRoot` (same root as {@link SessionStore}: sharded `*.json`, excludes index/archive).\n   */\n  async buildIndex(sessionsRoot: string): Promise<void> {\n    this.sessions.clear();\n    this.globalWordIndex.clear();\n\n    const files = await this.findSessionJsonFiles(sessionsRoot);\n\n    for (const file of files) {\n      try {\n        const raw = await readFile(file, 'utf-8');\n        const messages = JSON.parse(raw) as AgentMessage[];\n        if (!Array.isArray(messages)) {\n          continue;\n        }\n\n        const key = this.extractSessionKeyFromPath(file);\n        const wordIndex = this.buildWordIndex(messages);\n\n        const indexed: IndexedSession = { key, messages, wordIndex };\n        this.sessions.set(key, indexed);\n        this.mergeIntoGlobalIndex(key, wordIndex);\n      } catch {\n        /* skip bad files */\n      }\n    }\n  }\n\n  search(query: string, limit = 10): Array<{ key: string; score: number }> {\n    const queryWords = tokenizeWords(query);\n\n    if (queryWords.length === 0) {\n      return [];\n    }\n\n    const scores = new Map<string, number>();\n\n    for (const word of queryWords) {\n      const matchingSessions = this.globalWordIndex.get(word);\n      if (!matchingSessions) {\n        continue;\n      }\n      for (const sessionKey of matchingSessions) {\n        scores.set(sessionKey, (scores.get(sessionKey) || 0) + 1);\n      }\n    }\n\n    return Array.from(scores.entries())\n      .map(([key, score]) => ({ key, score: score / queryWords.length }))\n      .sort((a, b) => b.score - a.score)\n      .slice(0, limit);\n  }\n\n  getSessionMessages(key: string): AgentMessage[] {\n    return this.sessions.get(key)?.messages ?? [];\n  }\n\n  private extractSessionKeyFromPath(filePath: string): string {\n    const base = basename(filePath, '.json');\n    return fileStemToSessionKey(base);\n  }\n\n  private async findSessionJsonFiles(dir: string): Promise<string[]> {\n    const files: string[] = [];\n\n    const walk = async (rel: string): Promise<void> => {\n      const abs = join(dir, rel);\n      let entries;\n      try {\n        entries = await readdir(abs, { withFileTypes: true });\n      } catch {\n        return;\n      }\n\n      for (const ent of entries) {\n        const childRel = rel ? join(rel, ent.name) : ent.name;\n        if (ent.isDirectory()) {\n          if (ent.name === 'archive') {\n            continue;\n          }\n          await walk(childRel);\n        } else if (\n          ent.name.endsWith('.json') &&\n          ent.name !== FILENAMES.SESSIONS_INDEX &&\n          !ent.name.endsWith('.meta.json')\n        ) {\n          files.push(join(dir, childRel));\n        }\n      }\n    };\n\n    await walk('');\n    return files;\n  }\n\n  private buildWordIndex(messages: AgentMessage[]): Map<string, Set<number>> {\n    const index = new Map<string, Set<number>>();\n\n    for (let i = 0; i < messages.length; i++) {\n      const text = extractIndexableText(messages[i]?.content);\n      const words = tokenizeWords(text);\n\n      for (const word of words) {\n        if (!index.has(word)) {\n          index.set(word, new Set());\n        }\n        index.get(word)!.add(i);\n      }\n    }\n\n    return index;\n  }\n\n  private mergeIntoGlobalIndex(sessionKey: string, wordIndex: Map<string, Set<number>>): void {\n    for (const word of wordIndex.keys()) {\n      if (!this.globalWordIndex.has(word)) {\n        this.globalWordIndex.set(word, new Set());\n      }\n      this.globalWordIndex.get(word)!.add(sessionKey);\n    }\n  }\n}\n\nfunction tokenizeWords(text: string): string[] {\n  return text\n    .toLowerCase()\n    .split(/\\W+/)\n    .map((w) => w.trim())\n    .filter(Boolean);\n}\n\nfunction extractIndexableText(content: unknown): string {\n  if (typeof content === 'string') {\n    return content;\n  }\n  if (!Array.isArray(content)) {\n    return '';\n  }\n  const parts: string[] = [];\n  for (const item of content) {\n    if (typeof item !== 'object' || item === null || !('type' in item)) {\n      continue;\n    }\n    const c = item as { type?: string; text?: string };\n    if (c.type === 'text' && typeof c.text === 'string') {\n      parts.push(c.text);\n    }\n  }\n  return parts.join(' ');\n}\n"],"mappings":"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"}
+{"version":3,"file":"search-index.js","names":[],"sources":["../../../src/session/search-index.ts"],"sourcesContent":["/**\n * In-memory inverted index over session transcript JSON files on disk.\n */\n\nimport { readdir, readFile } from 'node:fs/promises';\nimport { basename, join } from 'node:path';\n\nimport type { AgentMessage } from '@mariozechner/pi-agent-core';\n\nimport { FILENAMES } from '../config/paths.js';\nimport { fileStemToSessionKey } from './session-file-key.js';\nimport { parseStoredTranscriptJson } from './transcript-format.js';\nimport { isTranscriptContextEntry, type TranscriptStoredRow } from './session-context-for-llm.js';\n\ninterface IndexedSession {\n  key: string;\n  messages: AgentMessage[];\n  wordIndex: Map<string, Set<number>>;\n}\n\nexport class SessionSearchIndex {\n  private sessions = new Map<string, IndexedSession>();\n  private globalWordIndex = new Map<string, Set<string>>();\n\n  /**\n   * Scan `sessionsRoot` (same root as {@link SessionStore}: sharded `*.json`, excludes index/archive).\n   */\n  async buildIndex(sessionsRoot: string): Promise<void> {\n    this.sessions.clear();\n    this.globalWordIndex.clear();\n\n    const files = await this.findSessionJsonFiles(sessionsRoot);\n\n    for (const file of files) {\n      try {\n        const raw = await readFile(file, 'utf-8');\n        const trimmed = raw.trim();\n        if (!trimmed) {\n          continue;\n        }\n        try {\n          JSON.parse(raw);\n        } catch {\n          continue;\n        }\n        const { messages, rows, envelope } = parseStoredTranscriptJson(raw);\n        if (!envelope) {\n          continue;\n        }\n\n        const key = this.extractSessionKeyFromPath(file);\n        const wordIndex = this.buildWordIndex(messages);\n        this.mergeContextTextIntoWordIndex(wordIndex, rows, messages.length);\n\n        const indexed: IndexedSession = { key, messages, wordIndex };\n        this.sessions.set(key, indexed);\n        this.mergeIntoGlobalIndex(key, wordIndex);\n      } catch {\n        /* skip bad files */\n      }\n    }\n  }\n\n  search(query: string, limit = 10): Array<{ key: string; score: number }> {\n    const queryWords = tokenizeWords(query);\n\n    if (queryWords.length === 0) {\n      return [];\n    }\n\n    const scores = new Map<string, number>();\n\n    for (const word of queryWords) {\n      const matchingSessions = this.globalWordIndex.get(word);\n      if (!matchingSessions) {\n        continue;\n      }\n      for (const sessionKey of matchingSessions) {\n        scores.set(sessionKey, (scores.get(sessionKey) || 0) + 1);\n      }\n    }\n\n    return Array.from(scores.entries())\n      .map(([key, score]) => ({ key, score: score / queryWords.length }))\n      .sort((a, b) => b.score - a.score)\n      .slice(0, limit);\n  }\n\n  getSessionMessages(key: string): AgentMessage[] {\n    return this.sessions.get(key)?.messages ?? [];\n  }\n\n  private extractSessionKeyFromPath(filePath: string): string {\n    const base = basename(filePath, '.json');\n    return fileStemToSessionKey(base);\n  }\n\n  private async findSessionJsonFiles(dir: string): Promise<string[]> {\n    const files: string[] = [];\n\n    const walk = async (rel: string): Promise<void> => {\n      const abs = join(dir, rel);\n      let entries;\n      try {\n        entries = await readdir(abs, { withFileTypes: true });\n      } catch {\n        return;\n      }\n\n      for (const ent of entries) {\n        const childRel = rel ? join(rel, ent.name) : ent.name;\n        if (ent.isDirectory()) {\n          if (ent.name === 'archive') {\n            continue;\n          }\n          await walk(childRel);\n        } else if (\n          ent.name.endsWith('.json') &&\n          ent.name !== FILENAMES.SESSIONS_INDEX &&\n          !ent.name.endsWith('.meta.json')\n        ) {\n          files.push(join(dir, childRel));\n        }\n      }\n    };\n\n    await walk('');\n    return files;\n  }\n\n  private buildWordIndex(messages: AgentMessage[]): Map<string, Set<number>> {\n    const index = new Map<string, Set<number>>();\n\n    for (let i = 0; i < messages.length; i++) {\n      const text = extractIndexableText(messages[i]?.content);\n      const words = tokenizeWords(text);\n\n      for (const word of words) {\n        if (!index.has(word)) {\n          index.set(word, new Set());\n        }\n        index.get(word)!.add(i);\n      }\n    }\n\n    return index;\n  }\n\n  /** Index `kind: 'context'` `text` / `id` so session search matches audit rows (synthetic slot indices). */\n  private mergeContextTextIntoWordIndex(\n    wordIndex: Map<string, Set<number>>,\n    rows: TranscriptStoredRow[],\n    llmMessageCount: number,\n  ): void {\n    let slot = 0;\n    for (const r of rows) {\n      if (!isTranscriptContextEntry(r)) continue;\n      const parts: string[] = [];\n      if (typeof r.text === 'string' && r.text.trim()) parts.push(r.text);\n      if (typeof r.id === 'string' && r.id.trim()) parts.push(r.id);\n      const blob = parts.join(' ');\n      if (!blob.trim()) continue;\n      const words = tokenizeWords(blob);\n      const idx = llmMessageCount + slot;\n      slot += 1;\n      for (const word of words) {\n        if (!wordIndex.has(word)) {\n          wordIndex.set(word, new Set());\n        }\n        wordIndex.get(word)!.add(idx);\n      }\n    }\n  }\n\n  private mergeIntoGlobalIndex(sessionKey: string, wordIndex: Map<string, Set<number>>): void {\n    for (const word of wordIndex.keys()) {\n      if (!this.globalWordIndex.has(word)) {\n        this.globalWordIndex.set(word, new Set());\n      }\n      this.globalWordIndex.get(word)!.add(sessionKey);\n    }\n  }\n}\n\nfunction tokenizeWords(text: string): string[] {\n  return text\n    .toLowerCase()\n    .split(/\\W+/)\n    .map((w) => w.trim())\n    .filter(Boolean);\n}\n\nfunction extractIndexableText(content: unknown): string {\n  if (typeof content === 'string') {\n    return content;\n  }\n  if (!Array.isArray(content)) {\n    return '';\n  }\n  const parts: string[] = [];\n  for (const item of content) {\n    if (typeof item !== 'object' || item === null || !('type' in item)) {\n      continue;\n    }\n    const c = item as { type?: string; text?: string };\n    if (c.type === 'text' && typeof c.text === 'string') {\n      parts.push(c.text);\n    }\n  }\n  return parts.join(' ');\n}\n"],"mappings":";;;;;;;;;;YAS+C;AAW/C,IAAa,qBAAb,MAAgC;CAC9B,2BAAmB,IAAI,KAA6B;CACpD,kCAA0B,IAAI,KAA0B;;;;CAKxD,MAAM,WAAW,cAAqC;AACpD,OAAK,SAAS,OAAO;AACrB,OAAK,gBAAgB,OAAO;EAE5B,MAAM,QAAQ,MAAM,KAAK,qBAAqB,aAAa;AAE3D,OAAK,MAAM,QAAQ,MACjB,KAAI;GACF,MAAM,MAAM,MAAM,SAAS,MAAM,QAAQ;AAEzC,OAAI,CADY,IAAI,MACR,CACV;AAEF,OAAI;AACF,SAAK,MAAM,IAAI;WACT;AACN;;GAEF,MAAM,EAAE,UAAU,MAAM,aAAa,0BAA0B,IAAI;AACnE,OAAI,CAAC,SACH;GAGF,MAAM,MAAM,KAAK,0BAA0B,KAAK;GAChD,MAAM,YAAY,KAAK,eAAe,SAAS;AAC/C,QAAK,8BAA8B,WAAW,MAAM,SAAS,OAAO;GAEpE,MAAM,UAA0B;IAAE;IAAK;IAAU;IAAW;AAC5D,QAAK,SAAS,IAAI,KAAK,QAAQ;AAC/B,QAAK,qBAAqB,KAAK,UAAU;UACnC;;CAMZ,OAAO,OAAe,QAAQ,IAA2C;EACvE,MAAM,aAAa,cAAc,MAAM;AAEvC,MAAI,WAAW,WAAW,EACxB,QAAO,EAAE;EAGX,MAAM,yBAAS,IAAI,KAAqB;AAExC,OAAK,MAAM,QAAQ,YAAY;GAC7B,MAAM,mBAAmB,KAAK,gBAAgB,IAAI,KAAK;AACvD,OAAI,CAAC,iBACH;AAEF,QAAK,MAAM,cAAc,iBACvB,QAAO,IAAI,aAAa,OAAO,IAAI,WAAW,IAAI,KAAK,EAAE;;AAI7D,SAAO,MAAM,KAAK,OAAO,SAAS,CAAC,CAChC,KAAK,CAAC,KAAK,YAAY;GAAE;GAAK,OAAO,QAAQ,WAAW;GAAQ,EAAE,CAClE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,CACjC,MAAM,GAAG,MAAM;;CAGpB,mBAAmB,KAA6B;AAC9C,SAAO,KAAK,SAAS,IAAI,IAAI,EAAE,YAAY,EAAE;;CAG/C,0BAAkC,UAA0B;AAE1D,SAAO,qBADM,SAAS,UAAU,QACA,CAAC;;CAGnC,MAAc,qBAAqB,KAAgC;EACjE,MAAM,QAAkB,EAAE;EAE1B,MAAM,OAAO,OAAO,QAA+B;GACjD,MAAM,MAAM,KAAK,KAAK,IAAI;GAC1B,IAAI;AACJ,OAAI;AACF,cAAU,MAAM,QAAQ,KAAK,EAAE,eAAe,MAAM,CAAC;WAC/C;AACN;;AAGF,QAAK,MAAM,OAAO,SAAS;IACzB,MAAM,WAAW,MAAM,KAAK,KAAK,IAAI,KAAK,GAAG,IAAI;AACjD,QAAI,IAAI,aAAa,EAAE;AACrB,SAAI,IAAI,SAAS,UACf;AAEF,WAAM,KAAK,SAAS;eAEpB,IAAI,KAAK,SAAS,QAAQ,IAC1B,IAAI,SAAS,UAAU,kBACvB,CAAC,IAAI,KAAK,SAAS,aAAa,CAEhC,OAAM,KAAK,KAAK,KAAK,SAAS,CAAC;;;AAKrC,QAAM,KAAK,GAAG;AACd,SAAO;;CAGT,eAAuB,UAAoD;EACzE,MAAM,wBAAQ,IAAI,KAA0B;AAE5C,OAAK,IAAI,IAAI,GAAG,IAAI,SAAS,QAAQ,KAAK;GAExC,MAAM,QAAQ,cADD,qBAAqB,SAAS,IAAI,QACf,CAAC;AAEjC,QAAK,MAAM,QAAQ,OAAO;AACxB,QAAI,CAAC,MAAM,IAAI,KAAK,CAClB,OAAM,IAAI,sBAAM,IAAI,KAAK,CAAC;AAE5B,UAAM,IAAI,KAAK,CAAE,IAAI,EAAE;;;AAI3B,SAAO;;;CAIT,8BACE,WACA,MACA,iBACM;EACN,IAAI,OAAO;AACX,OAAK,MAAM,KAAK,MAAM;AACpB,OAAI,CAAC,yBAAyB,EAAE,CAAE;GAClC,MAAM,QAAkB,EAAE;AAC1B,OAAI,OAAO,EAAE,SAAS,YAAY,EAAE,KAAK,MAAM,CAAE,OAAM,KAAK,EAAE,KAAK;AACnE,OAAI,OAAO,EAAE,OAAO,YAAY,EAAE,GAAG,MAAM,CAAE,OAAM,KAAK,EAAE,GAAG;GAC7D,MAAM,OAAO,MAAM,KAAK,IAAI;AAC5B,OAAI,CAAC,KAAK,MAAM,CAAE;GAClB,MAAM,QAAQ,cAAc,KAAK;GACjC,MAAM,MAAM,kBAAkB;AAC9B,WAAQ;AACR,QAAK,MAAM,QAAQ,OAAO;AACxB,QAAI,CAAC,UAAU,IAAI,KAAK,CACtB,WAAU,IAAI,sBAAM,IAAI,KAAK,CAAC;AAEhC,cAAU,IAAI,KAAK,CAAE,IAAI,IAAI;;;;CAKnC,qBAA6B,YAAoB,WAA2C;AAC1F,OAAK,MAAM,QAAQ,UAAU,MAAM,EAAE;AACnC,OAAI,CAAC,KAAK,gBAAgB,IAAI,KAAK,CACjC,MAAK,gBAAgB,IAAI,sBAAM,IAAI,KAAK,CAAC;AAE3C,QAAK,gBAAgB,IAAI,KAAK,CAAE,IAAI,WAAW;;;;AAKrD,SAAS,cAAc,MAAwB;AAC7C,QAAO,KACJ,aAAa,CACb,MAAM,MAAM,CACZ,KAAK,MAAM,EAAE,MAAM,CAAC,CACpB,OAAO,QAAQ;;AAGpB,SAAS,qBAAqB,SAA0B;AACtD,KAAI,OAAO,YAAY,SACrB,QAAO;AAET,KAAI,CAAC,MAAM,QAAQ,QAAQ,CACzB,QAAO;CAET,MAAM,QAAkB,EAAE;AAC1B,MAAK,MAAM,QAAQ,SAAS;AAC1B,MAAI,OAAO,SAAS,YAAY,SAAS,QAAQ,EAAE,UAAU,MAC3D;EAEF,MAAM,IAAI;AACV,MAAI,EAAE,SAAS,UAAU,OAAO,EAAE,SAAS,SACzC,OAAM,KAAK,EAAE,KAAK;;AAGtB,QAAO,MAAM,KAAK,IAAI"}

package/dist/src/session/session-context-for-llm.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Transcript rows persisted on disk may include non-LLM entries (e.g. `kind: 'context'`).
+ * {@link buildSessionContextForLlm} is the single choke point for provider-facing history.
+ *
+ * Do not pass raw `parseStoredTranscriptJson(...).rows` into pi-agent / providers — always run
+ * {@link buildSessionContextForLlm} first (or use {@link SessionStore.loadMessages}, which already does).
+ */
+import type { AgentMessage } from '@mariozechner/pi-agent-core';
+/** Persisted-only row: never sent to the model as a chat message. */
+export interface XopcTranscriptContextEntry {
+    kind: 'context';
+    id?: string;
+    /** Short human-readable line for UIs / logs. */
+    text?: string;
+    /** Structured payload (tool summaries, delivery metadata, etc.). */
+    data?: Record<string, unknown>;
+    createdAt?: string;
+}
+export type TranscriptStoredRow = AgentMessage | XopcTranscriptContextEntry;
+export declare function isTranscriptContextEntry(x: unknown): x is XopcTranscriptContextEntry;
+/**
+ * Normalize a JSON array from on-disk transcript into stored rows (drops unrecognized objects).
+ */
+export declare function transcriptRowsFromJsonArray(arr: unknown[]): TranscriptStoredRow[];
+/** Messages only — what providers and pi-agent should see. */
+export declare function buildSessionContextForLlm(rows: TranscriptStoredRow[]): AgentMessage[];
+/**
+ * When persisting LLM messages, keep prior `kind: 'context'` rows in their relative positions:
+ * each non-context slot in the previous file is replaced by the next incoming LLM message;
+ * trailing new LLM rows are appended. Extra old LLM rows are dropped if the new list is shorter.
+ */
+export declare function mergeLlmMessagesPreservingContextRows(prevRows: TranscriptStoredRow[], llmMessages: AgentMessage[]): TranscriptStoredRow[];

package/dist/src/session/session-context-for-llm.js

@@ -0,0 +1,60 @@
+//#region src/session/session-context-for-llm.ts
+function isTranscriptContextEntry(x) {
+	if (!x || typeof x !== "object") return false;
+	return x.kind === "context";
+}
+const LLM_ROLES = new Set([
+	"user",
+	"assistant",
+	"system",
+	"tool",
+	"toolResult"
+]);
+function isLikelyAgentMessage(x) {
+	if (!x || typeof x !== "object") return false;
+	const role = x.role;
+	return typeof role === "string" && LLM_ROLES.has(role);
+}
+/**
+* Normalize a JSON array from on-disk transcript into stored rows (drops unrecognized objects).
+*/
+function transcriptRowsFromJsonArray(arr) {
+	const out = [];
+	for (const x of arr) {
+		if (isTranscriptContextEntry(x)) {
+			out.push(x);
+			continue;
+		}
+		if (isLikelyAgentMessage(x)) out.push(x);
+	}
+	return out;
+}
+/** Messages only — what providers and pi-agent should see. */
+function buildSessionContextForLlm(rows) {
+	const out = [];
+	for (const r of rows) if (!isTranscriptContextEntry(r)) out.push(r);
+	return out;
+}
+/**
+* When persisting LLM messages, keep prior `kind: 'context'` rows in their relative positions:
+* each non-context slot in the previous file is replaced by the next incoming LLM message;
+* trailing new LLM rows are appended. Extra old LLM rows are dropped if the new list is shorter.
+*/
+function mergeLlmMessagesPreservingContextRows(prevRows, llmMessages) {
+	let i = 0;
+	const out = [];
+	for (const r of prevRows) if (isTranscriptContextEntry(r)) out.push(r);
+	else if (i < llmMessages.length) {
+		out.push(llmMessages[i]);
+		i += 1;
+	}
+	while (i < llmMessages.length) {
+		out.push(llmMessages[i]);
+		i += 1;
+	}
+	return out;
+}
+//#endregion
+export { buildSessionContextForLlm, isTranscriptContextEntry, mergeLlmMessagesPreservingContextRows, transcriptRowsFromJsonArray };
+
+//# sourceMappingURL=session-context-for-llm.js.map

package/dist/src/session/session-context-for-llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-context-for-llm.js","names":[],"sources":["../../../src/session/session-context-for-llm.ts"],"sourcesContent":["/**\n * Transcript rows persisted on disk may include non-LLM entries (e.g. `kind: 'context'`).\n * {@link buildSessionContextForLlm} is the single choke point for provider-facing history.\n *\n * Do not pass raw `parseStoredTranscriptJson(...).rows` into pi-agent / providers — always run\n * {@link buildSessionContextForLlm} first (or use {@link SessionStore.loadMessages}, which already does).\n */\n\nimport type { AgentMessage } from '@mariozechner/pi-agent-core';\n\n/** Persisted-only row: never sent to the model as a chat message. */\nexport interface XopcTranscriptContextEntry {\n  kind: 'context';\n  id?: string;\n  /** Short human-readable line for UIs / logs. */\n  text?: string;\n  /** Structured payload (tool summaries, delivery metadata, etc.). */\n  data?: Record<string, unknown>;\n  createdAt?: string;\n}\n\nexport type TranscriptStoredRow = AgentMessage | XopcTranscriptContextEntry;\n\nexport function isTranscriptContextEntry(x: unknown): x is XopcTranscriptContextEntry {\n  if (!x || typeof x !== 'object') return false;\n  return (x as Record<string, unknown>).kind === 'context';\n}\n\nconst LLM_ROLES = new Set(['user', 'assistant', 'system', 'tool', 'toolResult']);\n\nfunction isLikelyAgentMessage(x: unknown): x is AgentMessage {\n  if (!x || typeof x !== 'object') return false;\n  const role = (x as Record<string, unknown>).role;\n  return typeof role === 'string' && LLM_ROLES.has(role);\n}\n\n/**\n * Normalize a JSON array from on-disk transcript into stored rows (drops unrecognized objects).\n */\nexport function transcriptRowsFromJsonArray(arr: unknown[]): TranscriptStoredRow[] {\n  const out: TranscriptStoredRow[] = [];\n  for (const x of arr) {\n    if (isTranscriptContextEntry(x)) {\n      out.push(x);\n      continue;\n    }\n    if (isLikelyAgentMessage(x)) {\n      out.push(x);\n    }\n  }\n  return out;\n}\n\n/** Messages only — what providers and pi-agent should see. */\nexport function buildSessionContextForLlm(rows: TranscriptStoredRow[]): AgentMessage[] {\n  const out: AgentMessage[] = [];\n  for (const r of rows) {\n    if (!isTranscriptContextEntry(r)) {\n      out.push(r);\n    }\n  }\n  return out;\n}\n\n/**\n * When persisting LLM messages, keep prior `kind: 'context'` rows in their relative positions:\n * each non-context slot in the previous file is replaced by the next incoming LLM message;\n * trailing new LLM rows are appended. Extra old LLM rows are dropped if the new list is shorter.\n */\nexport function mergeLlmMessagesPreservingContextRows(\n  prevRows: TranscriptStoredRow[],\n  llmMessages: AgentMessage[],\n): TranscriptStoredRow[] {\n  let i = 0;\n  const out: TranscriptStoredRow[] = [];\n  for (const r of prevRows) {\n    if (isTranscriptContextEntry(r)) {\n      out.push(r);\n    } else {\n      if (i < llmMessages.length) {\n        out.push(llmMessages[i]);\n        i += 1;\n      }\n    }\n  }\n  while (i < llmMessages.length) {\n    out.push(llmMessages[i]);\n    i += 1;\n  }\n  return out;\n}\n"],"mappings":";AAuBA,SAAgB,yBAAyB,GAA6C;AACpF,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;AACxC,QAAQ,EAA8B,SAAS;;AAGjD,MAAM,YAAY,IAAI,IAAI;CAAC;CAAQ;CAAa;CAAU;CAAQ;CAAa,CAAC;AAEhF,SAAS,qBAAqB,GAA+B;AAC3D,KAAI,CAAC,KAAK,OAAO,MAAM,SAAU,QAAO;CACxC,MAAM,OAAQ,EAA8B;AAC5C,QAAO,OAAO,SAAS,YAAY,UAAU,IAAI,KAAK;;;;;AAMxD,SAAgB,4BAA4B,KAAuC;CACjF,MAAM,MAA6B,EAAE;AACrC,MAAK,MAAM,KAAK,KAAK;AACnB,MAAI,yBAAyB,EAAE,EAAE;AAC/B,OAAI,KAAK,EAAE;AACX;;AAEF,MAAI,qBAAqB,EAAE,CACzB,KAAI,KAAK,EAAE;;AAGf,QAAO;;;AAIT,SAAgB,0BAA0B,MAA6C;CACrF,MAAM,MAAsB,EAAE;AAC9B,MAAK,MAAM,KAAK,KACd,KAAI,CAAC,yBAAyB,EAAE,CAC9B,KAAI,KAAK,EAAE;AAGf,QAAO;;;;;;;AAQT,SAAgB,sCACd,UACA,aACuB;CACvB,IAAI,IAAI;CACR,MAAM,MAA6B,EAAE;AACrC,MAAK,MAAM,KAAK,SACd,KAAI,yBAAyB,EAAE,CAC7B,KAAI,KAAK,EAAE;UAEP,IAAI,YAAY,QAAQ;AAC1B,MAAI,KAAK,YAAY,GAAG;AACxB,OAAK;;AAIX,QAAO,IAAI,YAAY,QAAQ;AAC7B,MAAI,KAAK,YAAY,GAAG;AACxB,OAAK;;AAEP,QAAO"}

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

@@ -1,10 +1,12 @@
 import type { Config } from '../config/schema.js';
 import type { AgentMessage } from '@mariozechner/pi-agent-core';
-import type { SessionMetadata, SessionDetail, SessionListQuery, PaginatedResult, GlobalSessionStats, ExportFormat } from './types.js';
+import type { SessionMetadata, SessionDetail, SessionListQuery, PaginatedResult, GlobalSessionStats, ExportFormat, CompactionCheckpointSummary, CompactionCheckpointDetail } from './types.js';
 import { SessionStatus } from './types.js';
 import type { Message } from './types.js';
 import { type CompactionConfig, type CompactionResult } from '../agent/memory/compaction.js';
 import { type WindowConfig } from '../agent/memory/window.js';
+import { type XopcSessionTranscriptV1 } from './transcript-format.js';
+import { type TranscriptStoredRow, type XopcTranscriptContextEntry } from './session-context-for-llm.js';
 /**
  * Session files live under `resolveSessionsDir(config, agentId)` (ADR-003), sharded by
  * `resolveSessionShardRelativePath(sessionKey)` (users/… vs system/heartbeat; web UI uses
@@ -27,11 +29,24 @@ export declare class SessionStore {
     private indexDirty;
     private window;
     private compactor;
+    /** Serialize index + transcript mutations (reentrant for nested store calls). */
+    private storeMutationChain;
+    private storeMutationDepth;
     constructor(options: SessionStoreOptions, windowConfig?: Partial<WindowConfig>, compactionConfig?: Partial<CompactionConfig>);
     /** Root directory of session JSON files (sharded). Used by `session_search` indexing. */
     getSessionsRoot(): string;
     initialize(): Promise<void>;
     private sessionPathsForKey;
+    private invalidateIndexCache;
+    /**
+     * Serialize mutations that touch the sessions index or transcript paths.
+     * Reentrant: nested calls (e.g. applyCompaction → saveMessages) run inline without deadlocking.
+     */
+    private runStoreMutation;
+    private checkpointBasenamePrefix;
+    private pruneCompactionCheckpoints;
+    /** Best-effort copy of the current transcript before compaction replaces it. */
+    private captureCompactionCheckpointIfExists;
     /**
      * Get sessions by agent ID
      */
@@ -62,7 +77,12 @@ export declare class SessionStore {
      */
     private extractRoutingFromKey;
     list(query?: SessionListQuery): Promise<PaginatedResult<SessionMetadata>>;
-    get(key: string): Promise<SessionDetail | null>;
+    get(key: string, options?: {
+        includeTranscriptSummary?: boolean;
+        includeTranscriptRows?: boolean;
+    }): Promise<SessionDetail | null>;
+    /** Full on-disk transcript rows (LLM messages + optional `kind: 'context'`). */
+    loadTranscriptRows(key: string): Promise<TranscriptStoredRow[]>;
     getMetadata(key: string): Promise<SessionMetadata | null>;
     updateMetadata(key: string, updates: Partial<SessionMetadata>): Promise<void>;
     delete(key: string): Promise<boolean>;
@@ -78,11 +98,26 @@ export declare class SessionStore {
     loadMessages(key: string, options?: {
         fromArchive?: boolean;
     }): Promise<AgentMessage[]>;
+    /**
+     * Load the versioned transcript document (stable id, compaction history), or null if missing/invalid.
+     */
+    loadTranscriptDocument(key: string): Promise<XopcSessionTranscriptV1 | null>;
     /**
      * Find the most recent archived session file for a given key.
      * Archived files have format: {safeKey}.{timestamp}.json
      */
     private findMostRecentArchive;
+    /**
+     * Persist transcript JSON + merge session row into the index. Caller must hold {@link runStoreMutation} (or be nested under it).
+     * Transcript is stored as a versioned document (pi-style header) with stable {@link XopcSessionTranscriptV1.id}.
+     */
+    private writeSessionTranscriptFromStoredRows;
+    private writeSessionTranscriptAndUpdateIndex;
+    /**
+     * Append a persisted-only transcript row (`kind: 'context'`), visible on disk and in session search
+     * after stripping, but never returned from {@link loadMessages}.
+     */
+    appendTranscriptContextEntry(key: string, entry: Omit<XopcTranscriptContextEntry, 'kind'> & Partial<Pick<XopcTranscriptContextEntry, 'kind'>>): Promise<void>;
     saveMessages(key: string, messages: AgentMessage[]): Promise<void>;
     /**
      * Get window stats for messages
@@ -128,6 +163,19 @@ export declare class SessionStore {
         totalTokensAfter: number;
         lastCompactionAt: any;
     }>;
+    /**
+     * List pre-compaction transcript snapshots for a session (newest first).
+     */
+    listCompactionCheckpoints(key: string): Promise<CompactionCheckpointSummary[]>;
+    /**
+     * Metadata for a single compaction checkpoint file.
+     */
+    getCompactionCheckpointDetail(key: string, checkpointId: string): Promise<CompactionCheckpointDetail | null>;
+    /**
+     * Restore main transcript from a pre-compaction snapshot (then re-wrap + index sync).
+     * Does not delete the checkpoint file.
+     */
+    restoreCompactionCheckpoint(key: string, checkpointId: string): Promise<void>;
     /** Alias for delete */
     deleteSession(key: string): Promise<boolean>;
     /** Alias for loadMessages */
@@ -139,6 +187,9 @@ export declare class SessionStore {
     /** Alias for estimateTokens */
     estimateTokenUsage(key: string, messages: AgentMessage[]): Promise<number>;
     searchInSession(key: string, keyword: string): Promise<Message[]>;
+    /**
+     * JSON export includes API-shaped `messages` (LLM-only) plus `transcriptRows` (full on-disk order).
+     */
     exportSession(key: string, format: ExportFormat): Promise<string>;
     getStats(): Promise<GlobalSessionStats>;
     archiveOld(olderThanDays: number): Promise<number>;