@xopcai/xopc 0.0.30 → 0.0.31

package/dist/src/session/manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"manager.js","names":["EventEmitter"],"sources":["../../../src/session/manager.ts"],"sourcesContent":["// Session manager - high-level session management service\n\nimport EventEmitter from 'events';\nimport { createLogger } from '../utils/logger.js';\nimport { SessionStore } from './store.js';\nimport type {\n  SessionMetadata,\n  SessionDetail,\n  SessionListQuery,\n  PaginatedResult,\n  GlobalSessionStats,\n  ExportFormat,\n  SessionStatus,\n} from './types.js';\nimport type { Message } from './types.js';\nimport type { CompactionConfig, CompactionResult } from '../agent/memory/compaction.js';\nimport type { WindowConfig } from '../agent/memory/window.js';\nimport type { Config } from '../config/schema.js';\n\nconst log = createLogger('SessionManager');\n\nexport interface SessionManagerConfig {\n  config: Config;\n  agentId?: string;\n  sessionsDir?: string;\n  windowConfig?: Partial<WindowConfig>;\n  compactionConfig?: Partial<CompactionConfig>;\n}\n\nexport class SessionManager extends EventEmitter {\n  private store: SessionStore;\n\n  constructor(config: SessionManagerConfig) {\n    super();\n    this.store = new SessionStore(\n      {\n        config: config.config,\n        agentId: config.agentId,\n        sessionsDir: config.sessionsDir,\n      },\n      config.windowConfig,\n      config.compactionConfig\n    );\n  }\n\n  async initialize(): Promise<void> {\n    await this.store.initialize();\n    this.emit('ready');\n  }\n\n  /** Low-level store (e.g. cron resolving weixin delivery from session index). */\n  getStore(): SessionStore {\n    return this.store;\n  }\n\n  // ========== CRUD Operations ==========\n\n  async listSessions(query?: SessionListQuery): Promise<PaginatedResult<SessionMetadata>> {\n    return this.store.list(query);\n  }\n\n  /**\n   * List all subagent sessions.\n   * Subagent sessions have keys starting with 'subagent:'.\n   */\n  async listSubagents(query: SessionListQuery = {}): Promise<PaginatedResult<SessionMetadata>> {\n    // Filter for subagent sessions only\n    const subagentQuery: SessionListQuery = {\n      ...query,\n      search: query.search ? `subagent:${query.search}` : 'subagent:',\n    };\n    \n    const result = await this.store.list(subagentQuery);\n    \n    // Additional filtering to ensure only subagent sessions\n    const subagentSessions = result.items.filter((s) => s.key.startsWith('subagent:'));\n    \n    return {\n      ...result,\n      items: subagentSessions,\n      total: subagentSessions.length,\n      hasMore: false, // Simplified for now\n    };\n  }\n\n  async getSession(key: string): Promise<SessionDetail | null> {\n    const session = await this.store.get(key);\n    if (session) {\n      this.emit('sessionAccessed', { key });\n    }\n    return session;\n  }\n\n  async getSessionMetadata(key: string): Promise<SessionMetadata | null> {\n    return this.store.getMetadata(key);\n  }\n\n  async deleteSession(key: string): Promise<boolean> {\n    const result = await this.store.delete(key);\n    if (result) {\n      this.emit('sessionDeleted', { key });\n    }\n    return result;\n  }\n\n  async deleteSessions(keys: string[]): Promise<{ success: string[]; failed: string[] }> {\n    const result = await this.store.deleteMany(keys);\n    for (const key of result.success) {\n      this.emit('sessionDeleted', { key });\n    }\n    return result;\n  }\n\n  // ========== Metadata Updates ==========\n\n  async renameSession(key: string, name: string): Promise<void> {\n    await this.store.updateMetadata(key, { name });\n    this.emit('sessionUpdated', { key, name });\n  }\n\n  /** Partial metadata update (caller merges nested fields like `customData` when needed). */\n  async updateSessionMetadata(key: string, updates: Partial<SessionMetadata>): Promise<void> {\n    await this.store.updateMetadata(key, updates);\n    this.emit('sessionUpdated', { key });\n  }\n\n  async tagSession(key: string, tags: string[]): Promise<void> {\n    const existing = await this.store.getMetadata(key);\n    if (!existing) {\n      throw new Error(`Session not found: ${key}`);\n    }\n\n    // Merge tags, remove duplicates\n    const mergedTags = [...new Set([...existing.tags, ...tags])];\n    await this.store.updateMetadata(key, { tags: mergedTags });\n    this.emit('sessionUpdated', { key, tags: mergedTags });\n  }\n\n  async untagSession(key: string, tags: string[]): Promise<void> {\n    const existing = await this.store.getMetadata(key);\n    if (!existing) {\n      throw new Error(`Session not found: ${key}`);\n    }\n\n    const filteredTags = existing.tags.filter((t) => !tags.includes(t));\n    await this.store.updateMetadata(key, { tags: filteredTags });\n    this.emit('sessionUpdated', { key, tags: filteredTags });\n  }\n\n  async setSessionTags(key: string, tags: string[]): Promise<void> {\n    await this.store.updateMetadata(key, { tags: [...new Set(tags)] });\n    this.emit('sessionUpdated', { key, tags });\n  }\n\n  // ========== Status Management ==========\n\n  async archiveSession(key: string): Promise<void> {\n    await this.store.archive(key);\n    this.emit('sessionArchived', { key });\n  }\n\n  async unarchiveSession(key: string): Promise<void> {\n    await this.store.unarchive(key);\n    this.emit('sessionRestored', { key });\n  }\n\n  async pinSession(key: string): Promise<void> {\n    await this.store.pin(key);\n    this.emit('sessionPinned', { key });\n  }\n\n  async unpinSession(key: string): Promise<void> {\n    await this.store.unpin(key);\n    this.emit('sessionUnpinned', { key });\n  }\n\n  async setSessionStatus(key: string, status: SessionStatus): Promise<void> {\n    await this.store.setStatus(key, status);\n    this.emit('sessionStatusChanged', { key, status });\n  }\n\n  // ========== Search ==========\n\n  async searchSessions(query: string): Promise<SessionMetadata[]> {\n    const result = await this.store.list({ search: query, limit: 100 });\n    return result.items;\n  }\n\n  async searchInSession(key: string, keyword: string): Promise<Message[]> {\n    return this.store.searchInSession(key, keyword);\n  }\n\n  // ========== Export/Import ==========\n\n  async exportSession(key: string, format: ExportFormat): Promise<string> {\n    return this.store.exportSession(key, format);\n  }\n\n  // ========== Statistics ==========\n\n  async getStats(): Promise<GlobalSessionStats> {\n    return this.store.getStats();\n  }\n\n  // ========== Maintenance ==========\n\n  async archiveOldSessions(olderThanDays: number): Promise<number> {\n    const count = await this.store.archiveOld(olderThanDays);\n    log.info({ count, olderThanDays }, 'Archived old sessions');\n    return count;\n  }\n\n  // ========== Event Helpers ==========\n\n  onSessionCreated(callback: (metadata: SessionMetadata) => void): void {\n    this.on('sessionCreated', callback);\n  }\n\n  onSessionUpdated(callback: (data: { key: string; name?: string; tags?: string[] }) => void): void {\n    this.on('sessionUpdated', callback);\n  }\n\n  onSessionDeleted(callback: (data: { key: string }) => void): void {\n    this.on('sessionDeleted', callback);\n  }\n\n  onSessionArchived(callback: (data: { key: string }) => void): void {\n    this.on('sessionArchived', callback);\n  }\n\n  onSessionRestored(callback: (data: { key: string }) => void): void {\n    this.on('sessionRestored', callback);\n  }\n\n  onSessionPinned(callback: (data: { key: string }) => void): void {\n    this.on('sessionPinned', callback);\n  }\n\n  onSessionUnpinned(callback: (data: { key: string }) => void): void {\n    this.on('sessionUnpinned', callback);\n  }\n\n  onSessionStatusChanged(callback: (data: { key: string; status: SessionStatus }) => void): void {\n    this.on('sessionStatusChanged', callback);\n  }\n\n  onSessionAccessed(callback: (data: { key: string }) => void): void {\n    this.on('sessionAccessed', callback);\n  }\n\n  // ========== Store delegation (messages, compaction) ==========\n\n  /** Load messages for a session key */\n  async loadMessages(key: string) {\n    return this.store.loadMessages(key);\n  }\n\n  /** Save messages for a session key */\n  async saveMessages(key: string, messages: any[]) {\n    return this.store.saveMessages(key, messages);\n  }\n\n  /** Delete session data */\n  async delete(key: string): Promise<void> {\n    await this.store.delete(key);\n  }\n\n  /** Token/window stats for a message list */\n  getWindowStats(messages: any[]) {\n    return this.store.getWindowStats(messages);\n  }\n\n  /** Prepare compaction run */\n  prepareCompaction(key: string, messages: any[], contextWindow: number) {\n    return this.store.prepareCompaction(key, messages, contextWindow);\n  }\n\n  /** Compact session messages */\n  compact(\n    key: string,\n    messages: any[],\n    contextWindow: number,\n    instructions?: string,\n    force?: boolean,\n  ): Promise<CompactionResult> {\n    return this.store.compact(key, messages, contextWindow, instructions, force);\n  }\n\n  /** Compaction stats for a session */\n  async getCompactionStats(key: string) {\n    return this.store.getCompactionStats(key);\n  }\n\n  /** Estimate token usage for messages */\n  async estimateTokenUsage(key: string, messages: any[]): Promise<number> {\n    return this.store.estimateTokens(messages);\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"manager.js","names":["EventEmitter"],"sources":["../../../src/session/manager.ts"],"sourcesContent":["// Session manager - high-level session management service\n\nimport EventEmitter from 'events';\nimport { createLogger } from '../utils/logger.js';\nimport { SessionStore } from './store.js';\nimport type {\n  SessionMetadata,\n  SessionDetail,\n  SessionListQuery,\n  PaginatedResult,\n  GlobalSessionStats,\n  ExportFormat,\n  SessionStatus,\n} from './types.js';\nimport type { Message } from './types.js';\nimport type { CompactionConfig, CompactionResult } from '../agent/memory/compaction.js';\nimport type { XopcSessionTranscriptV1 } from './transcript-format.js';\nimport type { XopcTranscriptContextEntry } from './session-context-for-llm.js';\nimport { applySessionPatchToMetadata, type SessionPatchBody } from './patch-metadata.js';\nimport type { WindowConfig } from '../agent/memory/window.js';\nimport type { Config } from '../config/schema.js';\n\nconst log = createLogger('SessionManager');\n\nexport interface SessionManagerConfig {\n  config: Config;\n  agentId?: string;\n  sessionsDir?: string;\n  windowConfig?: Partial<WindowConfig>;\n  compactionConfig?: Partial<CompactionConfig>;\n}\n\nexport class SessionManager extends EventEmitter {\n  private store: SessionStore;\n\n  constructor(config: SessionManagerConfig) {\n    super();\n    this.store = new SessionStore(\n      {\n        config: config.config,\n        agentId: config.agentId,\n        sessionsDir: config.sessionsDir,\n      },\n      config.windowConfig,\n      config.compactionConfig\n    );\n  }\n\n  async initialize(): Promise<void> {\n    await this.store.initialize();\n    this.emit('ready');\n  }\n\n  /** Low-level store (e.g. cron resolving weixin delivery from session index). */\n  getStore(): SessionStore {\n    return this.store;\n  }\n\n  // ========== CRUD Operations ==========\n\n  async listSessions(query?: SessionListQuery): Promise<PaginatedResult<SessionMetadata>> {\n    return this.store.list(query);\n  }\n\n  /**\n   * List all subagent sessions.\n   * Subagent sessions have keys starting with 'subagent:'.\n   */\n  async listSubagents(query: SessionListQuery = {}): Promise<PaginatedResult<SessionMetadata>> {\n    // Filter for subagent sessions only\n    const subagentQuery: SessionListQuery = {\n      ...query,\n      search: query.search ? `subagent:${query.search}` : 'subagent:',\n    };\n    \n    const result = await this.store.list(subagentQuery);\n    \n    // Additional filtering to ensure only subagent sessions\n    const subagentSessions = result.items.filter((s) => s.key.startsWith('subagent:'));\n    \n    return {\n      ...result,\n      items: subagentSessions,\n      total: subagentSessions.length,\n      hasMore: false, // Simplified for now\n    };\n  }\n\n  async getSession(\n    key: string,\n    options?: { includeTranscriptSummary?: boolean; includeTranscriptRows?: boolean },\n  ): Promise<SessionDetail | null> {\n    const session = await this.store.get(key, options);\n    if (session) {\n      this.emit('sessionAccessed', { key });\n    }\n    return session;\n  }\n\n  /**\n   * OpenClaw-style `sessions.patch`: partial metadata (name, tags, customData shallow merge).\n   */\n  async patchSession(\n    key: string,\n    patch: SessionPatchBody,\n  ): Promise<{ ok: true } | { ok: false; error: string }> {\n    const meta = await this.store.getMetadata(key);\n    if (!meta) {\n      return { ok: false, error: 'Session not found' };\n    }\n    const updates = applySessionPatchToMetadata(meta, patch);\n    if (Object.keys(updates).length === 0) {\n      return { ok: true };\n    }\n    await this.store.updateMetadata(key, updates);\n    this.emit('sessionUpdated', { key });\n    return { ok: true };\n  }\n\n  async getSessionMetadata(key: string): Promise<SessionMetadata | null> {\n    return this.store.getMetadata(key);\n  }\n\n  async deleteSession(key: string): Promise<boolean> {\n    const result = await this.store.delete(key);\n    if (result) {\n      this.emit('sessionDeleted', { key });\n    }\n    return result;\n  }\n\n  async deleteSessions(keys: string[]): Promise<{ success: string[]; failed: string[] }> {\n    const result = await this.store.deleteMany(keys);\n    for (const key of result.success) {\n      this.emit('sessionDeleted', { key });\n    }\n    return result;\n  }\n\n  // ========== Metadata Updates ==========\n\n  async renameSession(key: string, name: string): Promise<void> {\n    await this.store.updateMetadata(key, { name });\n    this.emit('sessionUpdated', { key, name });\n  }\n\n  /** Partial metadata update (caller merges nested fields like `customData` when needed). */\n  async updateSessionMetadata(key: string, updates: Partial<SessionMetadata>): Promise<void> {\n    await this.store.updateMetadata(key, updates);\n    this.emit('sessionUpdated', { key });\n  }\n\n  async tagSession(key: string, tags: string[]): Promise<void> {\n    const existing = await this.store.getMetadata(key);\n    if (!existing) {\n      throw new Error(`Session not found: ${key}`);\n    }\n\n    // Merge tags, remove duplicates\n    const mergedTags = [...new Set([...existing.tags, ...tags])];\n    await this.store.updateMetadata(key, { tags: mergedTags });\n    this.emit('sessionUpdated', { key, tags: mergedTags });\n  }\n\n  async untagSession(key: string, tags: string[]): Promise<void> {\n    const existing = await this.store.getMetadata(key);\n    if (!existing) {\n      throw new Error(`Session not found: ${key}`);\n    }\n\n    const filteredTags = existing.tags.filter((t) => !tags.includes(t));\n    await this.store.updateMetadata(key, { tags: filteredTags });\n    this.emit('sessionUpdated', { key, tags: filteredTags });\n  }\n\n  async setSessionTags(key: string, tags: string[]): Promise<void> {\n    await this.store.updateMetadata(key, { tags: [...new Set(tags)] });\n    this.emit('sessionUpdated', { key, tags });\n  }\n\n  // ========== Status Management ==========\n\n  async archiveSession(key: string): Promise<void> {\n    await this.store.archive(key);\n    this.emit('sessionArchived', { key });\n  }\n\n  async unarchiveSession(key: string): Promise<void> {\n    await this.store.unarchive(key);\n    this.emit('sessionRestored', { key });\n  }\n\n  async pinSession(key: string): Promise<void> {\n    await this.store.pin(key);\n    this.emit('sessionPinned', { key });\n  }\n\n  async unpinSession(key: string): Promise<void> {\n    await this.store.unpin(key);\n    this.emit('sessionUnpinned', { key });\n  }\n\n  async setSessionStatus(key: string, status: SessionStatus): Promise<void> {\n    await this.store.setStatus(key, status);\n    this.emit('sessionStatusChanged', { key, status });\n  }\n\n  // ========== Search ==========\n\n  async searchSessions(query: string): Promise<SessionMetadata[]> {\n    const result = await this.store.list({ search: query, limit: 100 });\n    return result.items;\n  }\n\n  async searchInSession(key: string, keyword: string): Promise<Message[]> {\n    return this.store.searchInSession(key, keyword);\n  }\n\n  // ========== Export/Import ==========\n\n  async exportSession(key: string, format: ExportFormat): Promise<string> {\n    return this.store.exportSession(key, format);\n  }\n\n  // ========== Statistics ==========\n\n  async getStats(): Promise<GlobalSessionStats> {\n    return this.store.getStats();\n  }\n\n  // ========== Maintenance ==========\n\n  async archiveOldSessions(olderThanDays: number): Promise<number> {\n    const count = await this.store.archiveOld(olderThanDays);\n    log.info({ count, olderThanDays }, 'Archived old sessions');\n    return count;\n  }\n\n  // ========== Event Helpers ==========\n\n  onSessionCreated(callback: (metadata: SessionMetadata) => void): void {\n    this.on('sessionCreated', callback);\n  }\n\n  onSessionUpdated(callback: (data: { key: string; name?: string; tags?: string[] }) => void): void {\n    this.on('sessionUpdated', callback);\n  }\n\n  onSessionDeleted(callback: (data: { key: string }) => void): void {\n    this.on('sessionDeleted', callback);\n  }\n\n  onSessionArchived(callback: (data: { key: string }) => void): void {\n    this.on('sessionArchived', callback);\n  }\n\n  onSessionRestored(callback: (data: { key: string }) => void): void {\n    this.on('sessionRestored', callback);\n  }\n\n  onSessionPinned(callback: (data: { key: string }) => void): void {\n    this.on('sessionPinned', callback);\n  }\n\n  onSessionUnpinned(callback: (data: { key: string }) => void): void {\n    this.on('sessionUnpinned', callback);\n  }\n\n  onSessionStatusChanged(callback: (data: { key: string; status: SessionStatus }) => void): void {\n    this.on('sessionStatusChanged', callback);\n  }\n\n  onSessionAccessed(callback: (data: { key: string }) => void): void {\n    this.on('sessionAccessed', callback);\n  }\n\n  // ========== Store delegation (messages, compaction) ==========\n\n  /** Load messages for a session key */\n  async loadMessages(key: string) {\n    return this.store.loadMessages(key);\n  }\n\n  /** Wrapped transcript document (stable id, compaction history); null if missing or not a valid envelope. */\n  async loadTranscriptDocument(key: string): Promise<XopcSessionTranscriptV1 | null> {\n    return this.store.loadTranscriptDocument(key);\n  }\n\n  /** Save messages for a session key */\n  async saveMessages(key: string, messages: any[]) {\n    return this.store.saveMessages(key, messages);\n  }\n\n  /**\n   * Append `kind: 'context'` transcript row (persisted, excluded from {@link loadMessages} / LLM).\n   */\n  async appendTranscriptContextEntry(\n    key: string,\n    entry: Omit<XopcTranscriptContextEntry, 'kind'> & Partial<Pick<XopcTranscriptContextEntry, 'kind'>>,\n  ): Promise<void> {\n    await this.store.appendTranscriptContextEntry(key, entry);\n    this.emit('sessionUpdated', { key });\n  }\n\n  /** Delete session data */\n  async delete(key: string): Promise<void> {\n    await this.store.delete(key);\n  }\n\n  /** Token/window stats for a message list */\n  getWindowStats(messages: any[]) {\n    return this.store.getWindowStats(messages);\n  }\n\n  /** Prepare compaction run */\n  prepareCompaction(key: string, messages: any[], contextWindow: number) {\n    return this.store.prepareCompaction(key, messages, contextWindow);\n  }\n\n  /** Compact session messages */\n  compact(\n    key: string,\n    messages: any[],\n    contextWindow: number,\n    instructions?: string,\n    force?: boolean,\n  ): Promise<CompactionResult> {\n    return this.store.compact(key, messages, contextWindow, instructions, force);\n  }\n\n  /** Compaction stats for a session */\n  async getCompactionStats(key: string) {\n    return this.store.getCompactionStats(key);\n  }\n\n  /** List pre-compaction transcript snapshots (newest first). */\n  listCompactionCheckpoints(key: string) {\n    return this.store.listCompactionCheckpoints(key);\n  }\n\n  getCompactionCheckpointDetail(key: string, checkpointId: string) {\n    return this.store.getCompactionCheckpointDetail(key, checkpointId);\n  }\n\n  restoreCompactionCheckpoint(key: string, checkpointId: string) {\n    return this.store.restoreCompactionCheckpoint(key, checkpointId);\n  }\n\n  /** Estimate token usage for messages */\n  async estimateTokenUsage(key: string, messages: any[]): Promise<number> {\n    return this.store.estimateTokens(messages);\n  }\n}\n"],"mappings":"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"}

package/dist/src/session/patch-metadata.d.ts

@@ -0,0 +1,12 @@
+/**
+ * OpenClaw-style partial session row updates: merge tags and shallow-merge customData.
+ */
+import type { SessionMetadata } from './types.js';
+export type SessionPatchBody = {
+    name?: string;
+    tags?: string[];
+    /** When true, `tags` replaces the tag list; otherwise tags are union-merged. */
+    replaceTags?: boolean;
+    customData?: Record<string, unknown>;
+};
+export declare function applySessionPatchToMetadata(existing: SessionMetadata, patch: SessionPatchBody): Partial<SessionMetadata>;

package/dist/src/session/patch-metadata.js

@@ -0,0 +1,23 @@
+//#region src/session/patch-metadata.ts
+function applySessionPatchToMetadata(existing, patch) {
+	const out = {};
+	if (typeof patch.name === "string") {
+		const t = patch.name.trim();
+		if (t.length > 0) out.name = t;
+		else out.name = void 0;
+	}
+	if (patch.tags !== void 0 && Array.isArray(patch.tags)) {
+		const normalized = [...new Set(patch.tags.map((t) => String(t).trim()).filter(Boolean))];
+		if (patch.replaceTags) out.tags = normalized;
+		else out.tags = [...new Set([...existing.tags, ...normalized])];
+	}
+	if (patch.customData !== void 0 && typeof patch.customData === "object" && patch.customData !== null) out.customData = {
+		...existing.customData ?? {},
+		...patch.customData
+	};
+	return out;
+}
+//#endregion
+export { applySessionPatchToMetadata };
+
+//# sourceMappingURL=patch-metadata.js.map

package/dist/src/session/patch-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch-metadata.js","names":[],"sources":["../../../src/session/patch-metadata.ts"],"sourcesContent":["/**\n * OpenClaw-style partial session row updates: merge tags and shallow-merge customData.\n */\n\nimport type { SessionMetadata } from './types.js';\n\nexport type SessionPatchBody = {\n  name?: string;\n  tags?: string[];\n  /** When true, `tags` replaces the tag list; otherwise tags are union-merged. */\n  replaceTags?: boolean;\n  customData?: Record<string, unknown>;\n};\n\nexport function applySessionPatchToMetadata(\n  existing: SessionMetadata,\n  patch: SessionPatchBody,\n): Partial<SessionMetadata> {\n  const out: Partial<SessionMetadata> = {};\n\n  if (typeof patch.name === 'string') {\n    const t = patch.name.trim();\n    if (t.length > 0) {\n      out.name = t;\n    } else {\n      out.name = undefined;\n    }\n  }\n\n  if (patch.tags !== undefined && Array.isArray(patch.tags)) {\n    const normalized = [...new Set(patch.tags.map((t) => String(t).trim()).filter(Boolean))];\n    if (patch.replaceTags) {\n      out.tags = normalized;\n    } else {\n      out.tags = [...new Set([...existing.tags, ...normalized])];\n    }\n  }\n\n  if (patch.customData !== undefined && typeof patch.customData === 'object' && patch.customData !== null) {\n    out.customData = { ...(existing.customData ?? {}), ...patch.customData };\n  }\n\n  return out;\n}\n"],"mappings":";AAcA,SAAgB,4BACd,UACA,OAC0B;CAC1B,MAAM,MAAgC,EAAE;AAExC,KAAI,OAAO,MAAM,SAAS,UAAU;EAClC,MAAM,IAAI,MAAM,KAAK,MAAM;AAC3B,MAAI,EAAE,SAAS,EACb,KAAI,OAAO;MAEX,KAAI,OAAO,KAAA;;AAIf,KAAI,MAAM,SAAS,KAAA,KAAa,MAAM,QAAQ,MAAM,KAAK,EAAE;EACzD,MAAM,aAAa,CAAC,GAAG,IAAI,IAAI,MAAM,KAAK,KAAK,MAAM,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,OAAO,QAAQ,CAAC,CAAC;AACxF,MAAI,MAAM,YACR,KAAI,OAAO;MAEX,KAAI,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,SAAS,MAAM,GAAG,WAAW,CAAC,CAAC;;AAI9D,KAAI,MAAM,eAAe,KAAA,KAAa,OAAO,MAAM,eAAe,YAAY,MAAM,eAAe,KACjG,KAAI,aAAa;EAAE,GAAI,SAAS,cAAc,EAAE;EAAG,GAAG,MAAM;EAAY;AAG1E,QAAO"}

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

@@ -17,5 +17,7 @@ export declare class SessionSearchIndex {
     private extractSessionKeyFromPath;
     private findSessionJsonFiles;
     private buildWordIndex;
+    /** Index `kind: 'context'` `text` / `id` so session search matches audit rows (synthetic slot indices). */
+    private mergeContextTextIntoWordIndex;
     private mergeIntoGlobalIndex;
 }

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

@@ -1,5 +1,7 @@
 import { FILENAMES, init_paths } from "../config/paths.js";
 import { fileStemToSessionKey } from "./session-file-key.js";
+import { isTranscriptContextEntry } from "./session-context-for-llm.js";
+import { parseStoredTranscriptJson } from "./transcript-format.js";
 import { basename, join } from "node:path";
 import { readFile, readdir } from "node:fs/promises";
 //#region src/session/search-index.ts
@@ -19,10 +21,17 @@ var SessionSearchIndex = class {
 		const files = await this.findSessionJsonFiles(sessionsRoot);
 		for (const file of files) try {
 			const raw = await readFile(file, "utf-8");
-			const messages = JSON.parse(raw);
-			if (!Array.isArray(messages)) continue;
+			if (!raw.trim()) continue;
+			try {
+				JSON.parse(raw);
+			} catch {
+				continue;
+			}
+			const { messages, rows, envelope } = parseStoredTranscriptJson(raw);
+			if (!envelope) continue;
 			const key = this.extractSessionKeyFromPath(file);
 			const wordIndex = this.buildWordIndex(messages);
+			this.mergeContextTextIntoWordIndex(wordIndex, rows, messages.length);
 			const indexed = {
 				key,
 				messages,
@@ -84,6 +93,25 @@ var SessionSearchIndex = class {
 		}
 		return index;
 	}
+	/** Index `kind: 'context'` `text` / `id` so session search matches audit rows (synthetic slot indices). */
+	mergeContextTextIntoWordIndex(wordIndex, rows, llmMessageCount) {
+		let slot = 0;
+		for (const r of rows) {
+			if (!isTranscriptContextEntry(r)) continue;
+			const parts = [];
+			if (typeof r.text === "string" && r.text.trim()) parts.push(r.text);
+			if (typeof r.id === "string" && r.id.trim()) parts.push(r.id);
+			const blob = parts.join(" ");
+			if (!blob.trim()) continue;
+			const words = tokenizeWords(blob);
+			const idx = llmMessageCount + slot;
+			slot += 1;
+			for (const word of words) {
+				if (!wordIndex.has(word)) wordIndex.set(word, /* @__PURE__ */ new Set());
+				wordIndex.get(word).add(idx);
+			}
+		}
+	}
 	mergeIntoGlobalIndex(sessionKey, wordIndex) {
 		for (const word of wordIndex.keys()) {
 			if (!this.globalWordIndex.has(word)) this.globalWordIndex.set(word, /* @__PURE__ */ new Set());

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":"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"}

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
@@ -75,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>;
@@ -91,6 +98,10 @@ 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
@@ -98,8 +109,15 @@ export declare class SessionStore {
     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
@@ -145,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 */
@@ -156,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>;