@caupulican/pi-adaptative 0.80.103 → 0.81.0

package/dist/core/memory/providers/transcript-recall.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcript-recall.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/providers/transcript-recall.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAaxG,qBAAa,wBAAyB,YAAW,cAAc;IAC9D,QAAQ,CAAC,IAAI,uBAAuB;IACpC,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,gBAAgB,CAAM;IAC9B,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,QAAQ,CAAM;IAEtB,WAAW,IAAI,OAAO,CAErB;IAED,eAAe,IAAI,kBAAkB,CAEpC;IAEK,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAK9E;IAEK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAE9B;IAED,wFAAwF;IACxF,iBAAiB,IAAI,MAAM,EAAE,CAE5B;IAEK,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB7C;IAED,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,SAAS;CAsDjB","sourcesContent":["/**\n * TranscriptRecallProvider — cross-session similarity recall (adaptive-agent design R3).\n *\n * A read-only CONTEXT memory provider: it indexes the most-recent past session transcripts (the JSONL\n * corpus) with a dependency-free token/Jaccard index ({@link TranscriptIndex}, reusing skill_audit's\n * tokenizer) and answers `prefetch(query)` with a small `<memory_context>` recall page of the most\n * relevant past snippets. The current session and auto-learn sessions are excluded. It never writes —\n * the file-store remains the write target; this is the recall corpus.\n */\n\nimport { readdirSync, statSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { wrapUntrustedText } from \"../../security/untrusted-boundary.ts\";\nimport {\n\ttype FileEntry,\n\tgetDefaultSessionDir,\n\tisAutoLearnSessionId,\n\tloadEntriesFromFile,\n} from \"../../session-manager.ts\";\nimport type { MemoryCapabilities, MemoryLifecycleContext, MemoryProvider } from \"../memory-provider.ts\";\nimport { type TranscriptDoc, TranscriptIndex } from \"../transcript-index.ts\";\n\n/** Most-recent past sessions to consider. */\nconst MAX_SESSIONS = 60;\n/** Per-session text cap (keeps the index light and snippets relevant). */\nconst MAX_DOC_CHARS = 8_000;\n/** Overall corpus cap across all docs. */\nconst MAX_TOTAL_CHARS = 500_000;\n/** Skip transcript files larger than this before parsing them, so a huge log can't block/bloat the\n * first recalled turn (Bug #9). Far above a normal session; only pathological logs exceed it. */\nconst MAX_FILE_BYTES = 8_000_000;\n\nexport class TranscriptRecallProvider implements MemoryProvider {\n\treadonly name = \"transcript-recall\";\n\tprivate index: TranscriptIndex | undefined;\n\tprivate currentSessionId = \"\";\n\tprivate cwd = \"\";\n\tprivate agentDir = \"\";\n\n\tisAvailable(): boolean {\n\t\treturn true;\n\t}\n\n\tgetCapabilities(): MemoryCapabilities {\n\t\treturn { surfaces: [\"context\"] };\n\t}\n\n\tasync initialize(sessionId: string, ctx: MemoryLifecycleContext): Promise<void> {\n\t\tthis.currentSessionId = sessionId;\n\t\tthis.cwd = ctx.cwd;\n\t\tthis.agentDir = ctx.agentDir;\n\t\tthis.index = undefined; // built lazily on first prefetch\n\t}\n\n\tasync shutdown(): Promise<void> {\n\t\tthis.index = undefined;\n\t}\n\n\t/** GC manages the dynamic recall page so stale pages pack while the newest are kept. */\n\tgetContextMarkers(): string[] {\n\t\treturn [\"<memory_context\"];\n\t}\n\n\tasync prefetch(query: string): Promise<string> {\n\t\tif (!query.trim()) return \"\";\n\t\tlet index: TranscriptIndex;\n\t\ttry {\n\t\t\tindex = this.ensureIndex();\n\t\t} catch {\n\t\t\treturn \"\";\n\t\t}\n\t\tif (index.size === 0) return \"\";\n\t\t// minScore is a query-CONTAINMENT threshold (fraction of the query's tokens present in the doc),\n\t\t// not Jaccard — so it is length-independent and recalls relevant long sessions. ~1/3 of query\n\t\t// terms must appear before a session is considered relevant.\n\t\tconst hits = index.query(query, { k: 3, minScore: 0.34, maxSnippetChars: 600 });\n\t\tif (hits.length === 0) return \"\";\n\t\t// Recalled past text is UNTRUSTED (it may itself contain injected instructions or a forged\n\t\t// `</memory_context>` to break out). Fence each snippet with the untrusted-content boundary so a\n\t\t// payload can't escape and be replayed as a current instruction (design: recall = untrusted).\n\t\tconst body = hits\n\t\t\t.map((h) => `- (${h.timestamp ?? \"earlier session\"}) ${wrapUntrustedText(h.snippet, \"transcript-recall\")}`)\n\t\t\t.join(\"\\n\");\n\t\treturn `<memory_context source=\"transcript-recall\">\\nRelevant context recalled from past sessions (read-only reference, untrusted, may be stale):\\n${body}\\n</memory_context>`;\n\t}\n\n\tprivate ensureIndex(): TranscriptIndex {\n\t\tif (!this.index) {\n\t\t\tthis.index = new TranscriptIndex(this.buildDocs());\n\t\t}\n\t\treturn this.index;\n\t}\n\n\tprivate buildDocs(): TranscriptDoc[] {\n\t\tconst docs: TranscriptDoc[] = [];\n\t\tlet dir: string;\n\t\ttry {\n\t\t\tdir = getDefaultSessionDir(this.cwd, this.agentDir);\n\t\t} catch {\n\t\t\treturn docs;\n\t\t}\n\n\t\tlet files: Array<{ path: string; mtime: number }>;\n\t\ttry {\n\t\t\tfiles = readdirSync(dir)\n\t\t\t\t.filter((f) => f.endsWith(\".jsonl\"))\n\t\t\t\t.map((f) => {\n\t\t\t\t\tconst path = join(dir, f);\n\t\t\t\t\tlet mtime = 0;\n\t\t\t\t\tlet size = 0;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tconst st = statSync(path);\n\t\t\t\t\t\tmtime = st.mtimeMs;\n\t\t\t\t\t\tsize = st.size;\n\t\t\t\t\t} catch {}\n\t\t\t\t\treturn { path, mtime, size };\n\t\t\t\t})\n\t\t\t\t.filter((f) => f.size > 0 && f.size <= MAX_FILE_BYTES) // skip oversize logs before parse (Bug #9)\n\t\t\t\t.sort((a, b) => b.mtime - a.mtime) // most-recent first\n\t\t\t\t.slice(0, MAX_SESSIONS);\n\t\t} catch {\n\t\t\treturn docs;\n\t\t}\n\n\t\tlet total = 0;\n\t\tfor (const { path } of files) {\n\t\t\tlet entries: FileEntry[];\n\t\t\ttry {\n\t\t\t\tentries = loadEntriesFromFile(path);\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst header = entries.find((e): e is Extract<FileEntry, { type: \"session\" }> => e.type === \"session\");\n\t\t\tconst sessionId = header?.id;\n\t\t\tif (!sessionId || sessionId === this.currentSessionId || isAutoLearnSessionId(sessionId)) continue;\n\t\t\t// Privacy: only recall from sessions that ran in THIS working directory. A misplaced/copied\n\t\t\t// transcript with a different cwd must not leak across project boundaries (Bug #11).\n\t\t\tif (header?.cwd && resolve(header.cwd) !== resolve(this.cwd)) continue;\n\n\t\t\tconst text = extractSessionText(entries, MAX_DOC_CHARS);\n\t\t\tif (!text.trim()) continue;\n\t\t\tdocs.push({ sessionId, timestamp: header?.timestamp, text });\n\t\t\ttotal += text.length;\n\t\t\tif (total >= MAX_TOTAL_CHARS) break;\n\t\t}\n\t\treturn docs;\n\t}\n}\n\n/** Concatenate user+assistant text from a session's entries, capped to `maxChars`. */\nfunction extractSessionText(entries: FileEntry[], maxChars: number): string {\n\tconst parts: string[] = [];\n\tlet len = 0;\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"message\") continue;\n\t\tconst message = entry.message;\n\t\tif (message.role !== \"user\" && message.role !== \"assistant\") continue;\n\t\tconst content = message.content;\n\t\tlet text = \"\";\n\t\tif (typeof content === \"string\") {\n\t\t\ttext = content;\n\t\t} else if (Array.isArray(content)) {\n\t\t\ttext = content\n\t\t\t\t.map((b) => (b && typeof b === \"object\" && \"type\" in b && b.type === \"text\" ? (b.text ?? \"\") : \"\"))\n\t\t\t\t.join(\" \");\n\t\t}\n\t\ttext = text.trim();\n\t\tif (!text) continue;\n\t\t// Skip our own previously-injected recall pages so recalled snippets don't recirculate and\n\t\t// amplify across sessions (Bug #10).\n\t\tif (text.includes('<memory_context source=\"transcript-recall\"')) continue;\n\t\tparts.push(text);\n\t\tlen += text.length;\n\t\tif (len >= maxChars) break;\n\t}\n\treturn parts.join(\"\\n\").slice(0, maxChars);\n}\n"]}
+{"version":3,"file":"transcript-recall.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/providers/transcript-recall.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAaxG,qBAAa,wBAAyB,YAAW,cAAc;IAC9D,QAAQ,CAAC,IAAI,uBAAuB;IACpC,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,gBAAgB,CAAM;IAC9B,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,QAAQ,CAAM;IAEtB,WAAW,IAAI,OAAO,CAErB;IAED,eAAe,IAAI,kBAAkB,CAEpC;IAEK,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAK9E;IAEK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAE9B;IAED,wFAAwF;IACxF,iBAAiB,IAAI,MAAM,EAAE,CAE5B;IAEK,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB7C;IAED,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,SAAS;CAsDjB","sourcesContent":["/**\n * TranscriptRecallProvider — cross-session similarity recall (adaptive-agent design R3).\n *\n * A read-only CONTEXT memory provider: it indexes the most-recent past session transcripts (the JSONL\n * corpus) with a dependency-free token/Jaccard index ({@link TranscriptIndex}, reusing skill_audit's\n * tokenizer) and answers `prefetch(query)` with a small `<memory_context>` recall page of the most\n * relevant past snippets. The current session and auto-learn sessions are excluded. It never writes —\n * the file-store remains the write target; this is the recall corpus.\n */\n\nimport { readdirSync, statSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport {\n\ttype FileEntry,\n\tgetDefaultSessionDir,\n\tisAutoLearnSessionId,\n\tloadEntriesFromFile,\n} from \"@caupulican/pi-agent-core/node\";\nimport { wrapUntrustedText } from \"../../security/untrusted-boundary.ts\";\nimport type { MemoryCapabilities, MemoryLifecycleContext, MemoryProvider } from \"../memory-provider.ts\";\nimport { type TranscriptDoc, TranscriptIndex } from \"../transcript-index.ts\";\n\n/** Most-recent past sessions to consider. */\nconst MAX_SESSIONS = 60;\n/** Per-session text cap (keeps the index light and snippets relevant). */\nconst MAX_DOC_CHARS = 8_000;\n/** Overall corpus cap across all docs. */\nconst MAX_TOTAL_CHARS = 500_000;\n/** Skip transcript files larger than this before parsing them, so a huge log can't block/bloat the\n * first recalled turn (Bug #9). Far above a normal session; only pathological logs exceed it. */\nconst MAX_FILE_BYTES = 8_000_000;\n\nexport class TranscriptRecallProvider implements MemoryProvider {\n\treadonly name = \"transcript-recall\";\n\tprivate index: TranscriptIndex | undefined;\n\tprivate currentSessionId = \"\";\n\tprivate cwd = \"\";\n\tprivate agentDir = \"\";\n\n\tisAvailable(): boolean {\n\t\treturn true;\n\t}\n\n\tgetCapabilities(): MemoryCapabilities {\n\t\treturn { surfaces: [\"context\"] };\n\t}\n\n\tasync initialize(sessionId: string, ctx: MemoryLifecycleContext): Promise<void> {\n\t\tthis.currentSessionId = sessionId;\n\t\tthis.cwd = ctx.cwd;\n\t\tthis.agentDir = ctx.agentDir;\n\t\tthis.index = undefined; // built lazily on first prefetch\n\t}\n\n\tasync shutdown(): Promise<void> {\n\t\tthis.index = undefined;\n\t}\n\n\t/** GC manages the dynamic recall page so stale pages pack while the newest are kept. */\n\tgetContextMarkers(): string[] {\n\t\treturn [\"<memory_context\"];\n\t}\n\n\tasync prefetch(query: string): Promise<string> {\n\t\tif (!query.trim()) return \"\";\n\t\tlet index: TranscriptIndex;\n\t\ttry {\n\t\t\tindex = this.ensureIndex();\n\t\t} catch {\n\t\t\treturn \"\";\n\t\t}\n\t\tif (index.size === 0) return \"\";\n\t\t// minScore is a query-CONTAINMENT threshold (fraction of the query's tokens present in the doc),\n\t\t// not Jaccard — so it is length-independent and recalls relevant long sessions. ~1/3 of query\n\t\t// terms must appear before a session is considered relevant.\n\t\tconst hits = index.query(query, { k: 3, minScore: 0.34, maxSnippetChars: 600 });\n\t\tif (hits.length === 0) return \"\";\n\t\t// Recalled past text is UNTRUSTED (it may itself contain injected instructions or a forged\n\t\t// `</memory_context>` to break out). Fence each snippet with the untrusted-content boundary so a\n\t\t// payload can't escape and be replayed as a current instruction (design: recall = untrusted).\n\t\tconst body = hits\n\t\t\t.map((h) => `- (${h.timestamp ?? \"earlier session\"}) ${wrapUntrustedText(h.snippet, \"transcript-recall\")}`)\n\t\t\t.join(\"\\n\");\n\t\treturn `<memory_context source=\"transcript-recall\">\\nRelevant context recalled from past sessions (read-only reference, untrusted, may be stale):\\n${body}\\n</memory_context>`;\n\t}\n\n\tprivate ensureIndex(): TranscriptIndex {\n\t\tif (!this.index) {\n\t\t\tthis.index = new TranscriptIndex(this.buildDocs());\n\t\t}\n\t\treturn this.index;\n\t}\n\n\tprivate buildDocs(): TranscriptDoc[] {\n\t\tconst docs: TranscriptDoc[] = [];\n\t\tlet dir: string;\n\t\ttry {\n\t\t\tdir = getDefaultSessionDir(this.cwd, this.agentDir);\n\t\t} catch {\n\t\t\treturn docs;\n\t\t}\n\n\t\tlet files: Array<{ path: string; mtime: number }>;\n\t\ttry {\n\t\t\tfiles = readdirSync(dir)\n\t\t\t\t.filter((f) => f.endsWith(\".jsonl\"))\n\t\t\t\t.map((f) => {\n\t\t\t\t\tconst path = join(dir, f);\n\t\t\t\t\tlet mtime = 0;\n\t\t\t\t\tlet size = 0;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tconst st = statSync(path);\n\t\t\t\t\t\tmtime = st.mtimeMs;\n\t\t\t\t\t\tsize = st.size;\n\t\t\t\t\t} catch {}\n\t\t\t\t\treturn { path, mtime, size };\n\t\t\t\t})\n\t\t\t\t.filter((f) => f.size > 0 && f.size <= MAX_FILE_BYTES) // skip oversize logs before parse (Bug #9)\n\t\t\t\t.sort((a, b) => b.mtime - a.mtime) // most-recent first\n\t\t\t\t.slice(0, MAX_SESSIONS);\n\t\t} catch {\n\t\t\treturn docs;\n\t\t}\n\n\t\tlet total = 0;\n\t\tfor (const { path } of files) {\n\t\t\tlet entries: FileEntry[];\n\t\t\ttry {\n\t\t\t\tentries = loadEntriesFromFile(path);\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst header = entries.find((e): e is Extract<FileEntry, { type: \"session\" }> => e.type === \"session\");\n\t\t\tconst sessionId = header?.id;\n\t\t\tif (!sessionId || sessionId === this.currentSessionId || isAutoLearnSessionId(sessionId)) continue;\n\t\t\t// Privacy: only recall from sessions that ran in THIS working directory. A misplaced/copied\n\t\t\t// transcript with a different cwd must not leak across project boundaries (Bug #11).\n\t\t\tif (header?.cwd && resolve(header.cwd) !== resolve(this.cwd)) continue;\n\n\t\t\tconst text = extractSessionText(entries, MAX_DOC_CHARS);\n\t\t\tif (!text.trim()) continue;\n\t\t\tdocs.push({ sessionId, timestamp: header?.timestamp, text });\n\t\t\ttotal += text.length;\n\t\t\tif (total >= MAX_TOTAL_CHARS) break;\n\t\t}\n\t\treturn docs;\n\t}\n}\n\n/** Concatenate user+assistant text from a session's entries, capped to `maxChars`. */\nfunction extractSessionText(entries: FileEntry[], maxChars: number): string {\n\tconst parts: string[] = [];\n\tlet len = 0;\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"message\") continue;\n\t\tconst message = entry.message;\n\t\tif (message.role !== \"user\" && message.role !== \"assistant\") continue;\n\t\tconst content = message.content;\n\t\tlet text = \"\";\n\t\tif (typeof content === \"string\") {\n\t\t\ttext = content;\n\t\t} else if (Array.isArray(content)) {\n\t\t\ttext = content\n\t\t\t\t.map((b) => (b && typeof b === \"object\" && \"type\" in b && b.type === \"text\" ? (b.text ?? \"\") : \"\"))\n\t\t\t\t.join(\" \");\n\t\t}\n\t\ttext = text.trim();\n\t\tif (!text) continue;\n\t\t// Skip our own previously-injected recall pages so recalled snippets don't recirculate and\n\t\t// amplify across sessions (Bug #10).\n\t\tif (text.includes('<memory_context source=\"transcript-recall\"')) continue;\n\t\tparts.push(text);\n\t\tlen += text.length;\n\t\tif (len >= maxChars) break;\n\t}\n\treturn parts.join(\"\\n\").slice(0, maxChars);\n}\n"]}

package/dist/core/memory/providers/transcript-recall.js

@@ -9,8 +9,8 @@
  */
 import { readdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { getDefaultSessionDir, isAutoLearnSessionId, loadEntriesFromFile, } from "@caupulican/pi-agent-core/node";
 import { wrapUntrustedText } from "../../security/untrusted-boundary.js";
-import { getDefaultSessionDir, isAutoLearnSessionId, loadEntriesFromFile, } from "../../session-manager.js";
 import { TranscriptIndex } from "../transcript-index.js";
 /** Most-recent past sessions to consider. */
 const MAX_SESSIONS = 60;

package/dist/core/memory/providers/transcript-recall.js.map

@@ -1 +1 @@
-{"version":3,"file":"transcript-recall.js","sourceRoot":"","sources":["../../../../src/core/memory/providers/transcript-recall.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * TranscriptRecallProvider — cross-session similarity recall (adaptive-agent design R3).\n *\n * A read-only CONTEXT memory provider: it indexes the most-recent past session transcripts (the JSONL\n * corpus) with a dependency-free token/Jaccard index ({@link TranscriptIndex}, reusing skill_audit's\n * tokenizer) and answers `prefetch(query)` with a small `<memory_context>` recall page of the most\n * relevant past snippets. The current session and auto-learn sessions are excluded. It never writes —\n * the file-store remains the write target; this is the recall corpus.\n */\n\nimport { readdirSync, statSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { wrapUntrustedText } from \"../../security/untrusted-boundary.ts\";\nimport {\n\ttype FileEntry,\n\tgetDefaultSessionDir,\n\tisAutoLearnSessionId,\n\tloadEntriesFromFile,\n} from \"../../session-manager.ts\";\nimport type { MemoryCapabilities, MemoryLifecycleContext, MemoryProvider } from \"../memory-provider.ts\";\nimport { type TranscriptDoc, TranscriptIndex } from \"../transcript-index.ts\";\n\n/** Most-recent past sessions to consider. */\nconst MAX_SESSIONS = 60;\n/** Per-session text cap (keeps the index light and snippets relevant). */\nconst MAX_DOC_CHARS = 8_000;\n/** Overall corpus cap across all docs. */\nconst MAX_TOTAL_CHARS = 500_000;\n/** Skip transcript files larger than this before parsing them, so a huge log can't block/bloat the\n * first recalled turn (Bug #9). Far above a normal session; only pathological logs exceed it. */\nconst MAX_FILE_BYTES = 8_000_000;\n\nexport class TranscriptRecallProvider implements MemoryProvider {\n\treadonly name = \"transcript-recall\";\n\tprivate index: TranscriptIndex | undefined;\n\tprivate currentSessionId = \"\";\n\tprivate cwd = \"\";\n\tprivate agentDir = \"\";\n\n\tisAvailable(): boolean {\n\t\treturn true;\n\t}\n\n\tgetCapabilities(): MemoryCapabilities {\n\t\treturn { surfaces: [\"context\"] };\n\t}\n\n\tasync initialize(sessionId: string, ctx: MemoryLifecycleContext): Promise<void> {\n\t\tthis.currentSessionId = sessionId;\n\t\tthis.cwd = ctx.cwd;\n\t\tthis.agentDir = ctx.agentDir;\n\t\tthis.index = undefined; // built lazily on first prefetch\n\t}\n\n\tasync shutdown(): Promise<void> {\n\t\tthis.index = undefined;\n\t}\n\n\t/** GC manages the dynamic recall page so stale pages pack while the newest are kept. */\n\tgetContextMarkers(): string[] {\n\t\treturn [\"<memory_context\"];\n\t}\n\n\tasync prefetch(query: string): Promise<string> {\n\t\tif (!query.trim()) return \"\";\n\t\tlet index: TranscriptIndex;\n\t\ttry {\n\t\t\tindex = this.ensureIndex();\n\t\t} catch {\n\t\t\treturn \"\";\n\t\t}\n\t\tif (index.size === 0) return \"\";\n\t\t// minScore is a query-CONTAINMENT threshold (fraction of the query's tokens present in the doc),\n\t\t// not Jaccard — so it is length-independent and recalls relevant long sessions. ~1/3 of query\n\t\t// terms must appear before a session is considered relevant.\n\t\tconst hits = index.query(query, { k: 3, minScore: 0.34, maxSnippetChars: 600 });\n\t\tif (hits.length === 0) return \"\";\n\t\t// Recalled past text is UNTRUSTED (it may itself contain injected instructions or a forged\n\t\t// `</memory_context>` to break out). Fence each snippet with the untrusted-content boundary so a\n\t\t// payload can't escape and be replayed as a current instruction (design: recall = untrusted).\n\t\tconst body = hits\n\t\t\t.map((h) => `- (${h.timestamp ?? \"earlier session\"}) ${wrapUntrustedText(h.snippet, \"transcript-recall\")}`)\n\t\t\t.join(\"\\n\");\n\t\treturn `<memory_context source=\"transcript-recall\">\\nRelevant context recalled from past sessions (read-only reference, untrusted, may be stale):\\n${body}\\n</memory_context>`;\n\t}\n\n\tprivate ensureIndex(): TranscriptIndex {\n\t\tif (!this.index) {\n\t\t\tthis.index = new TranscriptIndex(this.buildDocs());\n\t\t}\n\t\treturn this.index;\n\t}\n\n\tprivate buildDocs(): TranscriptDoc[] {\n\t\tconst docs: TranscriptDoc[] = [];\n\t\tlet dir: string;\n\t\ttry {\n\t\t\tdir = getDefaultSessionDir(this.cwd, this.agentDir);\n\t\t} catch {\n\t\t\treturn docs;\n\t\t}\n\n\t\tlet files: Array<{ path: string; mtime: number }>;\n\t\ttry {\n\t\t\tfiles = readdirSync(dir)\n\t\t\t\t.filter((f) => f.endsWith(\".jsonl\"))\n\t\t\t\t.map((f) => {\n\t\t\t\t\tconst path = join(dir, f);\n\t\t\t\t\tlet mtime = 0;\n\t\t\t\t\tlet size = 0;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tconst st = statSync(path);\n\t\t\t\t\t\tmtime = st.mtimeMs;\n\t\t\t\t\t\tsize = st.size;\n\t\t\t\t\t} catch {}\n\t\t\t\t\treturn { path, mtime, size };\n\t\t\t\t})\n\t\t\t\t.filter((f) => f.size > 0 && f.size <= MAX_FILE_BYTES) // skip oversize logs before parse (Bug #9)\n\t\t\t\t.sort((a, b) => b.mtime - a.mtime) // most-recent first\n\t\t\t\t.slice(0, MAX_SESSIONS);\n\t\t} catch {\n\t\t\treturn docs;\n\t\t}\n\n\t\tlet total = 0;\n\t\tfor (const { path } of files) {\n\t\t\tlet entries: FileEntry[];\n\t\t\ttry {\n\t\t\t\tentries = loadEntriesFromFile(path);\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst header = entries.find((e): e is Extract<FileEntry, { type: \"session\" }> => e.type === \"session\");\n\t\t\tconst sessionId = header?.id;\n\t\t\tif (!sessionId || sessionId === this.currentSessionId || isAutoLearnSessionId(sessionId)) continue;\n\t\t\t// Privacy: only recall from sessions that ran in THIS working directory. A misplaced/copied\n\t\t\t// transcript with a different cwd must not leak across project boundaries (Bug #11).\n\t\t\tif (header?.cwd && resolve(header.cwd) !== resolve(this.cwd)) continue;\n\n\t\t\tconst text = extractSessionText(entries, MAX_DOC_CHARS);\n\t\t\tif (!text.trim()) continue;\n\t\t\tdocs.push({ sessionId, timestamp: header?.timestamp, text });\n\t\t\ttotal += text.length;\n\t\t\tif (total >= MAX_TOTAL_CHARS) break;\n\t\t}\n\t\treturn docs;\n\t}\n}\n\n/** Concatenate user+assistant text from a session's entries, capped to `maxChars`. */\nfunction extractSessionText(entries: FileEntry[], maxChars: number): string {\n\tconst parts: string[] = [];\n\tlet len = 0;\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"message\") continue;\n\t\tconst message = entry.message;\n\t\tif (message.role !== \"user\" && message.role !== \"assistant\") continue;\n\t\tconst content = message.content;\n\t\tlet text = \"\";\n\t\tif (typeof content === \"string\") {\n\t\t\ttext = content;\n\t\t} else if (Array.isArray(content)) {\n\t\t\ttext = content\n\t\t\t\t.map((b) => (b && typeof b === \"object\" && \"type\" in b && b.type === \"text\" ? (b.text ?? \"\") : \"\"))\n\t\t\t\t.join(\" \");\n\t\t}\n\t\ttext = text.trim();\n\t\tif (!text) continue;\n\t\t// Skip our own previously-injected recall pages so recalled snippets don't recirculate and\n\t\t// amplify across sessions (Bug #10).\n\t\tif (text.includes('<memory_context source=\"transcript-recall\"')) continue;\n\t\tparts.push(text);\n\t\tlen += text.length;\n\t\tif (len >= maxChars) break;\n\t}\n\treturn parts.join(\"\\n\").slice(0, maxChars);\n}\n"]}
+{"version":3,"file":"transcript-recall.js","sourceRoot":"","sources":["../../../../src/core/memory/providers/transcript-recall.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * TranscriptRecallProvider — cross-session similarity recall (adaptive-agent design R3).\n *\n * A read-only CONTEXT memory provider: it indexes the most-recent past session transcripts (the JSONL\n * corpus) with a dependency-free token/Jaccard index ({@link TranscriptIndex}, reusing skill_audit's\n * tokenizer) and answers `prefetch(query)` with a small `<memory_context>` recall page of the most\n * relevant past snippets. The current session and auto-learn sessions are excluded. It never writes —\n * the file-store remains the write target; this is the recall corpus.\n */\n\nimport { readdirSync, statSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport {\n\ttype FileEntry,\n\tgetDefaultSessionDir,\n\tisAutoLearnSessionId,\n\tloadEntriesFromFile,\n} from \"@caupulican/pi-agent-core/node\";\nimport { wrapUntrustedText } from \"../../security/untrusted-boundary.ts\";\nimport type { MemoryCapabilities, MemoryLifecycleContext, MemoryProvider } from \"../memory-provider.ts\";\nimport { type TranscriptDoc, TranscriptIndex } from \"../transcript-index.ts\";\n\n/** Most-recent past sessions to consider. */\nconst MAX_SESSIONS = 60;\n/** Per-session text cap (keeps the index light and snippets relevant). */\nconst MAX_DOC_CHARS = 8_000;\n/** Overall corpus cap across all docs. */\nconst MAX_TOTAL_CHARS = 500_000;\n/** Skip transcript files larger than this before parsing them, so a huge log can't block/bloat the\n * first recalled turn (Bug #9). Far above a normal session; only pathological logs exceed it. */\nconst MAX_FILE_BYTES = 8_000_000;\n\nexport class TranscriptRecallProvider implements MemoryProvider {\n\treadonly name = \"transcript-recall\";\n\tprivate index: TranscriptIndex | undefined;\n\tprivate currentSessionId = \"\";\n\tprivate cwd = \"\";\n\tprivate agentDir = \"\";\n\n\tisAvailable(): boolean {\n\t\treturn true;\n\t}\n\n\tgetCapabilities(): MemoryCapabilities {\n\t\treturn { surfaces: [\"context\"] };\n\t}\n\n\tasync initialize(sessionId: string, ctx: MemoryLifecycleContext): Promise<void> {\n\t\tthis.currentSessionId = sessionId;\n\t\tthis.cwd = ctx.cwd;\n\t\tthis.agentDir = ctx.agentDir;\n\t\tthis.index = undefined; // built lazily on first prefetch\n\t}\n\n\tasync shutdown(): Promise<void> {\n\t\tthis.index = undefined;\n\t}\n\n\t/** GC manages the dynamic recall page so stale pages pack while the newest are kept. */\n\tgetContextMarkers(): string[] {\n\t\treturn [\"<memory_context\"];\n\t}\n\n\tasync prefetch(query: string): Promise<string> {\n\t\tif (!query.trim()) return \"\";\n\t\tlet index: TranscriptIndex;\n\t\ttry {\n\t\t\tindex = this.ensureIndex();\n\t\t} catch {\n\t\t\treturn \"\";\n\t\t}\n\t\tif (index.size === 0) return \"\";\n\t\t// minScore is a query-CONTAINMENT threshold (fraction of the query's tokens present in the doc),\n\t\t// not Jaccard — so it is length-independent and recalls relevant long sessions. ~1/3 of query\n\t\t// terms must appear before a session is considered relevant.\n\t\tconst hits = index.query(query, { k: 3, minScore: 0.34, maxSnippetChars: 600 });\n\t\tif (hits.length === 0) return \"\";\n\t\t// Recalled past text is UNTRUSTED (it may itself contain injected instructions or a forged\n\t\t// `</memory_context>` to break out). Fence each snippet with the untrusted-content boundary so a\n\t\t// payload can't escape and be replayed as a current instruction (design: recall = untrusted).\n\t\tconst body = hits\n\t\t\t.map((h) => `- (${h.timestamp ?? \"earlier session\"}) ${wrapUntrustedText(h.snippet, \"transcript-recall\")}`)\n\t\t\t.join(\"\\n\");\n\t\treturn `<memory_context source=\"transcript-recall\">\\nRelevant context recalled from past sessions (read-only reference, untrusted, may be stale):\\n${body}\\n</memory_context>`;\n\t}\n\n\tprivate ensureIndex(): TranscriptIndex {\n\t\tif (!this.index) {\n\t\t\tthis.index = new TranscriptIndex(this.buildDocs());\n\t\t}\n\t\treturn this.index;\n\t}\n\n\tprivate buildDocs(): TranscriptDoc[] {\n\t\tconst docs: TranscriptDoc[] = [];\n\t\tlet dir: string;\n\t\ttry {\n\t\t\tdir = getDefaultSessionDir(this.cwd, this.agentDir);\n\t\t} catch {\n\t\t\treturn docs;\n\t\t}\n\n\t\tlet files: Array<{ path: string; mtime: number }>;\n\t\ttry {\n\t\t\tfiles = readdirSync(dir)\n\t\t\t\t.filter((f) => f.endsWith(\".jsonl\"))\n\t\t\t\t.map((f) => {\n\t\t\t\t\tconst path = join(dir, f);\n\t\t\t\t\tlet mtime = 0;\n\t\t\t\t\tlet size = 0;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tconst st = statSync(path);\n\t\t\t\t\t\tmtime = st.mtimeMs;\n\t\t\t\t\t\tsize = st.size;\n\t\t\t\t\t} catch {}\n\t\t\t\t\treturn { path, mtime, size };\n\t\t\t\t})\n\t\t\t\t.filter((f) => f.size > 0 && f.size <= MAX_FILE_BYTES) // skip oversize logs before parse (Bug #9)\n\t\t\t\t.sort((a, b) => b.mtime - a.mtime) // most-recent first\n\t\t\t\t.slice(0, MAX_SESSIONS);\n\t\t} catch {\n\t\t\treturn docs;\n\t\t}\n\n\t\tlet total = 0;\n\t\tfor (const { path } of files) {\n\t\t\tlet entries: FileEntry[];\n\t\t\ttry {\n\t\t\t\tentries = loadEntriesFromFile(path);\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst header = entries.find((e): e is Extract<FileEntry, { type: \"session\" }> => e.type === \"session\");\n\t\t\tconst sessionId = header?.id;\n\t\t\tif (!sessionId || sessionId === this.currentSessionId || isAutoLearnSessionId(sessionId)) continue;\n\t\t\t// Privacy: only recall from sessions that ran in THIS working directory. A misplaced/copied\n\t\t\t// transcript with a different cwd must not leak across project boundaries (Bug #11).\n\t\t\tif (header?.cwd && resolve(header.cwd) !== resolve(this.cwd)) continue;\n\n\t\t\tconst text = extractSessionText(entries, MAX_DOC_CHARS);\n\t\t\tif (!text.trim()) continue;\n\t\t\tdocs.push({ sessionId, timestamp: header?.timestamp, text });\n\t\t\ttotal += text.length;\n\t\t\tif (total >= MAX_TOTAL_CHARS) break;\n\t\t}\n\t\treturn docs;\n\t}\n}\n\n/** Concatenate user+assistant text from a session's entries, capped to `maxChars`. */\nfunction extractSessionText(entries: FileEntry[], maxChars: number): string {\n\tconst parts: string[] = [];\n\tlet len = 0;\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"message\") continue;\n\t\tconst message = entry.message;\n\t\tif (message.role !== \"user\" && message.role !== \"assistant\") continue;\n\t\tconst content = message.content;\n\t\tlet text = \"\";\n\t\tif (typeof content === \"string\") {\n\t\t\ttext = content;\n\t\t} else if (Array.isArray(content)) {\n\t\t\ttext = content\n\t\t\t\t.map((b) => (b && typeof b === \"object\" && \"type\" in b && b.type === \"text\" ? (b.text ?? \"\") : \"\"))\n\t\t\t\t.join(\" \");\n\t\t}\n\t\ttext = text.trim();\n\t\tif (!text) continue;\n\t\t// Skip our own previously-injected recall pages so recalled snippets don't recirculate and\n\t\t// amplify across sessions (Bug #10).\n\t\tif (text.includes('<memory_context source=\"transcript-recall\"')) continue;\n\t\tparts.push(text);\n\t\tlen += text.length;\n\t\tif (len >= maxChars) break;\n\t}\n\treturn parts.join(\"\\n\").slice(0, maxChars);\n}\n"]}

package/dist/core/memory-controller.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Memory controller: the session's plug-and-play memory subsystem — the read-only OKF retrieval
+ * provider, the bounded prompt-evidence surfacing pilot, cross-session recall effectiveness, and the
+ * live {@link MemoryManager} (bundled file-store + transcript-recall providers plus any extension
+ * contributions).
+ *
+ * Extracted verbatim from agent-session.ts (god-file decomposition). Owns the lazily-built OKF
+ * provider, the latest retrieval/prompt-inclusion reports, the recreated-on-reload MemoryManager, the
+ * recall {@link EffectivenessTracker}, and the extension-contributed pending providers. Everything
+ * else it needs — settings, the current turn index, agent/workspace dirs, the session id, the
+ * child-session flag, and the tool-registry refresh — is reached through narrow deps accessors rather
+ * than the whole AgentSession.
+ *
+ * Context-transform boundary (deliberate): {@link runMemoryRetrieval} and
+ * {@link maybeAppendMemoryEvidenceBlock} are invoked from the session's context transform as one-line
+ * delegations. This controller deliberately imports no compaction/context-pipeline internals — it only
+ * ever reads settings and builds the retrieval report + the bounded evidence block, so the transform
+ * stays the single owner of the pass ordering.
+ */
+import type { AgentMessage } from "@caupulican/pi-agent-core";
+import { type MemoryPromptInclusionReport, type MemoryRetrievalDiagnostics } from "./context/memory-diagnostics.ts";
+import { type MemoryRetrievalReport } from "./context/memory-retrieval.ts";
+import { MemoryManager } from "./memory/memory-manager.ts";
+import type { MemoryProvider } from "./memory/memory-provider.ts";
+import type { SettingsManager } from "./settings-manager.ts";
+export interface MemoryControllerDeps {
+    /** Memory-retrieval + prompt-inclusion settings (the opt-in gates for retrieval and surfacing). */
+    getSettingsManager(): SettingsManager;
+    /** Current turn index, stamped into a retrieval request's `createdAtTurn`. */
+    getTurnIndex(): number;
+    /** Agent root — the durable OKF memory docs live under `<agentDir>/okf-memory`. */
+    getAgentDir(): string;
+    /** Workspace root, passed to provider initialization. */
+    getCwd(): string;
+    /** This session's id, passed to provider initialization. */
+    getSessionId(): string;
+    /** Child sessions gate durable memory writes; passed to provider initialization. */
+    isChildSession(): boolean;
+    /** Re-derive the tool registry after (re)init so the newly-surfaced memory tools take effect. */
+    refreshToolRegistry(): void;
+}
+export declare class MemoryController {
+    private _memoryOkfProvider;
+    private _latestMemoryRetrievalReport;
+    private _latestMemoryPromptInclusionReport;
+    /** Plug-and-play memory subsystem. Recreated on each (re)initialize so reload is safe. */
+    private _memoryManager;
+    /** R4: tracks whether injected recall is actually used, to adapt the recall gate. */
+    private readonly _effectivenessTracker;
+    /** Memory providers registered by extensions via pi.registerMemoryProvider, applied on (re)init. */
+    private _pendingMemoryProviders;
+    private readonly deps;
+    constructor(deps: MemoryControllerDeps);
+    /** The live memory manager. Callers reach prefetch / tool-definitions / markers / shutdown through it. */
+    getMemoryManager(): MemoryManager;
+    /**
+     * Fixed path for this slice's local Pi OKF memory documents, shared across sessions
+     * under this agentDir (not session-scoped, unlike tool-artifacts/context-gc, since OKF
+     * memory represents durable cross-session knowledge, not a per-session capture). Not
+     * yet user-configurable -- see the memory-retrieval settings doc comment.
+     */
+    private _memoryOkfDir;
+    /**
+     * Session-scoped, read-only local OKF memory provider. Lazily created ONLY when memory
+     * retrieval is enabled (see `runMemoryRetrieval`) -- never force-created, so a session
+     * with the setting off never touches `_memoryOkfDir()` at all (no directory access, no
+     * creation; `createOkfMemoryProvider` itself never writes/mkdirs either way).
+     */
+    private _getMemoryOkfProvider;
+    /**
+     * Observe-only local memory retrieval (see context/memory-retrieval.ts and
+     * context/okf-memory-provider.ts): default disabled, opt-in setting. When disabled,
+     * never constructs the OKF provider (no directory access under `_memoryOkfDir()` at
+     * all) and returns an empty report -- fully fail-closed. When enabled, queries the
+     * local, read-only OKF provider with the latest user message text (empty if there is
+     * none, e.g. a goal-continuation turn -- degrades to zero results by construction, see
+     * `latestUserMessageText`'s doc comment) under `DEFAULT_LOCAL_MEMORY_EGRESS_POLICY`.
+     * Retrieved items are only ever stored in the report; nothing here touches `messages`,
+     * the transcript, or the provider-visible prompt. Never throws into a live turn: any
+     * failure (including a provider search error) degrades to an empty report.
+     */
+    runMemoryRetrieval(messages: AgentMessage[]): Promise<MemoryRetrievalReport>;
+    /** Read-only inspection of the latest memory-retrieval report, for tests/debugging. */
+    getMemoryRetrievalReport(): MemoryRetrievalReport;
+    /**
+     * Bounded prompt-surfacing pilot for local memory evidence (see
+     * context/memory-prompt-block.ts): opt-in, default disabled, and gated on TWO settings
+     * (`enabled` AND `includeInPrompt`) plus a non-empty `report.contextItems` -- the first
+     * two are belt-and-suspenders on top of the fact that `runMemoryRetrieval` already
+     * leaves `contextItems` empty whenever `enabled` is false, regardless of
+     * `includeInPrompt`. Reuses the `report` this pass's `runMemoryRetrieval` call already
+     * computed -- never re-queries the provider here.
+     *
+     * Appends exactly one ephemeral `custom`/"memory_evidence" message wrapped by
+     * `wrapUntrustedText` (the same nonce-fenced boundary + always-on system-prompt rule
+     * used for other untrusted content) to the END of `messages`. This is purely additive
+     * (never mutates an existing message) and purely transient: `messages` here is the
+     * array about to be sent to the provider, not `this.agent.state.messages` or anything
+     * persisted via `sessionManager` -- so the injected message can never reach the
+     * transcript, regardless of how many times this pass runs.
+     *
+     * Also records a `MemoryPromptInclusionReport` (context/memory-diagnostics.ts) at each
+     * branch below, for context_audit's diagnostic surface only -- this is pure bookkeeping
+     * alongside the existing branches, not a new branch/condition: the messages returned
+     * are unchanged by this recording.
+     */
+    maybeAppendMemoryEvidenceBlock(messages: AgentMessage[], report: MemoryRetrievalReport): AgentMessage[];
+    /** Read-only inspection of the latest memory-prompt-inclusion decision, for tests/debugging and context_audit. */
+    getMemoryPromptInclusionReport(): MemoryPromptInclusionReport;
+    /**
+     * Combines the already-stored, no-arg latest reports (never re-queries the provider or
+     * touches the OKF directory) into the safe, allow-list-projected shape context_audit
+     * exposes. See context/memory-diagnostics.ts for why this projection is allow-list
+     * based rather than a spread-then-delete of the raw report.
+     */
+    getMemoryAuditDiagnostics(): {
+        retrieval: MemoryRetrievalDiagnostics;
+        promptInclusion: MemoryPromptInclusionReport;
+    };
+    /**
+     * Zero-I/O gate for cross-session recall (R3): skip trivial turns (short acks, slash commands) so
+     * recall only runs when it could plausibly help. The provider's similarity cutoff is the real
+     * filter — this just avoids the index query on turns that obviously don't warrant it.
+     */
+    shouldAttemptRecall(text: string): boolean;
+    /** R4: score whether the agent actually used an injected recall page, so the recall gate can adapt. */
+    recordRecallOutcome(recallText: string, queryText: string, responseText: string): void;
+    /**
+     * (Re)build the memory subsystem: a fresh MemoryManager (reload-safe), register the bundled
+     * file-store + any extension-contributed providers, initialize, then surface the memory tools and
+     * the frozen system-prompt block. Best-effort: never throws into the session lifecycle.
+     */
+    initialize(): Promise<void>;
+    /** Register a memory provider contributed by an extension; applied on the next memory (re)init. */
+    registerMemoryProvider(provider: MemoryProvider): void;
+    /** Reload starts memory providers fresh; loaded extensions re-register before the next `initialize()`. */
+    clearPendingProviders(): void;
+}
+//# sourceMappingURL=memory-controller.d.ts.map

package/dist/core/memory-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-controller.d.ts","sourceRoot":"","sources":["../../src/core/memory-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,2BAA2B,CAAC;AAC7E,OAAO,EAEN,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAE/B,MAAM,iCAAiC,CAAC;AAMzC,OAAO,EAAE,KAAK,qBAAqB,EAA4B,MAAM,+BAA+B,CAAC;AAGrG,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAIlE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AA0B7D,MAAM,WAAW,oBAAoB;IACpC,mGAAmG;IACnG,kBAAkB,IAAI,eAAe,CAAC;IACtC,8EAA8E;IAC9E,YAAY,IAAI,MAAM,CAAC;IACvB,qFAAmF;IACnF,WAAW,IAAI,MAAM,CAAC;IACtB,yDAAyD;IACzD,MAAM,IAAI,MAAM,CAAC;IACjB,4DAA4D;IAC5D,YAAY,IAAI,MAAM,CAAC;IACvB,oFAAoF;IACpF,cAAc,IAAI,OAAO,CAAC;IAC1B,iGAAiG;IACjG,mBAAmB,IAAI,IAAI,CAAC;CAC5B;AAED,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,kBAAkB,CAAgD;IAC1E,OAAO,CAAC,4BAA4B,CAAgD;IACpF,OAAO,CAAC,kCAAkC,CAAsD;IAChG,0FAA0F;IAC1F,OAAO,CAAC,cAAc,CAAsC;IAC5D,qFAAqF;IACrF,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA8B;IACpE,oGAAoG;IACpG,OAAO,CAAC,uBAAuB,CAAwB;IAEvD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAE5C,YAAY,IAAI,EAAE,oBAAoB,EAErC;IAED,0GAA0G;IAC1G,gBAAgB,IAAI,aAAa,CAEhC;IAED;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAK7B;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAwBjF;IAED,uFAAuF;IACvF,wBAAwB,IAAI,qBAAqB,CAEhD;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,8BAA8B,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,qBAAqB,GAAG,YAAY,EAAE,CAoFtG;IAED,kHAAkH;IAClH,8BAA8B,IAAI,2BAA2B,CAE5D;IAED;;;;;OAKG;IACH,yBAAyB,IAAI;QAC5B,SAAS,EAAE,0BAA0B,CAAC;QACtC,eAAe,EAAE,2BAA2B,CAAC;KAC7C,CAMA;IAED;;;;OAIG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUzC;IAED,uGAAuG;IACvG,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAErF;IAED;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CA8BhC;IAED,mGAAmG;IACnG,sBAAsB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAIrD;IAED,0GAA0G;IAC1G,qBAAqB,IAAI,IAAI,CAE5B;CACD","sourcesContent":["/**\n * Memory controller: the session's plug-and-play memory subsystem — the read-only OKF retrieval\n * provider, the bounded prompt-evidence surfacing pilot, cross-session recall effectiveness, and the\n * live {@link MemoryManager} (bundled file-store + transcript-recall providers plus any extension\n * contributions).\n *\n * Extracted verbatim from agent-session.ts (god-file decomposition). Owns the lazily-built OKF\n * provider, the latest retrieval/prompt-inclusion reports, the recreated-on-reload MemoryManager, the\n * recall {@link EffectivenessTracker}, and the extension-contributed pending providers. Everything\n * else it needs — settings, the current turn index, agent/workspace dirs, the session id, the\n * child-session flag, and the tool-registry refresh — is reached through narrow deps accessors rather\n * than the whole AgentSession.\n *\n * Context-transform boundary (deliberate): {@link runMemoryRetrieval} and\n * {@link maybeAppendMemoryEvidenceBlock} are invoked from the session's context transform as one-line\n * delegations. This controller deliberately imports no compaction/context-pipeline internals — it only\n * ever reads settings and builds the retrieval report + the bounded evidence block, so the transform\n * stays the single owner of the pass ordering.\n */\n\nimport { join } from \"node:path\";\nimport type { AgentMessage, CustomMessage } from \"@caupulican/pi-agent-core\";\nimport {\n\tdefaultMemoryPromptInclusionReport,\n\ttype MemoryPromptInclusionReport,\n\ttype MemoryRetrievalDiagnostics,\n\tsanitizeMemoryRetrievalReportForDiagnostics,\n} from \"./context/memory-diagnostics.ts\";\nimport { buildMemoryPromptBlock } from \"./context/memory-prompt-block.ts\";\nimport {\n\ttype MemoryProvider as ContextMemoryProvider,\n\tDEFAULT_LOCAL_MEMORY_EGRESS_POLICY,\n} from \"./context/memory-provider-contract.ts\";\nimport { type MemoryRetrievalReport, retrieveMemoryForContext } from \"./context/memory-retrieval.ts\";\nimport { createOkfMemoryProvider } from \"./context/okf-memory-provider.ts\";\nimport { EffectivenessTracker } from \"./memory/effectiveness-tracker.ts\";\nimport { MemoryManager } from \"./memory/memory-manager.ts\";\nimport type { MemoryProvider } from \"./memory/memory-provider.ts\";\nimport { FileStoreProvider } from \"./memory/providers/file-store.ts\";\nimport { TranscriptRecallProvider } from \"./memory/providers/transcript-recall.ts\";\nimport { wrapUntrustedText } from \"./security/untrusted-boundary.ts\";\nimport type { SettingsManager } from \"./settings-manager.ts\";\n\n/**\n * Text of the most recent user message, or \"\" if there is none (e.g. goal-continuation\n * turns with no new user input). An empty query degrades to zero memory-retrieval results\n * by construction (see memory-provider-contract.ts's score-on-empty-query-tokens rule) --\n * no special-casing needed here beyond returning \"\".\n */\nfunction latestUserMessageText(messages: AgentMessage[]): string {\n\tfor (let index = messages.length - 1; index >= 0; index--) {\n\t\tconst message = messages[index];\n\t\tif (message.role !== \"user\") continue;\n\t\tif (typeof message.content === \"string\") return message.content;\n\t\tconst parts: string[] = [];\n\t\tfor (const part of message.content) {\n\t\t\tif (part.type === \"text\") parts.push(part.text);\n\t\t}\n\t\treturn parts.join(\"\\n\");\n\t}\n\treturn \"\";\n}\n\nfunction emptyMemoryRetrievalReport(maxResults: number): MemoryRetrievalReport {\n\treturn { request: { query: \"\", maxResults }, providerReports: [], results: [], contextItems: [] };\n}\n\nexport interface MemoryControllerDeps {\n\t/** Memory-retrieval + prompt-inclusion settings (the opt-in gates for retrieval and surfacing). */\n\tgetSettingsManager(): SettingsManager;\n\t/** Current turn index, stamped into a retrieval request's `createdAtTurn`. */\n\tgetTurnIndex(): number;\n\t/** Agent root — the durable OKF memory docs live under `<agentDir>/okf-memory`. */\n\tgetAgentDir(): string;\n\t/** Workspace root, passed to provider initialization. */\n\tgetCwd(): string;\n\t/** This session's id, passed to provider initialization. */\n\tgetSessionId(): string;\n\t/** Child sessions gate durable memory writes; passed to provider initialization. */\n\tisChildSession(): boolean;\n\t/** Re-derive the tool registry after (re)init so the newly-surfaced memory tools take effect. */\n\trefreshToolRegistry(): void;\n}\n\nexport class MemoryController {\n\tprivate _memoryOkfProvider: ContextMemoryProvider | undefined = undefined;\n\tprivate _latestMemoryRetrievalReport: MemoryRetrievalReport | undefined = undefined;\n\tprivate _latestMemoryPromptInclusionReport: MemoryPromptInclusionReport | undefined = undefined;\n\t/** Plug-and-play memory subsystem. Recreated on each (re)initialize so reload is safe. */\n\tprivate _memoryManager: MemoryManager = new MemoryManager();\n\t/** R4: tracks whether injected recall is actually used, to adapt the recall gate. */\n\tprivate readonly _effectivenessTracker = new EffectivenessTracker();\n\t/** Memory providers registered by extensions via pi.registerMemoryProvider, applied on (re)init. */\n\tprivate _pendingMemoryProviders: MemoryProvider[] = [];\n\n\tprivate readonly deps: MemoryControllerDeps;\n\n\tconstructor(deps: MemoryControllerDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\t/** The live memory manager. Callers reach prefetch / tool-definitions / markers / shutdown through it. */\n\tgetMemoryManager(): MemoryManager {\n\t\treturn this._memoryManager;\n\t}\n\n\t/**\n\t * Fixed path for this slice's local Pi OKF memory documents, shared across sessions\n\t * under this agentDir (not session-scoped, unlike tool-artifacts/context-gc, since OKF\n\t * memory represents durable cross-session knowledge, not a per-session capture). Not\n\t * yet user-configurable -- see the memory-retrieval settings doc comment.\n\t */\n\tprivate _memoryOkfDir(): string {\n\t\treturn join(this.deps.getAgentDir(), \"okf-memory\");\n\t}\n\n\t/**\n\t * Session-scoped, read-only local OKF memory provider. Lazily created ONLY when memory\n\t * retrieval is enabled (see `runMemoryRetrieval`) -- never force-created, so a session\n\t * with the setting off never touches `_memoryOkfDir()` at all (no directory access, no\n\t * creation; `createOkfMemoryProvider` itself never writes/mkdirs either way).\n\t */\n\tprivate _getMemoryOkfProvider(): ContextMemoryProvider {\n\t\tthis._memoryOkfProvider ??= createOkfMemoryProvider({ rootDir: this._memoryOkfDir() });\n\t\treturn this._memoryOkfProvider;\n\t}\n\n\t/**\n\t * Observe-only local memory retrieval (see context/memory-retrieval.ts and\n\t * context/okf-memory-provider.ts): default disabled, opt-in setting. When disabled,\n\t * never constructs the OKF provider (no directory access under `_memoryOkfDir()` at\n\t * all) and returns an empty report -- fully fail-closed. When enabled, queries the\n\t * local, read-only OKF provider with the latest user message text (empty if there is\n\t * none, e.g. a goal-continuation turn -- degrades to zero results by construction, see\n\t * `latestUserMessageText`'s doc comment) under `DEFAULT_LOCAL_MEMORY_EGRESS_POLICY`.\n\t * Retrieved items are only ever stored in the report; nothing here touches `messages`,\n\t * the transcript, or the provider-visible prompt. Never throws into a live turn: any\n\t * failure (including a provider search error) degrades to an empty report.\n\t */\n\tasync runMemoryRetrieval(messages: AgentMessage[]): Promise<MemoryRetrievalReport> {\n\t\ttry {\n\t\t\tconst settings = this.deps.getSettingsManager().getMemoryRetrievalSettings();\n\t\t\tif (!settings.enabled) {\n\t\t\t\tconst report = emptyMemoryRetrievalReport(settings.maxResults);\n\t\t\t\tthis._latestMemoryRetrievalReport = report;\n\t\t\t\treturn report;\n\t\t\t}\n\t\t\tconst report = await retrieveMemoryForContext(\n\t\t\t\t[this._getMemoryOkfProvider()],\n\t\t\t\t{ query: latestUserMessageText(messages), maxResults: settings.maxResults },\n\t\t\t\t{\n\t\t\t\t\tcreatedAtTurn: this.deps.getTurnIndex(),\n\t\t\t\t\tmaxResults: settings.maxResults,\n\t\t\t\t\tdefaultLocalPolicy: DEFAULT_LOCAL_MEMORY_EGRESS_POLICY,\n\t\t\t\t},\n\t\t\t);\n\t\t\tthis._latestMemoryRetrievalReport = report;\n\t\t\treturn report;\n\t\t} catch {\n\t\t\tconst report = emptyMemoryRetrievalReport(0);\n\t\t\tthis._latestMemoryRetrievalReport = report;\n\t\t\treturn report;\n\t\t}\n\t}\n\n\t/** Read-only inspection of the latest memory-retrieval report, for tests/debugging. */\n\tgetMemoryRetrievalReport(): MemoryRetrievalReport {\n\t\treturn this._latestMemoryRetrievalReport ?? emptyMemoryRetrievalReport(0);\n\t}\n\n\t/**\n\t * Bounded prompt-surfacing pilot for local memory evidence (see\n\t * context/memory-prompt-block.ts): opt-in, default disabled, and gated on TWO settings\n\t * (`enabled` AND `includeInPrompt`) plus a non-empty `report.contextItems` -- the first\n\t * two are belt-and-suspenders on top of the fact that `runMemoryRetrieval` already\n\t * leaves `contextItems` empty whenever `enabled` is false, regardless of\n\t * `includeInPrompt`. Reuses the `report` this pass's `runMemoryRetrieval` call already\n\t * computed -- never re-queries the provider here.\n\t *\n\t * Appends exactly one ephemeral `custom`/\"memory_evidence\" message wrapped by\n\t * `wrapUntrustedText` (the same nonce-fenced boundary + always-on system-prompt rule\n\t * used for other untrusted content) to the END of `messages`. This is purely additive\n\t * (never mutates an existing message) and purely transient: `messages` here is the\n\t * array about to be sent to the provider, not `this.agent.state.messages` or anything\n\t * persisted via `sessionManager` -- so the injected message can never reach the\n\t * transcript, regardless of how many times this pass runs.\n\t *\n\t * Also records a `MemoryPromptInclusionReport` (context/memory-diagnostics.ts) at each\n\t * branch below, for context_audit's diagnostic surface only -- this is pure bookkeeping\n\t * alongside the existing branches, not a new branch/condition: the messages returned\n\t * are unchanged by this recording.\n\t */\n\tmaybeAppendMemoryEvidenceBlock(messages: AgentMessage[], report: MemoryRetrievalReport): AgentMessage[] {\n\t\ttry {\n\t\t\tconst settings = this.deps.getSettingsManager().getMemoryRetrievalSettings();\n\t\t\tconst base = {\n\t\t\t\tenabled: settings.enabled,\n\t\t\t\tincludeInPrompt: settings.includeInPrompt,\n\t\t\t\tselectedItemCount: report.contextItems.length,\n\t\t\t};\n\t\t\tif (!settings.enabled) {\n\t\t\t\tthis._latestMemoryPromptInclusionReport = {\n\t\t\t\t\t...base,\n\t\t\t\t\tstatus: \"disabled\",\n\t\t\t\t\tincludedCount: 0,\n\t\t\t\t\tomittedCount: 0,\n\t\t\t\t\tblockChars: 0,\n\t\t\t\t};\n\t\t\t\treturn messages;\n\t\t\t}\n\t\t\tif (!settings.includeInPrompt) {\n\t\t\t\tthis._latestMemoryPromptInclusionReport = {\n\t\t\t\t\t...base,\n\t\t\t\t\tstatus: \"include_disabled\",\n\t\t\t\t\tincludedCount: 0,\n\t\t\t\t\tomittedCount: 0,\n\t\t\t\t\tblockChars: 0,\n\t\t\t\t};\n\t\t\t\treturn messages;\n\t\t\t}\n\t\t\tif (report.contextItems.length === 0) {\n\t\t\t\tthis._latestMemoryPromptInclusionReport = {\n\t\t\t\t\t...base,\n\t\t\t\t\tstatus: \"no_results\",\n\t\t\t\t\tincludedCount: 0,\n\t\t\t\t\tomittedCount: 0,\n\t\t\t\t\tblockChars: 0,\n\t\t\t\t};\n\t\t\t\treturn messages;\n\t\t\t}\n\n\t\t\tconst block = buildMemoryPromptBlock(report.contextItems);\n\t\t\tif (!block.text) {\n\t\t\t\tthis._latestMemoryPromptInclusionReport = {\n\t\t\t\t\t...base,\n\t\t\t\t\tstatus: \"empty_block\",\n\t\t\t\t\tincludedCount: block.includedCount,\n\t\t\t\t\tomittedCount: block.omittedCount,\n\t\t\t\t\tblockChars: 0,\n\t\t\t\t};\n\t\t\t\treturn messages;\n\t\t\t}\n\n\t\t\tconst wrapped = wrapUntrustedText(block.text, \"memory:pi-okf\");\n\t\t\tconst evidenceMessage: CustomMessage = {\n\t\t\t\trole: \"custom\",\n\t\t\t\tcustomType: \"memory_evidence\",\n\t\t\t\tcontent: [{ type: \"text\", text: wrapped }],\n\t\t\t\tdisplay: false,\n\t\t\t\ttimestamp: Date.now(),\n\t\t\t};\n\t\t\tthis._latestMemoryPromptInclusionReport = {\n\t\t\t\t...base,\n\t\t\t\tstatus: \"included\",\n\t\t\t\tincludedCount: block.includedCount,\n\t\t\t\tomittedCount: block.omittedCount,\n\t\t\t\tblockChars: wrapped.length,\n\t\t\t\tsourceLabel: \"memory:pi-okf\",\n\t\t\t};\n\t\t\treturn [...messages, evidenceMessage];\n\t\t} catch {\n\t\t\t// `base` may not exist yet if the throw happened before it was computed (e.g.\n\t\t\t// settings access or `report.contextItems` itself threw), so this branch cannot\n\t\t\t// rely on it -- fall back to safe, fixed defaults rather than risk referencing\n\t\t\t// a partially-evaluated value.\n\t\t\tthis._latestMemoryPromptInclusionReport = {\n\t\t\t\tenabled: false,\n\t\t\t\tincludeInPrompt: false,\n\t\t\t\tselectedItemCount: 0,\n\t\t\t\tstatus: \"failed\",\n\t\t\t\tincludedCount: 0,\n\t\t\t\tomittedCount: 0,\n\t\t\t\tblockChars: 0,\n\t\t\t};\n\t\t\treturn messages;\n\t\t}\n\t}\n\n\t/** Read-only inspection of the latest memory-prompt-inclusion decision, for tests/debugging and context_audit. */\n\tgetMemoryPromptInclusionReport(): MemoryPromptInclusionReport {\n\t\treturn this._latestMemoryPromptInclusionReport ?? defaultMemoryPromptInclusionReport();\n\t}\n\n\t/**\n\t * Combines the already-stored, no-arg latest reports (never re-queries the provider or\n\t * touches the OKF directory) into the safe, allow-list-projected shape context_audit\n\t * exposes. See context/memory-diagnostics.ts for why this projection is allow-list\n\t * based rather than a spread-then-delete of the raw report.\n\t */\n\tgetMemoryAuditDiagnostics(): {\n\t\tretrieval: MemoryRetrievalDiagnostics;\n\t\tpromptInclusion: MemoryPromptInclusionReport;\n\t} {\n\t\tconst settings = this.deps.getSettingsManager().getMemoryRetrievalSettings();\n\t\treturn {\n\t\t\tretrieval: sanitizeMemoryRetrievalReportForDiagnostics(this.getMemoryRetrievalReport(), settings),\n\t\t\tpromptInclusion: this.getMemoryPromptInclusionReport(),\n\t\t};\n\t}\n\n\t/**\n\t * Zero-I/O gate for cross-session recall (R3): skip trivial turns (short acks, slash commands) so\n\t * recall only runs when it could plausibly help. The provider's similarity cutoff is the real\n\t * filter — this just avoids the index query on turns that obviously don't warrant it.\n\t */\n\tshouldAttemptRecall(text: string): boolean {\n\t\tconst t = text.trim();\n\t\tif (t.length < 12 || t.startsWith(\"/\")) return false;\n\t\tconst words = t.split(/\\s+/).filter((w) => w.length >= 3);\n\t\t// R4 adaptive gate: if recall has rarely been used lately (enough samples to trust the signal),\n\t\t// raise the bar so we only recall on clearly substantial turns — and relax it again once recall\n\t\t// starts paying off. Never fully disabled, so the loop can recover.\n\t\tconst recallRarelyUseful =\n\t\t\tthis._effectivenessTracker.sampleCount >= 5 && this._effectivenessTracker.usefulLately() < 0.15;\n\t\treturn words.length >= (recallRarelyUseful ? 6 : 3);\n\t}\n\n\t/** R4: score whether the agent actually used an injected recall page, so the recall gate can adapt. */\n\trecordRecallOutcome(recallText: string, queryText: string, responseText: string): void {\n\t\tthis._effectivenessTracker.recordRecallOutcome(recallText, queryText, responseText);\n\t}\n\n\t/**\n\t * (Re)build the memory subsystem: a fresh MemoryManager (reload-safe), register the bundled\n\t * file-store + any extension-contributed providers, initialize, then surface the memory tools and\n\t * the frozen system-prompt block. Best-effort: never throws into the session lifecycle.\n\t */\n\tasync initialize(): Promise<void> {\n\t\ttry {\n\t\t\t// Release the previous generation's providers (locks/handles) before recreating, so a\n\t\t\t// reload does not orphan the old MemoryManager. No-op on first init / for file-store.\n\t\t\tawait this._memoryManager.shutdownAll().catch(() => {});\n\t\t\tconst manager = new MemoryManager();\n\t\t\tmanager.registerProvider(new FileStoreProvider());\n\t\t\t// Bundled read-only cross-session recall (R3): indexes past-session transcripts and answers\n\t\t\t// prefetch() with a <memory_context> page. Never writes.\n\t\t\tmanager.registerProvider(new TranscriptRecallProvider());\n\t\t\tfor (const provider of this._pendingMemoryProviders) {\n\t\t\t\ttry {\n\t\t\t\t\tmanager.registerProvider(provider);\n\t\t\t\t} catch {\n\t\t\t\t\t// Duplicate name or reserved-tool collision — skip this provider, keep the rest.\n\t\t\t\t}\n\t\t\t}\n\t\t\tthis._memoryManager = manager;\n\t\t\tawait manager.initializeAll(this.deps.getSessionId(), {\n\t\t\t\tagentDir: this.deps.getAgentDir(),\n\t\t\t\tcwd: this.deps.getCwd(),\n\t\t\t\tisChildSession: this.deps.isChildSession(),\n\t\t\t});\n\t\t\t// Surface memory tools + the frozen memory block now that providers are initialized.\n\t\t\t// refreshToolRegistry() ends in setActiveToolsByName(), which rebuilds AND assigns the\n\t\t\t// system prompt (including the memory block), so no explicit _rebuildSystemPrompt is needed.\n\t\t\tthis.deps.refreshToolRegistry();\n\t\t} catch (error) {\n\t\t\tconsole.error(\"Memory subsystem init failed:\", error instanceof Error ? error.message : String(error));\n\t\t}\n\t}\n\n\t/** Register a memory provider contributed by an extension; applied on the next memory (re)init. */\n\tregisterMemoryProvider(provider: MemoryProvider): void {\n\t\tif (!this._pendingMemoryProviders.some((p) => p.name === provider.name)) {\n\t\t\tthis._pendingMemoryProviders.push(provider);\n\t\t}\n\t}\n\n\t/** Reload starts memory providers fresh; loaded extensions re-register before the next `initialize()`. */\n\tclearPendingProviders(): void {\n\t\tthis._pendingMemoryProviders = [];\n\t}\n}\n"]}

package/dist/core/memory-controller.js

@@ -0,0 +1,323 @@
+/**
+ * Memory controller: the session's plug-and-play memory subsystem — the read-only OKF retrieval
+ * provider, the bounded prompt-evidence surfacing pilot, cross-session recall effectiveness, and the
+ * live {@link MemoryManager} (bundled file-store + transcript-recall providers plus any extension
+ * contributions).
+ *
+ * Extracted verbatim from agent-session.ts (god-file decomposition). Owns the lazily-built OKF
+ * provider, the latest retrieval/prompt-inclusion reports, the recreated-on-reload MemoryManager, the
+ * recall {@link EffectivenessTracker}, and the extension-contributed pending providers. Everything
+ * else it needs — settings, the current turn index, agent/workspace dirs, the session id, the
+ * child-session flag, and the tool-registry refresh — is reached through narrow deps accessors rather
+ * than the whole AgentSession.
+ *
+ * Context-transform boundary (deliberate): {@link runMemoryRetrieval} and
+ * {@link maybeAppendMemoryEvidenceBlock} are invoked from the session's context transform as one-line
+ * delegations. This controller deliberately imports no compaction/context-pipeline internals — it only
+ * ever reads settings and builds the retrieval report + the bounded evidence block, so the transform
+ * stays the single owner of the pass ordering.
+ */
+import { join } from "node:path";
+import { defaultMemoryPromptInclusionReport, sanitizeMemoryRetrievalReportForDiagnostics, } from "./context/memory-diagnostics.js";
+import { buildMemoryPromptBlock } from "./context/memory-prompt-block.js";
+import { DEFAULT_LOCAL_MEMORY_EGRESS_POLICY, } from "./context/memory-provider-contract.js";
+import { retrieveMemoryForContext } from "./context/memory-retrieval.js";
+import { createOkfMemoryProvider } from "./context/okf-memory-provider.js";
+import { EffectivenessTracker } from "./memory/effectiveness-tracker.js";
+import { MemoryManager } from "./memory/memory-manager.js";
+import { FileStoreProvider } from "./memory/providers/file-store.js";
+import { TranscriptRecallProvider } from "./memory/providers/transcript-recall.js";
+import { wrapUntrustedText } from "./security/untrusted-boundary.js";
+/**
+ * Text of the most recent user message, or "" if there is none (e.g. goal-continuation
+ * turns with no new user input). An empty query degrades to zero memory-retrieval results
+ * by construction (see memory-provider-contract.ts's score-on-empty-query-tokens rule) --
+ * no special-casing needed here beyond returning "".
+ */
+function latestUserMessageText(messages) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message.role !== "user")
+            continue;
+        if (typeof message.content === "string")
+            return message.content;
+        const parts = [];
+        for (const part of message.content) {
+            if (part.type === "text")
+                parts.push(part.text);
+        }
+        return parts.join("\n");
+    }
+    return "";
+}
+function emptyMemoryRetrievalReport(maxResults) {
+    return { request: { query: "", maxResults }, providerReports: [], results: [], contextItems: [] };
+}
+export class MemoryController {
+    _memoryOkfProvider = undefined;
+    _latestMemoryRetrievalReport = undefined;
+    _latestMemoryPromptInclusionReport = undefined;
+    /** Plug-and-play memory subsystem. Recreated on each (re)initialize so reload is safe. */
+    _memoryManager = new MemoryManager();
+    /** R4: tracks whether injected recall is actually used, to adapt the recall gate. */
+    _effectivenessTracker = new EffectivenessTracker();
+    /** Memory providers registered by extensions via pi.registerMemoryProvider, applied on (re)init. */
+    _pendingMemoryProviders = [];
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** The live memory manager. Callers reach prefetch / tool-definitions / markers / shutdown through it. */
+    getMemoryManager() {
+        return this._memoryManager;
+    }
+    /**
+     * Fixed path for this slice's local Pi OKF memory documents, shared across sessions
+     * under this agentDir (not session-scoped, unlike tool-artifacts/context-gc, since OKF
+     * memory represents durable cross-session knowledge, not a per-session capture). Not
+     * yet user-configurable -- see the memory-retrieval settings doc comment.
+     */
+    _memoryOkfDir() {
+        return join(this.deps.getAgentDir(), "okf-memory");
+    }
+    /**
+     * Session-scoped, read-only local OKF memory provider. Lazily created ONLY when memory
+     * retrieval is enabled (see `runMemoryRetrieval`) -- never force-created, so a session
+     * with the setting off never touches `_memoryOkfDir()` at all (no directory access, no
+     * creation; `createOkfMemoryProvider` itself never writes/mkdirs either way).
+     */
+    _getMemoryOkfProvider() {
+        this._memoryOkfProvider ??= createOkfMemoryProvider({ rootDir: this._memoryOkfDir() });
+        return this._memoryOkfProvider;
+    }
+    /**
+     * Observe-only local memory retrieval (see context/memory-retrieval.ts and
+     * context/okf-memory-provider.ts): default disabled, opt-in setting. When disabled,
+     * never constructs the OKF provider (no directory access under `_memoryOkfDir()` at
+     * all) and returns an empty report -- fully fail-closed. When enabled, queries the
+     * local, read-only OKF provider with the latest user message text (empty if there is
+     * none, e.g. a goal-continuation turn -- degrades to zero results by construction, see
+     * `latestUserMessageText`'s doc comment) under `DEFAULT_LOCAL_MEMORY_EGRESS_POLICY`.
+     * Retrieved items are only ever stored in the report; nothing here touches `messages`,
+     * the transcript, or the provider-visible prompt. Never throws into a live turn: any
+     * failure (including a provider search error) degrades to an empty report.
+     */
+    async runMemoryRetrieval(messages) {
+        try {
+            const settings = this.deps.getSettingsManager().getMemoryRetrievalSettings();
+            if (!settings.enabled) {
+                const report = emptyMemoryRetrievalReport(settings.maxResults);
+                this._latestMemoryRetrievalReport = report;
+                return report;
+            }
+            const report = await retrieveMemoryForContext([this._getMemoryOkfProvider()], { query: latestUserMessageText(messages), maxResults: settings.maxResults }, {
+                createdAtTurn: this.deps.getTurnIndex(),
+                maxResults: settings.maxResults,
+                defaultLocalPolicy: DEFAULT_LOCAL_MEMORY_EGRESS_POLICY,
+            });
+            this._latestMemoryRetrievalReport = report;
+            return report;
+        }
+        catch {
+            const report = emptyMemoryRetrievalReport(0);
+            this._latestMemoryRetrievalReport = report;
+            return report;
+        }
+    }
+    /** Read-only inspection of the latest memory-retrieval report, for tests/debugging. */
+    getMemoryRetrievalReport() {
+        return this._latestMemoryRetrievalReport ?? emptyMemoryRetrievalReport(0);
+    }
+    /**
+     * Bounded prompt-surfacing pilot for local memory evidence (see
+     * context/memory-prompt-block.ts): opt-in, default disabled, and gated on TWO settings
+     * (`enabled` AND `includeInPrompt`) plus a non-empty `report.contextItems` -- the first
+     * two are belt-and-suspenders on top of the fact that `runMemoryRetrieval` already
+     * leaves `contextItems` empty whenever `enabled` is false, regardless of
+     * `includeInPrompt`. Reuses the `report` this pass's `runMemoryRetrieval` call already
+     * computed -- never re-queries the provider here.
+     *
+     * Appends exactly one ephemeral `custom`/"memory_evidence" message wrapped by
+     * `wrapUntrustedText` (the same nonce-fenced boundary + always-on system-prompt rule
+     * used for other untrusted content) to the END of `messages`. This is purely additive
+     * (never mutates an existing message) and purely transient: `messages` here is the
+     * array about to be sent to the provider, not `this.agent.state.messages` or anything
+     * persisted via `sessionManager` -- so the injected message can never reach the
+     * transcript, regardless of how many times this pass runs.
+     *
+     * Also records a `MemoryPromptInclusionReport` (context/memory-diagnostics.ts) at each
+     * branch below, for context_audit's diagnostic surface only -- this is pure bookkeeping
+     * alongside the existing branches, not a new branch/condition: the messages returned
+     * are unchanged by this recording.
+     */
+    maybeAppendMemoryEvidenceBlock(messages, report) {
+        try {
+            const settings = this.deps.getSettingsManager().getMemoryRetrievalSettings();
+            const base = {
+                enabled: settings.enabled,
+                includeInPrompt: settings.includeInPrompt,
+                selectedItemCount: report.contextItems.length,
+            };
+            if (!settings.enabled) {
+                this._latestMemoryPromptInclusionReport = {
+                    ...base,
+                    status: "disabled",
+                    includedCount: 0,
+                    omittedCount: 0,
+                    blockChars: 0,
+                };
+                return messages;
+            }
+            if (!settings.includeInPrompt) {
+                this._latestMemoryPromptInclusionReport = {
+                    ...base,
+                    status: "include_disabled",
+                    includedCount: 0,
+                    omittedCount: 0,
+                    blockChars: 0,
+                };
+                return messages;
+            }
+            if (report.contextItems.length === 0) {
+                this._latestMemoryPromptInclusionReport = {
+                    ...base,
+                    status: "no_results",
+                    includedCount: 0,
+                    omittedCount: 0,
+                    blockChars: 0,
+                };
+                return messages;
+            }
+            const block = buildMemoryPromptBlock(report.contextItems);
+            if (!block.text) {
+                this._latestMemoryPromptInclusionReport = {
+                    ...base,
+                    status: "empty_block",
+                    includedCount: block.includedCount,
+                    omittedCount: block.omittedCount,
+                    blockChars: 0,
+                };
+                return messages;
+            }
+            const wrapped = wrapUntrustedText(block.text, "memory:pi-okf");
+            const evidenceMessage = {
+                role: "custom",
+                customType: "memory_evidence",
+                content: [{ type: "text", text: wrapped }],
+                display: false,
+                timestamp: Date.now(),
+            };
+            this._latestMemoryPromptInclusionReport = {
+                ...base,
+                status: "included",
+                includedCount: block.includedCount,
+                omittedCount: block.omittedCount,
+                blockChars: wrapped.length,
+                sourceLabel: "memory:pi-okf",
+            };
+            return [...messages, evidenceMessage];
+        }
+        catch {
+            // `base` may not exist yet if the throw happened before it was computed (e.g.
+            // settings access or `report.contextItems` itself threw), so this branch cannot
+            // rely on it -- fall back to safe, fixed defaults rather than risk referencing
+            // a partially-evaluated value.
+            this._latestMemoryPromptInclusionReport = {
+                enabled: false,
+                includeInPrompt: false,
+                selectedItemCount: 0,
+                status: "failed",
+                includedCount: 0,
+                omittedCount: 0,
+                blockChars: 0,
+            };
+            return messages;
+        }
+    }
+    /** Read-only inspection of the latest memory-prompt-inclusion decision, for tests/debugging and context_audit. */
+    getMemoryPromptInclusionReport() {
+        return this._latestMemoryPromptInclusionReport ?? defaultMemoryPromptInclusionReport();
+    }
+    /**
+     * Combines the already-stored, no-arg latest reports (never re-queries the provider or
+     * touches the OKF directory) into the safe, allow-list-projected shape context_audit
+     * exposes. See context/memory-diagnostics.ts for why this projection is allow-list
+     * based rather than a spread-then-delete of the raw report.
+     */
+    getMemoryAuditDiagnostics() {
+        const settings = this.deps.getSettingsManager().getMemoryRetrievalSettings();
+        return {
+            retrieval: sanitizeMemoryRetrievalReportForDiagnostics(this.getMemoryRetrievalReport(), settings),
+            promptInclusion: this.getMemoryPromptInclusionReport(),
+        };
+    }
+    /**
+     * Zero-I/O gate for cross-session recall (R3): skip trivial turns (short acks, slash commands) so
+     * recall only runs when it could plausibly help. The provider's similarity cutoff is the real
+     * filter — this just avoids the index query on turns that obviously don't warrant it.
+     */
+    shouldAttemptRecall(text) {
+        const t = text.trim();
+        if (t.length < 12 || t.startsWith("/"))
+            return false;
+        const words = t.split(/\s+/).filter((w) => w.length >= 3);
+        // R4 adaptive gate: if recall has rarely been used lately (enough samples to trust the signal),
+        // raise the bar so we only recall on clearly substantial turns — and relax it again once recall
+        // starts paying off. Never fully disabled, so the loop can recover.
+        const recallRarelyUseful = this._effectivenessTracker.sampleCount >= 5 && this._effectivenessTracker.usefulLately() < 0.15;
+        return words.length >= (recallRarelyUseful ? 6 : 3);
+    }
+    /** R4: score whether the agent actually used an injected recall page, so the recall gate can adapt. */
+    recordRecallOutcome(recallText, queryText, responseText) {
+        this._effectivenessTracker.recordRecallOutcome(recallText, queryText, responseText);
+    }
+    /**
+     * (Re)build the memory subsystem: a fresh MemoryManager (reload-safe), register the bundled
+     * file-store + any extension-contributed providers, initialize, then surface the memory tools and
+     * the frozen system-prompt block. Best-effort: never throws into the session lifecycle.
+     */
+    async initialize() {
+        try {
+            // Release the previous generation's providers (locks/handles) before recreating, so a
+            // reload does not orphan the old MemoryManager. No-op on first init / for file-store.
+            await this._memoryManager.shutdownAll().catch(() => { });
+            const manager = new MemoryManager();
+            manager.registerProvider(new FileStoreProvider());
+            // Bundled read-only cross-session recall (R3): indexes past-session transcripts and answers
+            // prefetch() with a <memory_context> page. Never writes.
+            manager.registerProvider(new TranscriptRecallProvider());
+            for (const provider of this._pendingMemoryProviders) {
+                try {
+                    manager.registerProvider(provider);
+                }
+                catch {
+                    // Duplicate name or reserved-tool collision — skip this provider, keep the rest.
+                }
+            }
+            this._memoryManager = manager;
+            await manager.initializeAll(this.deps.getSessionId(), {
+                agentDir: this.deps.getAgentDir(),
+                cwd: this.deps.getCwd(),
+                isChildSession: this.deps.isChildSession(),
+            });
+            // Surface memory tools + the frozen memory block now that providers are initialized.
+            // refreshToolRegistry() ends in setActiveToolsByName(), which rebuilds AND assigns the
+            // system prompt (including the memory block), so no explicit _rebuildSystemPrompt is needed.
+            this.deps.refreshToolRegistry();
+        }
+        catch (error) {
+            console.error("Memory subsystem init failed:", error instanceof Error ? error.message : String(error));
+        }
+    }
+    /** Register a memory provider contributed by an extension; applied on the next memory (re)init. */
+    registerMemoryProvider(provider) {
+        if (!this._pendingMemoryProviders.some((p) => p.name === provider.name)) {
+            this._pendingMemoryProviders.push(provider);
+        }
+    }
+    /** Reload starts memory providers fresh; loaded extensions re-register before the next `initialize()`. */
+    clearPendingProviders() {
+        this._pendingMemoryProviders = [];
+    }
+}
+//# sourceMappingURL=memory-controller.js.map