open-multi-agent-kit 0.95.0 → 0.95.2

package/dist/core/context-budget-system-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-system-prompt.js","sourceRoot":"","sources":["../../src/core/context-budget-system-prompt.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\ttype ContextBudgetCacheProviderV2,\n\ttype ContextBudgetItemV2,\n\ttype PromptContextBudgetPlanV2,\n\tplanPromptContextBudgetV2,\n} from \"./context-budget-governor-v2.ts\";\nimport { createSystemPromptBudgetItems, escapeXml } from \"./context-budget-system-prompt-items.ts\";\nimport {\n\ttype ContextBudgetTokenizerMode,\n\tcreateTokenCounterForMode,\n\ttype TokenCounterAdapter,\n} from \"./context-budget-token-counter.ts\";\nimport type { ContextFile } from \"./resource-loader.ts\";\nimport type { Skill } from \"./skills.ts\";\n\nexport interface SystemPromptContextBudgetOptions {\n\treadonly maxPromptTokens: number;\n\treadonly responseReserveTokens?: number;\n\treadonly modelId?: string;\n\treadonly tokenizerMode?: ContextBudgetTokenizerMode;\n\treadonly activeSkillNames?: readonly string[];\n\treadonly includeSkillInventory?: boolean;\n\treadonly includeFullContextFiles?: boolean;\n\treadonly tokenCounter?: TokenCounterAdapter;\n\treadonly cacheProvider?: ContextBudgetCacheProviderV2;\n\t/** Maximum number of inactive (non-active) skills to include as items. Default: 15. */\n\treadonly maxInactiveSkills?: number;\n\t/** Current user query text for relevance-aware skill ranking. */\n\treadonly queryContext?: string;\n}\n\nexport interface SystemPromptBudgetedResourcesInput {\n\treadonly basePrompt: string;\n\treadonly contextFiles: readonly ContextFile[];\n\treadonly skills: readonly Skill[];\n\treadonly includeSkills: boolean;\n\treadonly options: SystemPromptContextBudgetOptions;\n}\n\nexport interface SystemPromptBudgetedResources {\n\treadonly text: string;\n\treadonly plan: PromptContextBudgetPlanV2;\n}\n\nexport function renderSystemPromptBudgetedResources(\n\tinput: SystemPromptBudgetedResourcesInput,\n): SystemPromptBudgetedResources {\n\tconst tokenCounter =\n\t\tinput.options.tokenCounter ?? createTokenCounterForMode(input.options.tokenizerMode ?? \"fallback\");\n\tconst modelId = input.options.modelId ?? \"unknown\";\n\tconst baseTokens = tokenCounter.countText(input.basePrompt, modelId).tokens;\n\tconst resourceBudget = Math.max(0, input.options.maxPromptTokens - baseTokens);\n\tconst items = createSystemPromptBudgetItems(input, resourceBudget);\n\tconst plan = planPromptContextBudgetV2({\n\t\tmaxTokens: resourceBudget,\n\t\tresponseReserveTokens: input.options.responseReserveTokens ?? 0,\n\t\tmodelId,\n\t\tpolicyVersion: CONTEXT_BUDGET_POLICY_VERSION_V2,\n\t\tquery: input.options.queryContext,\n\t\titems,\n\t\ttokenCounter,\n\t\tcacheProvider: input.options.cacheProvider,\n\t});\n\tconst included = new Set(plan.includedItemIds);\n\tconst filtered = deduplicatePointerFull(items, included);\n\tconst text = filtered\n\t\t.filter((item) => included.has(item.id))\n\t\t.map(\n\t\t\t(item) =>\n\t\t\t\tplan.selectedRepresentations.find((representation) => representation.itemId === item.id)?.text ?? item.text,\n\t\t)\n\t\t.join(\"\\n\")\n\t\t.trimEnd();\n\tconst note = renderBudgetNote(plan, baseTokens);\n\treturn { text: text ? `${text}\\n${note}` : note, plan };\n}\n\nfunction renderBudgetNote(plan: PromptContextBudgetPlanV2, baseTokens: number): string {\n\tconst omitted = plan.omittedItemIds.length;\n\tconst { cache, counts, diagnosticReasons, tokenOptimizer, tokens } = plan.observability;\n\tconst selectedCacheHits =\n\t\tcache.representationCache.exactHits +\n\t\tcache.representationCache.semanticHits +\n\t\tcache.representationCache.pointerHits;\n\tconst renderedDiagnosticReasons =\n\t\tdiagnosticReasons.length === 0\n\t\t\t? '    <diagnostic_reasons count=\"0\" />'\n\t\t\t: [\n\t\t\t\t\t`    <diagnostic_reasons count=\"${formatObservableInteger(diagnosticReasons.length)}\">`,\n\t\t\t\t\t...diagnosticReasons.map((reason) => `      <reason>${escapeXml(reason)}</reason>`),\n\t\t\t\t\t\"    </diagnostic_reasons>\",\n\t\t\t\t].join(\"\\n\");\n\treturn [\n\t\t\"<context_budget>\",\n\t\t`  <policy>${escapeXml(plan.policyVersion)}</policy>`,\n\t\t`  <plan_hash>${escapeXml(plan.planHash)}</plan_hash>`,\n\t\t`  <base_prompt_tokens>${formatObservableInteger(baseTokens)}</base_prompt_tokens>`,\n\t\t`  <resource_tokens_used>${formatObservableInteger(plan.usedTokens)}</resource_tokens_used>`,\n\t\t`  <resource_tokens_omitted>${formatObservableInteger(plan.omittedTokens)}</resource_tokens_omitted>`,\n\t\t`  <omitted_items>${formatObservableInteger(omitted)}</omitted_items>`,\n\t\t`  <emergency>${plan.emergency ? \"true\" : \"false\"}</emergency>`,\n\t\t\"  <decision_observability>\",\n\t\t`    <counts selected=\"${formatObservableInteger(counts.selected)}\" omitted=\"${formatObservableInteger(counts.omitted)}\" pointer=\"${formatObservableInteger(counts.pointer)}\" compressed=\"${formatObservableInteger(counts.compressed)}\" full=\"${formatObservableInteger(counts.full)}\" retrieval_fallbacks=\"${formatObservableInteger(counts.retrievalFallback)}\" />`,\n\t\t`    <tokens available=\"${formatObservableInteger(tokens.available)}\" used=\"${formatObservableInteger(tokens.used)}\" raw=\"${formatObservableInteger(tokens.raw)}\" omitted=\"${formatObservableInteger(tokens.omitted)}\" token_savings=\"${formatObservableInteger(tokens.tokenSavings)}\" />`,\n\t\t`    <cache_decision plan_hit=\"${cache.planCache.hit ? \"true\" : \"false\"}\" selected_hits=\"${formatObservableInteger(selectedCacheHits)}\" misses=\"${formatObservableInteger(cache.representationCache.misses)}\" stale_rejects=\"${formatObservableInteger(cache.representationCache.staleRejects)}\" negative_hits=\"${formatObservableInteger(cache.representationCache.negativeHits)}\" writes=\"${formatObservableInteger(cache.representationCache.writes)}\" />`,\n\t\trenderedDiagnosticReasons,\n\t\t`    <token_optimizer optimizer_id=\"${escapeXml(tokenOptimizer.optimizerId)}\" status=\"${escapeXml(tokenOptimizer.status)}\" active=\"${tokenOptimizer.active ? \"true\" : \"false\"}\" active_context_budget_optimizer=\"${escapeXml(tokenOptimizer.activeContextBudgetOptimizer)}\" compatibility_only=\"${tokenOptimizer.compatibilityOnly ? \"true\" : \"false\"}\" />`,\n\t\t\"  </decision_observability>\",\n\t\t\"  <note>Some low-priority resource inventory may be represented by pointers. Use read on referenced paths when needed.</note>\",\n\t\t\"</context_budget>\",\n\t].join(\"\\n\");\n}\n\nfunction formatObservableInteger(value: number): string {\n\tif (!Number.isFinite(value)) {\n\t\treturn \"0\";\n\t}\n\treturn String(Math.max(0, Math.floor(value)));\n}\n\n/**\n * R3: When a context-full item is included, exclude the matching pointer\n * so the same file does not consume tokens twice.\n */\nfunction deduplicatePointerFull(\n\titems: readonly ContextBudgetItemV2[],\n\tincluded: ReadonlySet<string>,\n): readonly ContextBudgetItemV2[] {\n\tconst includedFullPaths = new Set<string>();\n\tfor (const item of items) {\n\t\tif (item.id.startsWith(\"context-full:\") && included.has(item.id)) {\n\t\t\tconst path = item.id.slice(\"context-full:\".length);\n\t\t\tincludedFullPaths.add(path);\n\t\t}\n\t}\n\tif (includedFullPaths.size === 0) {\n\t\treturn items;\n\t}\n\treturn items.filter((item) => {\n\t\tif (!item.id.startsWith(\"context-pointer:\")) {\n\t\t\treturn true;\n\t\t}\n\t\tconst path = item.id.slice(\"context-pointer:\".length);\n\t\treturn !includedFullPaths.has(path);\n\t});\n}\n"]}
+{"version":3,"file":"context-budget-system-prompt.js","sourceRoot":"","sources":["../../src/core/context-budget-system-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,gCAAgC,EAIhC,yBAAyB,GACzB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,6BAA6B,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACnG,OAAO,EAEN,yBAAyB,GAEzB,MAAM,mCAAmC,CAAC;AAiC3C,MAAM,UAAU,mCAAmC,CAClD,KAAyC,EACT;IAChC,MAAM,YAAY,GACjB,KAAK,CAAC,OAAO,CAAC,YAAY,IAAI,yBAAyB,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,IAAI,UAAU,CAAC,CAAC;IACpG,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,IAAI,SAAS,CAAC;IACnD,MAAM,UAAU,GAAG,YAAY,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IAC5E,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,eAAe,GAAG,UAAU,CAAC,CAAC;IAC/E,MAAM,KAAK,GAAG,6BAA6B,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,yBAAyB,CAAC;QACtC,SAAS,EAAE,cAAc;QACzB,qBAAqB,EAAE,KAAK,CAAC,OAAO,CAAC,qBAAqB,IAAI,CAAC;QAC/D,OAAO;QACP,aAAa,EAAE,gCAAgC;QAC/C,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,YAAY;QACjC,KAAK;QACL,YAAY;QACZ,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,aAAa;KAC1C,CAAC,CAAC;IACH,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChG,OAAO,EAAE,IAAI,EAAE,qBAAqB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;IACpD,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,sBAAsB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,QAAQ;SACnB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;SACvC,GAAG,CACH,CAAC,IAAI,EAAE,EAAE,CACR,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,cAAc,CAAC,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC,IAAI,CAC5G;SACA,IAAI,CAAC,IAAI,CAAC;SACV,OAAO,EAAE,CAAC;IACZ,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAChD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;AAAA,CACxD;AAED,SAAS,qBAAqB,CAAC,IAA+B,EAAU;IACvE,OAAO;QACN,kBAAkB;QAClB,aAAa,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,WAAW;QACrD,+BAA+B,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM;QAC9F,0BAA0B,CAAC,IAAI,EAAE,IAAI,CAAC;QACtC,mBAAmB;KACnB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAAA,CACb;AAED,SAAS,gBAAgB,CAAC,IAA+B,EAAE,UAAkB,EAAU;IACtF,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC;IAC3C,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC;IACxE,MAAM,iBAAiB,GACtB,KAAK,CAAC,mBAAmB,CAAC,SAAS;QACnC,KAAK,CAAC,mBAAmB,CAAC,YAAY;QACtC,KAAK,CAAC,mBAAmB,CAAC,WAAW,CAAC;IACvC,MAAM,yBAAyB,GAC9B,iBAAiB,CAAC,MAAM,KAAK,CAAC;QAC7B,CAAC,CAAC,sCAAsC;QACxC,CAAC,CAAC;YACA,kCAAkC,uBAAuB,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI;YACvF,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,iBAAiB,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC;YACnF,2BAA2B;SAC3B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,OAAO;QACN,kBAAkB;QAClB,aAAa,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,WAAW;QACrD,gBAAgB,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc;QACtD,yBAAyB,uBAAuB,CAAC,UAAU,CAAC,uBAAuB;QACnF,2BAA2B,uBAAuB,CAAC,IAAI,CAAC,UAAU,CAAC,yBAAyB;QAC5F,8BAA8B,uBAAuB,CAAC,IAAI,CAAC,aAAa,CAAC,4BAA4B;QACrG,oBAAoB,uBAAuB,CAAC,OAAO,CAAC,kBAAkB;QACtE,gBAAgB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,cAAc;QAC/D,4BAA4B;QAC5B,yBAAyB,uBAAuB,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,uBAAuB,CAAC,MAAM,CAAC,OAAO,CAAC,cAAc,uBAAuB,CAAC,MAAM,CAAC,OAAO,CAAC,iBAAiB,uBAAuB,CAAC,MAAM,CAAC,UAAU,CAAC,WAAW,uBAAuB,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,uBAAuB,CAAC,MAAM,CAAC,iBAAiB,CAAC,MAAM;QACtW,0BAA0B,uBAAuB,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,uBAAuB,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,uBAAuB,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,uBAAuB,CAAC,MAAM,CAAC,OAAO,CAAC,oBAAoB,uBAAuB,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM;QAC1R,iCAAiC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,oBAAoB,uBAAuB,CAAC,iBAAiB,CAAC,aAAa,uBAAuB,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,oBAAoB,uBAAuB,CAAC,KAAK,CAAC,mBAAmB,CAAC,YAAY,CAAC,oBAAoB,uBAAuB,CAAC,KAAK,CAAC,mBAAmB,CAAC,YAAY,CAAC,aAAa,uBAAuB,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,MAAM;QAC7b,yBAAyB;QACzB,0BAA0B,CAAC,IAAI,EAAE,MAAM,CAAC;QACxC,6BAA6B;QAC7B,+HAA+H;QAC/H,mBAAmB;KACnB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAAA,CACb;AAED,SAAS,0BAA0B,CAAC,IAA+B,EAAE,MAAc,EAAU;IAC5F,MAAM,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC;IAC9C,OAAO,GAAG,MAAM,kCAAkC,SAAS,CAAC,cAAc,CAAC,WAAW,CAAC,aAAa,SAAS,CAAC,cAAc,CAAC,MAAM,CAAC,aAAa,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,sCAAsC,SAAS,CAAC,cAAc,CAAC,4BAA4B,CAAC,yBAAyB,cAAc,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC;AAAA,CACxW;AAED,SAAS,uBAAuB,CAAC,KAAa,EAAU;IACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,GAAG,CAAC;IACZ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAAA,CAC9C;AAED;;;GAGG;AACH,SAAS,sBAAsB,CAC9B,KAAqC,EACrC,QAA6B,EACI;IACjC,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAClE,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;YACnD,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;IACF,CAAC;IACD,IAAI,iBAAiB,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAC7C,OAAO,IAAI,CAAC;QACb,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACtD,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAAA,CACpC,CAAC,CAAC;AAAA,CACH","sourcesContent":["import {\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\ttype ContextBudgetCacheProviderV2,\n\ttype ContextBudgetItemV2,\n\ttype PromptContextBudgetPlanV2,\n\tplanPromptContextBudgetV2,\n} from \"./context-budget-governor-v2.ts\";\nimport { createSystemPromptBudgetItems, escapeXml } from \"./context-budget-system-prompt-items.ts\";\nimport {\n\ttype ContextBudgetTokenizerMode,\n\tcreateTokenCounterForMode,\n\ttype TokenCounterAdapter,\n} from \"./context-budget-token-counter.ts\";\nimport type { ContextFile } from \"./resource-loader.ts\";\nimport type { Skill } from \"./skills.ts\";\n\nexport interface SystemPromptContextBudgetOptions {\n\treadonly maxPromptTokens: number;\n\treadonly responseReserveTokens?: number;\n\treadonly modelId?: string;\n\treadonly tokenizerMode?: ContextBudgetTokenizerMode;\n\treadonly activeSkillNames?: readonly string[];\n\treadonly includeSkillInventory?: boolean;\n\treadonly includeFullContextFiles?: boolean;\n\treadonly tokenCounter?: TokenCounterAdapter;\n\treadonly cacheProvider?: ContextBudgetCacheProviderV2;\n\t/** Maximum number of inactive (non-active) skills to include as items. Default: 15. */\n\treadonly maxInactiveSkills?: number;\n\t/** Current user query text for relevance-aware skill ranking. */\n\treadonly queryContext?: string;\n}\n\nexport interface SystemPromptBudgetedResourcesInput {\n\treadonly basePrompt: string;\n\treadonly contextFiles: readonly ContextFile[];\n\treadonly skills: readonly Skill[];\n\treadonly includeSkills: boolean;\n\treadonly options: SystemPromptContextBudgetOptions;\n}\n\nexport interface SystemPromptBudgetedResources {\n\treadonly text: string;\n\treadonly plan: PromptContextBudgetPlanV2;\n}\n\nexport function renderSystemPromptBudgetedResources(\n\tinput: SystemPromptBudgetedResourcesInput,\n): SystemPromptBudgetedResources {\n\tconst tokenCounter =\n\t\tinput.options.tokenCounter ?? createTokenCounterForMode(input.options.tokenizerMode ?? \"fallback\");\n\tconst modelId = input.options.modelId ?? \"unknown\";\n\tconst baseTokens = tokenCounter.countText(input.basePrompt, modelId).tokens;\n\tconst resourceBudget = Math.max(0, input.options.maxPromptTokens - baseTokens);\n\tconst items = createSystemPromptBudgetItems(input, resourceBudget);\n\tconst plan = planPromptContextBudgetV2({\n\t\tmaxTokens: resourceBudget,\n\t\tresponseReserveTokens: input.options.responseReserveTokens ?? 0,\n\t\tmodelId,\n\t\tpolicyVersion: CONTEXT_BUDGET_POLICY_VERSION_V2,\n\t\tquery: input.options.queryContext,\n\t\titems,\n\t\ttokenCounter,\n\t\tcacheProvider: input.options.cacheProvider,\n\t});\n\tif (items.length === 0 && !plan.emergency && plan.observability.diagnosticReasons.length === 0) {\n\t\treturn { text: renderEmptyBudgetNote(plan), plan };\n\t}\n\n\tconst included = new Set(plan.includedItemIds);\n\tconst filtered = deduplicatePointerFull(items, included);\n\tconst text = filtered\n\t\t.filter((item) => included.has(item.id))\n\t\t.map(\n\t\t\t(item) =>\n\t\t\t\tplan.selectedRepresentations.find((representation) => representation.itemId === item.id)?.text ?? item.text,\n\t\t)\n\t\t.join(\"\\n\")\n\t\t.trimEnd();\n\tconst note = renderBudgetNote(plan, baseTokens);\n\treturn { text: text ? `${text}\\n${note}` : note, plan };\n}\n\nfunction renderEmptyBudgetNote(plan: PromptContextBudgetPlanV2): string {\n\treturn [\n\t\t\"<context_budget>\",\n\t\t`  <policy>${escapeXml(plan.policyVersion)}</policy>`,\n\t\t`  <cache_decision plan_hit=\"${plan.observability.cache.planCache.hit ? \"true\" : \"false\"}\" />`,\n\t\trenderTokenOptimizerStatus(plan, \"  \"),\n\t\t\"</context_budget>\",\n\t].join(\"\\n\");\n}\n\nfunction renderBudgetNote(plan: PromptContextBudgetPlanV2, baseTokens: number): string {\n\tconst omitted = plan.omittedItemIds.length;\n\tconst { cache, counts, diagnosticReasons, tokens } = plan.observability;\n\tconst selectedCacheHits =\n\t\tcache.representationCache.exactHits +\n\t\tcache.representationCache.semanticHits +\n\t\tcache.representationCache.pointerHits;\n\tconst renderedDiagnosticReasons =\n\t\tdiagnosticReasons.length === 0\n\t\t\t? '    <diagnostic_reasons count=\"0\" />'\n\t\t\t: [\n\t\t\t\t\t`    <diagnostic_reasons count=\"${formatObservableInteger(diagnosticReasons.length)}\">`,\n\t\t\t\t\t...diagnosticReasons.map((reason) => `      <reason>${escapeXml(reason)}</reason>`),\n\t\t\t\t\t\"    </diagnostic_reasons>\",\n\t\t\t\t].join(\"\\n\");\n\treturn [\n\t\t\"<context_budget>\",\n\t\t`  <policy>${escapeXml(plan.policyVersion)}</policy>`,\n\t\t`  <plan_hash>${escapeXml(plan.planHash)}</plan_hash>`,\n\t\t`  <base_prompt_tokens>${formatObservableInteger(baseTokens)}</base_prompt_tokens>`,\n\t\t`  <resource_tokens_used>${formatObservableInteger(plan.usedTokens)}</resource_tokens_used>`,\n\t\t`  <resource_tokens_omitted>${formatObservableInteger(plan.omittedTokens)}</resource_tokens_omitted>`,\n\t\t`  <omitted_items>${formatObservableInteger(omitted)}</omitted_items>`,\n\t\t`  <emergency>${plan.emergency ? \"true\" : \"false\"}</emergency>`,\n\t\t\"  <decision_observability>\",\n\t\t`    <counts selected=\"${formatObservableInteger(counts.selected)}\" omitted=\"${formatObservableInteger(counts.omitted)}\" pointer=\"${formatObservableInteger(counts.pointer)}\" compressed=\"${formatObservableInteger(counts.compressed)}\" full=\"${formatObservableInteger(counts.full)}\" retrieval_fallbacks=\"${formatObservableInteger(counts.retrievalFallback)}\" />`,\n\t\t`    <tokens available=\"${formatObservableInteger(tokens.available)}\" used=\"${formatObservableInteger(tokens.used)}\" raw=\"${formatObservableInteger(tokens.raw)}\" omitted=\"${formatObservableInteger(tokens.omitted)}\" token_savings=\"${formatObservableInteger(tokens.tokenSavings)}\" />`,\n\t\t`    <cache_decision plan_hit=\"${cache.planCache.hit ? \"true\" : \"false\"}\" selected_hits=\"${formatObservableInteger(selectedCacheHits)}\" misses=\"${formatObservableInteger(cache.representationCache.misses)}\" stale_rejects=\"${formatObservableInteger(cache.representationCache.staleRejects)}\" negative_hits=\"${formatObservableInteger(cache.representationCache.negativeHits)}\" writes=\"${formatObservableInteger(cache.representationCache.writes)}\" />`,\n\t\trenderedDiagnosticReasons,\n\t\trenderTokenOptimizerStatus(plan, \"    \"),\n\t\t\"  </decision_observability>\",\n\t\t\"  <note>Some low-priority resource inventory may be represented by pointers. Use read on referenced paths when needed.</note>\",\n\t\t\"</context_budget>\",\n\t].join(\"\\n\");\n}\n\nfunction renderTokenOptimizerStatus(plan: PromptContextBudgetPlanV2, indent: string): string {\n\tconst { tokenOptimizer } = plan.observability;\n\treturn `${indent}<token_optimizer optimizer_id=\"${escapeXml(tokenOptimizer.optimizerId)}\" status=\"${escapeXml(tokenOptimizer.status)}\" active=\"${tokenOptimizer.active ? \"true\" : \"false\"}\" active_context_budget_optimizer=\"${escapeXml(tokenOptimizer.activeContextBudgetOptimizer)}\" compatibility_only=\"${tokenOptimizer.compatibilityOnly ? \"true\" : \"false\"}\" />`;\n}\n\nfunction formatObservableInteger(value: number): string {\n\tif (!Number.isFinite(value)) {\n\t\treturn \"0\";\n\t}\n\treturn String(Math.max(0, Math.floor(value)));\n}\n\n/**\n * R3: When a context-full item is included, exclude the matching pointer\n * so the same file does not consume tokens twice.\n */\nfunction deduplicatePointerFull(\n\titems: readonly ContextBudgetItemV2[],\n\tincluded: ReadonlySet<string>,\n): readonly ContextBudgetItemV2[] {\n\tconst includedFullPaths = new Set<string>();\n\tfor (const item of items) {\n\t\tif (item.id.startsWith(\"context-full:\") && included.has(item.id)) {\n\t\t\tconst path = item.id.slice(\"context-full:\".length);\n\t\t\tincludedFullPaths.add(path);\n\t\t}\n\t}\n\tif (includedFullPaths.size === 0) {\n\t\treturn items;\n\t}\n\treturn items.filter((item) => {\n\t\tif (!item.id.startsWith(\"context-pointer:\")) {\n\t\t\treturn true;\n\t\t}\n\t\tconst path = item.id.slice(\"context-pointer:\".length);\n\t\treturn !includedFullPaths.has(path);\n\t});\n}\n"]}

package/dist/core/context-budget-v2-cache-disk.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Workspace-layer disk persistence for the context-budget-v2 representation
+ * cache.
+ *
+ * The in-memory provider (`context-budget-v2-cache-provider.ts`) dies with the
+ * process, so every new session re-renders and re-compresses context it already
+ * paid for. This provider keeps the same synchronous
+ * `ContextBudgetCacheProviderV2` contract and adds a bounded, atomically
+ * written JSON snapshot on disk.
+ *
+ * Scope: representation entries and negative entries only. Plan entries stay in
+ * memory on purpose — a plan is session-scoped (its key folds in the
+ * invalidation snapshot), so persisting it would only ever store misses.
+ *
+ * Safety: reads go through the same validator as the memory provider
+ * (`validateContextBudgetRepresentationCacheEntryV2`), which re-checks source
+ * hash, representation fingerprint, model, tokenizer, policy version and TTL.
+ * A corrupt, truncated, oversized, or schema-mismatched snapshot is discarded
+ * and the cache simply starts empty; a cache is never load-bearing for
+ * correctness.
+ */
+import { type ContextCacheInvalidationSnapshot } from "./context-budget-v2-cache-invalidation.ts";
+import type { ContextBudgetCacheLayerV2, ContextBudgetCacheProviderV2, ContextBudgetNegativeCacheEntryV2, ContextBudgetPlanCacheEntryV2, ContextBudgetPlanCacheReadV2, ContextBudgetRepresentationCacheEntryV2, ContextBudgetRepresentationCacheReadV2 } from "./context-budget-v2-types.ts";
+export declare const CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION: "context-budget-v2-diskcache-1";
+/** Default cap on persisted representation entries. */
+export declare const DEFAULT_DISK_CACHE_MAX_ENTRIES = 2048;
+/** Default cap on the persisted snapshot size. Oversized snapshots are dropped on load. */
+export declare const DEFAULT_DISK_CACHE_MAX_BYTES: number;
+/** Default write-behind debounce. Collapses a burst of writes into a single flush. */
+export declare const DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS = 750;
+/** Default cap on a single persisted representation's text length. */
+export declare const DEFAULT_DISK_CACHE_MAX_ENTRY_TEXT_LENGTH: number;
+export interface DiskContextBudgetCacheOptionsV2 {
+    /** Directory holding the snapshot file. Created on first flush. */
+    readonly dir: string;
+    /** Cache layer reported on reads. Defaults to `workspace`. */
+    readonly layer?: ContextBudgetCacheLayerV2;
+    /** Max persisted representation entries (LRU). */
+    readonly maxEntries?: number;
+    /** Max accepted snapshot size in bytes. */
+    readonly maxBytes?: number;
+    /** Max persisted text length for a single entry. */
+    readonly maxEntryTextLength?: number;
+    /** Write-behind debounce in ms. `0` flushes synchronously on every write. */
+    readonly flushDebounceMs?: number;
+    /** Injectable clock, for tests. */
+    readonly now?: () => number;
+}
+/**
+ * Create a disk backed workspace cache provider. Loading is synchronous and
+ * best-effort: any failure yields an empty in-memory cache rather than throwing,
+ * because a cache miss is always a legal outcome.
+ */
+export declare function createDiskContextBudgetCacheProviderV2(options: DiskContextBudgetCacheOptionsV2): DiskContextBudgetCacheProviderV2;
+export declare class DiskContextBudgetCacheProviderV2 implements ContextBudgetCacheProviderV2 {
+    private readonly representations;
+    private readonly negatives;
+    /** Plans stay in memory: their keys are session-scoped, so persisting them stores only misses. */
+    private readonly plans;
+    private readonly layer;
+    private readonly maxEntries;
+    private readonly maxBytes;
+    private readonly maxEntryTextLength;
+    private readonly flushDebounceMs;
+    private readonly now;
+    private readonly snapshotPath;
+    private invalidationSnapshot;
+    private dirty;
+    private flushTimer;
+    private loadError;
+    constructor(options: DiskContextBudgetCacheOptionsV2);
+    /** Absolute path of the persisted snapshot. */
+    get snapshotFilePath(): string;
+    /** Reason the on-disk snapshot was rejected, if it was. `undefined` on a clean load or a cold start. */
+    get lastLoadError(): string | undefined;
+    /** Number of representation entries currently held. */
+    get size(): number;
+    private load;
+    private markDirty;
+    /**
+     * Write the snapshot to disk atomically (temp file + rename). Best-effort:
+     * a failed flush leaves the previous snapshot intact and keeps the entries
+     * in memory. Returns `true` when a snapshot was written.
+     */
+    flush(): boolean;
+    /** Cancel any pending flush and persist immediately. Safe to call more than once. */
+    close(): void;
+    getInvalidationSnapshot(): ContextCacheInvalidationSnapshot | undefined;
+    setInvalidationSnapshot(snapshot: ContextCacheInvalidationSnapshot): void;
+    readRepresentation(key: string): ContextBudgetRepresentationCacheReadV2 | undefined;
+    writeRepresentation(input: {
+        readonly key: string;
+        readonly entry: ContextBudgetRepresentationCacheEntryV2;
+    }): void;
+    deleteRepresentation(key: string): void;
+    readNegativeRepresentation(key: string): ContextBudgetNegativeCacheEntryV2 | undefined;
+    writeNegativeRepresentation(input: {
+        readonly key: string;
+        readonly reason: string;
+    }): void;
+    deleteNegativeRepresentation(key: string): void;
+    readPlan(key: string): ContextBudgetPlanCacheReadV2 | undefined;
+    writePlan(input: {
+        readonly key: string;
+        readonly entry: ContextBudgetPlanCacheEntryV2;
+    }): void;
+    deletePlan(key: string): void;
+}
+//# sourceMappingURL=context-budget-v2-cache-disk.d.ts.map

package/dist/core/context-budget-v2-cache-disk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-v2-cache-disk.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-cache-disk.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Workspace-layer disk persistence for the context-budget-v2 representation\n * cache.\n *\n * The in-memory provider (`context-budget-v2-cache-provider.ts`) dies with the\n * process, so every new session re-renders and re-compresses context it already\n * paid for. This provider keeps the same synchronous\n * `ContextBudgetCacheProviderV2` contract and adds a bounded, atomically\n * written JSON snapshot on disk.\n *\n * Scope: representation entries and negative entries only. Plan entries stay in\n * memory on purpose — a plan is session-scoped (its key folds in the\n * invalidation snapshot), so persisting it would only ever store misses.\n *\n * Safety: reads go through the same validator as the memory provider\n * (`validateContextBudgetRepresentationCacheEntryV2`), which re-checks source\n * hash, representation fingerprint, model, tokenizer, policy version and TTL.\n * A corrupt, truncated, oversized, or schema-mismatched snapshot is discarded\n * and the cache simply starts empty; a cache is never load-bearing for\n * correctness.\n */\n\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { containsCredentialShape } from \"./compaction/transaction.ts\";\nimport {\n\ttype ContextCacheInvalidationSnapshot,\n\tcreateContextCacheInvalidationSnapshot,\n} from \"./context-budget-v2-cache-invalidation.ts\";\nimport type {\n\tContextBudgetCacheLayerV2,\n\tContextBudgetCacheProviderV2,\n\tContextBudgetNegativeCacheEntryV2,\n\tContextBudgetPlanCacheEntryV2,\n\tContextBudgetPlanCacheReadV2,\n\tContextBudgetRepresentationCacheEntryV2,\n\tContextBudgetRepresentationCacheReadV2,\n} from \"./context-budget-v2-types.ts\";\n\nexport const CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION = \"context-budget-v2-diskcache-1\" as const;\n\n/** Default cap on persisted representation entries. */\nexport const DEFAULT_DISK_CACHE_MAX_ENTRIES = 2048;\n/** Default cap on the persisted snapshot size. Oversized snapshots are dropped on load. */\nexport const DEFAULT_DISK_CACHE_MAX_BYTES = 32 * 1024 * 1024;\n/** Default write-behind debounce. Collapses a burst of writes into a single flush. */\nexport const DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS = 750;\n/** Default cap on a single persisted representation's text length. */\nexport const DEFAULT_DISK_CACHE_MAX_ENTRY_TEXT_LENGTH = 512 * 1024;\n\nexport interface DiskContextBudgetCacheOptionsV2 {\n\t/** Directory holding the snapshot file. Created on first flush. */\n\treadonly dir: string;\n\t/** Cache layer reported on reads. Defaults to `workspace`. */\n\treadonly layer?: ContextBudgetCacheLayerV2;\n\t/** Max persisted representation entries (LRU). */\n\treadonly maxEntries?: number;\n\t/** Max accepted snapshot size in bytes. */\n\treadonly maxBytes?: number;\n\t/** Max persisted text length for a single entry. */\n\treadonly maxEntryTextLength?: number;\n\t/** Write-behind debounce in ms. `0` flushes synchronously on every write. */\n\treadonly flushDebounceMs?: number;\n\t/** Injectable clock, for tests. */\n\treadonly now?: () => number;\n}\n\ninterface DiskSnapshotFileV2 {\n\treadonly schemaVersion: typeof CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION;\n\treadonly representations: readonly (readonly [string, ContextBudgetRepresentationCacheEntryV2])[];\n\treadonly negatives: readonly (readonly [string, ContextBudgetNegativeCacheEntryV2])[];\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction containsCredentialShapeInValue(value: unknown): boolean {\n\tconst pending: unknown[] = [value];\n\tconst seen = new Set<object>();\n\twhile (pending.length > 0) {\n\t\tconst current = pending.pop();\n\t\tif (typeof current === \"string\") {\n\t\t\tif (containsCredentialShape(current)) return true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (typeof current !== \"object\" || current === null || seen.has(current)) continue;\n\t\tseen.add(current);\n\t\tif (Array.isArray(current)) {\n\t\t\tpending.push(...current);\n\t\t\tcontinue;\n\t\t}\n\t\tfor (const [key, nested] of Object.entries(current)) {\n\t\t\tif (containsCredentialShape(key)) return true;\n\t\t\tpending.push(nested);\n\t\t}\n\t}\n\treturn false;\n}\n\nfunction isPersistableRepresentation(\n\tvalue: unknown,\n\tmaxEntryTextLength: number,\n): value is ContextBudgetRepresentationCacheEntryV2 {\n\tif (!isRecord(value)) return false;\n\tif (typeof value.kind !== \"string\") return false;\n\tif (typeof value.text !== \"string\" || value.text.length > maxEntryTextLength) return false;\n\tif (containsCredentialShapeInValue(value)) return false;\n\tconst estimated = value.estimatedTokens;\n\tif (typeof estimated !== \"number\" || !Number.isFinite(estimated) || estimated < 0) return false;\n\tif (typeof value.fidelity !== \"string\") return false;\n\tif (typeof value.sourceHash !== \"string\" || value.sourceHash.length === 0) return false;\n\tif (typeof value.representationFingerprint !== \"string\") return false;\n\tif (typeof value.modelId !== \"string\") return false;\n\tif (typeof value.tokenizerId !== \"string\") return false;\n\tif (typeof value.policyVersion !== \"string\") return false;\n\treturn true;\n}\n\nfunction isPersistableNegative(value: unknown): value is ContextBudgetNegativeCacheEntryV2 {\n\treturn isRecord(value) && typeof value.reason === \"string\" && !containsCredentialShapeInValue(value);\n}\n\nfunction readLru<T>(store: Map<string, T>, key: string): T | undefined {\n\tconst entry = store.get(key);\n\tif (entry === undefined) return undefined;\n\tstore.delete(key);\n\tstore.set(key, entry);\n\treturn entry;\n}\n\nfunction writeLru<T>(store: Map<string, T>, key: string, entry: T, maxEntries: number): void {\n\tstore.delete(key);\n\tstore.set(key, entry);\n\twhile (store.size > maxEntries) {\n\t\tconst oldestKey = store.keys().next().value;\n\t\tif (oldestKey === undefined) return;\n\t\tstore.delete(oldestKey);\n\t}\n}\n\n/**\n * Create a disk backed workspace cache provider. Loading is synchronous and\n * best-effort: any failure yields an empty in-memory cache rather than throwing,\n * because a cache miss is always a legal outcome.\n */\nexport function createDiskContextBudgetCacheProviderV2(\n\toptions: DiskContextBudgetCacheOptionsV2,\n): DiskContextBudgetCacheProviderV2 {\n\treturn new DiskContextBudgetCacheProviderV2(options);\n}\n\nexport class DiskContextBudgetCacheProviderV2 implements ContextBudgetCacheProviderV2 {\n\tprivate readonly representations = new Map<string, ContextBudgetRepresentationCacheEntryV2>();\n\tprivate readonly negatives = new Map<string, ContextBudgetNegativeCacheEntryV2>();\n\t/** Plans stay in memory: their keys are session-scoped, so persisting them stores only misses. */\n\tprivate readonly plans = new Map<string, ContextBudgetPlanCacheEntryV2>();\n\tprivate readonly layer: ContextBudgetCacheLayerV2;\n\tprivate readonly maxEntries: number;\n\tprivate readonly maxBytes: number;\n\tprivate readonly maxEntryTextLength: number;\n\tprivate readonly flushDebounceMs: number;\n\tprivate readonly now: () => number;\n\tprivate readonly snapshotPath: string;\n\tprivate invalidationSnapshot: ContextCacheInvalidationSnapshot | undefined;\n\tprivate dirty = false;\n\tprivate flushTimer: ReturnType<typeof setTimeout> | undefined;\n\tprivate loadError: string | undefined;\n\n\tconstructor(options: DiskContextBudgetCacheOptionsV2) {\n\t\tthis.layer = options.layer ?? \"workspace\";\n\t\tthis.maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_DISK_CACHE_MAX_ENTRIES);\n\t\tthis.maxBytes = Math.max(1024, options.maxBytes ?? DEFAULT_DISK_CACHE_MAX_BYTES);\n\t\tthis.maxEntryTextLength = Math.max(1, options.maxEntryTextLength ?? DEFAULT_DISK_CACHE_MAX_ENTRY_TEXT_LENGTH);\n\t\tthis.flushDebounceMs = Math.max(0, options.flushDebounceMs ?? DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS);\n\t\tthis.now = options.now ?? Date.now;\n\t\tthis.snapshotPath = path.join(options.dir, \"representations.json\");\n\t\tthis.load();\n\t}\n\n\t/** Absolute path of the persisted snapshot. */\n\tget snapshotFilePath(): string {\n\t\treturn this.snapshotPath;\n\t}\n\n\t/** Reason the on-disk snapshot was rejected, if it was. `undefined` on a clean load or a cold start. */\n\tget lastLoadError(): string | undefined {\n\t\treturn this.loadError;\n\t}\n\n\t/** Number of representation entries currently held. */\n\tget size(): number {\n\t\treturn this.representations.size;\n\t}\n\n\tprivate load(): void {\n\t\tlet raw: string;\n\t\ttry {\n\t\t\tconst stat = fs.statSync(this.snapshotPath);\n\t\t\tif (stat.size > this.maxBytes) {\n\t\t\t\tthis.loadError = `snapshot exceeds maxBytes (${stat.size} > ${this.maxBytes})`;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\traw = fs.readFileSync(this.snapshotPath, \"utf8\");\n\t\t} catch {\n\t\t\t// Cold start: no snapshot yet, or it is unreadable. Both are normal.\n\t\t\treturn;\n\t\t}\n\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(raw);\n\t\t} catch {\n\t\t\tthis.loadError = \"snapshot is not valid JSON\";\n\t\t\treturn;\n\t\t}\n\t\tif (!isRecord(parsed) || parsed.schemaVersion !== CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION) {\n\t\t\tthis.loadError = \"snapshot schema mismatch\";\n\t\t\treturn;\n\t\t}\n\n\t\tif (containsCredentialShapeInValue(parsed)) {\n\t\t\tthis.loadError = \"snapshot contains credential-shaped text\";\n\t\t\ttry {\n\t\t\t\tfs.rmSync(this.snapshotPath, { force: true });\n\t\t\t} catch {\n\t\t\t\t// The unsafe snapshot remains unreadable to this provider.\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\tconst representations = Array.isArray(parsed.representations) ? parsed.representations : [];\n\t\tfor (const pair of representations) {\n\t\t\tif (!Array.isArray(pair) || pair.length !== 2) continue;\n\t\t\tconst [key, entry] = pair as [unknown, unknown];\n\t\t\tif (typeof key !== \"string\" || key.length === 0) continue;\n\t\t\tif (!isPersistableRepresentation(entry, this.maxEntryTextLength)) continue;\n\t\t\twriteLru(this.representations, key, entry, this.maxEntries);\n\t\t}\n\n\t\tconst negatives = Array.isArray(parsed.negatives) ? parsed.negatives : [];\n\t\tfor (const pair of negatives) {\n\t\t\tif (!Array.isArray(pair) || pair.length !== 2) continue;\n\t\t\tconst [key, entry] = pair as [unknown, unknown];\n\t\t\tif (typeof key !== \"string\" || key.length === 0) continue;\n\t\t\tif (!isPersistableNegative(entry)) continue;\n\t\t\twriteLru(this.negatives, key, entry, this.maxEntries);\n\t\t}\n\t}\n\n\tprivate markDirty(): void {\n\t\tthis.dirty = true;\n\t\tif (this.flushDebounceMs === 0) {\n\t\t\tthis.flush();\n\t\t\treturn;\n\t\t}\n\t\tif (this.flushTimer !== undefined) return;\n\t\tthis.flushTimer = setTimeout(() => {\n\t\t\tthis.flushTimer = undefined;\n\t\t\tthis.flush();\n\t\t}, this.flushDebounceMs);\n\t\tthis.flushTimer.unref?.();\n\t}\n\n\t/**\n\t * Write the snapshot to disk atomically (temp file + rename). Best-effort:\n\t * a failed flush leaves the previous snapshot intact and keeps the entries\n\t * in memory. Returns `true` when a snapshot was written.\n\t */\n\tflush(): boolean {\n\t\tif (this.flushTimer !== undefined) {\n\t\t\tclearTimeout(this.flushTimer);\n\t\t\tthis.flushTimer = undefined;\n\t\t}\n\t\tif (!this.dirty) return false;\n\t\tconst snapshot: DiskSnapshotFileV2 = {\n\t\t\tschemaVersion: CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION,\n\t\t\trepresentations: [...this.representations.entries()]\n\t\t\t\t.filter(\n\t\t\t\t\t([key, entry]) =>\n\t\t\t\t\t\t!containsCredentialShape(key) && isPersistableRepresentation(entry, this.maxEntryTextLength),\n\t\t\t\t)\n\t\t\t\t.map(([key, entry]) => [key, entry] as const),\n\t\t\tnegatives: [...this.negatives.entries()]\n\t\t\t\t.filter(([key, entry]) => !containsCredentialShape(key) && isPersistableNegative(entry))\n\t\t\t\t.map(([key, entry]) => [key, entry] as const),\n\t\t};\n\t\tlet serialized: string;\n\t\ttry {\n\t\t\tserialized = JSON.stringify(snapshot);\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t\tif (Buffer.byteLength(serialized, \"utf8\") > this.maxBytes) {\n\t\t\t// Drop the oldest half and retry once rather than growing forever.\n\t\t\tconst keys = [...this.representations.keys()];\n\t\t\tif (keys.length === 0) return false;\n\t\t\tconst dropCount = Math.max(1, Math.ceil(keys.length / 2));\n\t\t\tfor (const key of keys.slice(0, dropCount)) this.representations.delete(key);\n\t\t\treturn this.flush();\n\t\t}\n\t\tconst tempPath = `${this.snapshotPath}.${process.pid}.tmp`;\n\t\ttry {\n\t\t\tfs.mkdirSync(path.dirname(this.snapshotPath), { recursive: true });\n\t\t\tfs.writeFileSync(tempPath, serialized, { encoding: \"utf8\", mode: 0o600 });\n\t\t\tfs.renameSync(tempPath, this.snapshotPath);\n\t\t\tthis.dirty = false;\n\t\t\treturn true;\n\t\t} catch {\n\t\t\ttry {\n\t\t\t\tfs.rmSync(tempPath, { force: true });\n\t\t\t} catch {\n\t\t\t\t// The temp file is unlinkable; nothing further to do.\n\t\t\t}\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Cancel any pending flush and persist immediately. Safe to call more than once. */\n\tclose(): void {\n\t\tthis.flush();\n\t}\n\n\tgetInvalidationSnapshot(): ContextCacheInvalidationSnapshot | undefined {\n\t\treturn this.invalidationSnapshot;\n\t}\n\n\tsetInvalidationSnapshot(snapshot: ContextCacheInvalidationSnapshot): void {\n\t\tthis.invalidationSnapshot = createContextCacheInvalidationSnapshot({\n\t\t\tforkId: snapshot.forkId,\n\t\t\tworktreeFingerprint: snapshot.worktreeFingerprint,\n\t\t\tactiveModelId: snapshot.activeModelId,\n\t\t\tcompactionModelId: snapshot.compactionModelId,\n\t\t\tglobalEpoch: snapshot.globalEpoch,\n\t\t\ttranscriptRepair: snapshot.counters.transcriptRepair,\n\t\t\ttoolResultDisposition: snapshot.counters.toolResultDisposition,\n\t\t\tevidenceReceipt: snapshot.counters.evidenceReceipt,\n\t\t\tuserSteering: snapshot.counters.userSteering,\n\t\t\tsettings: snapshot.counters.settings,\n\t\t});\n\t}\n\n\treadRepresentation(key: string): ContextBudgetRepresentationCacheReadV2 | undefined {\n\t\tconst entry = readLru(this.representations, key);\n\t\treturn entry ? { entry, layer: this.layer } : undefined;\n\t}\n\n\twriteRepresentation(input: { readonly key: string; readonly entry: ContextBudgetRepresentationCacheEntryV2 }): void {\n\t\twriteLru(this.representations, input.key, input.entry, this.maxEntries);\n\t\tif (\n\t\t\t(!containsCredentialShape(input.key) && isPersistableRepresentation(input.entry, this.maxEntryTextLength)) ||\n\t\t\tfs.existsSync(this.snapshotPath)\n\t\t) {\n\t\t\tthis.markDirty();\n\t\t}\n\t}\n\n\tdeleteRepresentation(key: string): void {\n\t\tif (this.representations.delete(key)) this.markDirty();\n\t}\n\n\treadNegativeRepresentation(key: string): ContextBudgetNegativeCacheEntryV2 | undefined {\n\t\treturn readLru(this.negatives, key);\n\t}\n\n\twriteNegativeRepresentation(input: { readonly key: string; readonly reason: string }): void {\n\t\twriteLru(\n\t\t\tthis.negatives,\n\t\t\tinput.key,\n\t\t\t{ reason: input.reason, createdAtEpochMs: this.now(), layer: this.layer },\n\t\t\tthis.maxEntries,\n\t\t);\n\t\tthis.markDirty();\n\t}\n\n\tdeleteNegativeRepresentation(key: string): void {\n\t\tif (this.negatives.delete(key)) this.markDirty();\n\t}\n\n\treadPlan(key: string): ContextBudgetPlanCacheReadV2 | undefined {\n\t\tconst entry = readLru(this.plans, key);\n\t\treturn entry ? { entry, layer: \"session\" } : undefined;\n\t}\n\n\twritePlan(input: { readonly key: string; readonly entry: ContextBudgetPlanCacheEntryV2 }): void {\n\t\twriteLru(this.plans, input.key, input.entry, this.maxEntries);\n\t}\n\n\tdeletePlan(key: string): void {\n\t\tthis.plans.delete(key);\n\t}\n}\n"]}

package/dist/core/context-budget-v2-cache-disk.js

@@ -0,0 +1,343 @@
+/**
+ * Workspace-layer disk persistence for the context-budget-v2 representation
+ * cache.
+ *
+ * The in-memory provider (`context-budget-v2-cache-provider.ts`) dies with the
+ * process, so every new session re-renders and re-compresses context it already
+ * paid for. This provider keeps the same synchronous
+ * `ContextBudgetCacheProviderV2` contract and adds a bounded, atomically
+ * written JSON snapshot on disk.
+ *
+ * Scope: representation entries and negative entries only. Plan entries stay in
+ * memory on purpose — a plan is session-scoped (its key folds in the
+ * invalidation snapshot), so persisting it would only ever store misses.
+ *
+ * Safety: reads go through the same validator as the memory provider
+ * (`validateContextBudgetRepresentationCacheEntryV2`), which re-checks source
+ * hash, representation fingerprint, model, tokenizer, policy version and TTL.
+ * A corrupt, truncated, oversized, or schema-mismatched snapshot is discarded
+ * and the cache simply starts empty; a cache is never load-bearing for
+ * correctness.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { containsCredentialShape } from "./compaction/transaction.js";
+import { createContextCacheInvalidationSnapshot, } from "./context-budget-v2-cache-invalidation.js";
+export const CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION = "context-budget-v2-diskcache-1";
+/** Default cap on persisted representation entries. */
+export const DEFAULT_DISK_CACHE_MAX_ENTRIES = 2048;
+/** Default cap on the persisted snapshot size. Oversized snapshots are dropped on load. */
+export const DEFAULT_DISK_CACHE_MAX_BYTES = 32 * 1024 * 1024;
+/** Default write-behind debounce. Collapses a burst of writes into a single flush. */
+export const DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS = 750;
+/** Default cap on a single persisted representation's text length. */
+export const DEFAULT_DISK_CACHE_MAX_ENTRY_TEXT_LENGTH = 512 * 1024;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function containsCredentialShapeInValue(value) {
+    const pending = [value];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (typeof current === "string") {
+            if (containsCredentialShape(current))
+                return true;
+            continue;
+        }
+        if (typeof current !== "object" || current === null || seen.has(current))
+            continue;
+        seen.add(current);
+        if (Array.isArray(current)) {
+            pending.push(...current);
+            continue;
+        }
+        for (const [key, nested] of Object.entries(current)) {
+            if (containsCredentialShape(key))
+                return true;
+            pending.push(nested);
+        }
+    }
+    return false;
+}
+function isPersistableRepresentation(value, maxEntryTextLength) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.kind !== "string")
+        return false;
+    if (typeof value.text !== "string" || value.text.length > maxEntryTextLength)
+        return false;
+    if (containsCredentialShapeInValue(value))
+        return false;
+    const estimated = value.estimatedTokens;
+    if (typeof estimated !== "number" || !Number.isFinite(estimated) || estimated < 0)
+        return false;
+    if (typeof value.fidelity !== "string")
+        return false;
+    if (typeof value.sourceHash !== "string" || value.sourceHash.length === 0)
+        return false;
+    if (typeof value.representationFingerprint !== "string")
+        return false;
+    if (typeof value.modelId !== "string")
+        return false;
+    if (typeof value.tokenizerId !== "string")
+        return false;
+    if (typeof value.policyVersion !== "string")
+        return false;
+    return true;
+}
+function isPersistableNegative(value) {
+    return isRecord(value) && typeof value.reason === "string" && !containsCredentialShapeInValue(value);
+}
+function readLru(store, key) {
+    const entry = store.get(key);
+    if (entry === undefined)
+        return undefined;
+    store.delete(key);
+    store.set(key, entry);
+    return entry;
+}
+function writeLru(store, key, entry, maxEntries) {
+    store.delete(key);
+    store.set(key, entry);
+    while (store.size > maxEntries) {
+        const oldestKey = store.keys().next().value;
+        if (oldestKey === undefined)
+            return;
+        store.delete(oldestKey);
+    }
+}
+/**
+ * Create a disk backed workspace cache provider. Loading is synchronous and
+ * best-effort: any failure yields an empty in-memory cache rather than throwing,
+ * because a cache miss is always a legal outcome.
+ */
+export function createDiskContextBudgetCacheProviderV2(options) {
+    return new DiskContextBudgetCacheProviderV2(options);
+}
+export class DiskContextBudgetCacheProviderV2 {
+    representations = new Map();
+    negatives = new Map();
+    /** Plans stay in memory: their keys are session-scoped, so persisting them stores only misses. */
+    plans = new Map();
+    layer;
+    maxEntries;
+    maxBytes;
+    maxEntryTextLength;
+    flushDebounceMs;
+    now;
+    snapshotPath;
+    invalidationSnapshot;
+    dirty = false;
+    flushTimer;
+    loadError;
+    constructor(options) {
+        this.layer = options.layer ?? "workspace";
+        this.maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_DISK_CACHE_MAX_ENTRIES);
+        this.maxBytes = Math.max(1024, options.maxBytes ?? DEFAULT_DISK_CACHE_MAX_BYTES);
+        this.maxEntryTextLength = Math.max(1, options.maxEntryTextLength ?? DEFAULT_DISK_CACHE_MAX_ENTRY_TEXT_LENGTH);
+        this.flushDebounceMs = Math.max(0, options.flushDebounceMs ?? DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS);
+        this.now = options.now ?? Date.now;
+        this.snapshotPath = path.join(options.dir, "representations.json");
+        this.load();
+    }
+    /** Absolute path of the persisted snapshot. */
+    get snapshotFilePath() {
+        return this.snapshotPath;
+    }
+    /** Reason the on-disk snapshot was rejected, if it was. `undefined` on a clean load or a cold start. */
+    get lastLoadError() {
+        return this.loadError;
+    }
+    /** Number of representation entries currently held. */
+    get size() {
+        return this.representations.size;
+    }
+    load() {
+        let raw;
+        try {
+            const stat = fs.statSync(this.snapshotPath);
+            if (stat.size > this.maxBytes) {
+                this.loadError = `snapshot exceeds maxBytes (${stat.size} > ${this.maxBytes})`;
+                return;
+            }
+            raw = fs.readFileSync(this.snapshotPath, "utf8");
+        }
+        catch {
+            // Cold start: no snapshot yet, or it is unreadable. Both are normal.
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.loadError = "snapshot is not valid JSON";
+            return;
+        }
+        if (!isRecord(parsed) || parsed.schemaVersion !== CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION) {
+            this.loadError = "snapshot schema mismatch";
+            return;
+        }
+        if (containsCredentialShapeInValue(parsed)) {
+            this.loadError = "snapshot contains credential-shaped text";
+            try {
+                fs.rmSync(this.snapshotPath, { force: true });
+            }
+            catch {
+                // The unsafe snapshot remains unreadable to this provider.
+            }
+            return;
+        }
+        const representations = Array.isArray(parsed.representations) ? parsed.representations : [];
+        for (const pair of representations) {
+            if (!Array.isArray(pair) || pair.length !== 2)
+                continue;
+            const [key, entry] = pair;
+            if (typeof key !== "string" || key.length === 0)
+                continue;
+            if (!isPersistableRepresentation(entry, this.maxEntryTextLength))
+                continue;
+            writeLru(this.representations, key, entry, this.maxEntries);
+        }
+        const negatives = Array.isArray(parsed.negatives) ? parsed.negatives : [];
+        for (const pair of negatives) {
+            if (!Array.isArray(pair) || pair.length !== 2)
+                continue;
+            const [key, entry] = pair;
+            if (typeof key !== "string" || key.length === 0)
+                continue;
+            if (!isPersistableNegative(entry))
+                continue;
+            writeLru(this.negatives, key, entry, this.maxEntries);
+        }
+    }
+    markDirty() {
+        this.dirty = true;
+        if (this.flushDebounceMs === 0) {
+            this.flush();
+            return;
+        }
+        if (this.flushTimer !== undefined)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = undefined;
+            this.flush();
+        }, this.flushDebounceMs);
+        this.flushTimer.unref?.();
+    }
+    /**
+     * Write the snapshot to disk atomically (temp file + rename). Best-effort:
+     * a failed flush leaves the previous snapshot intact and keeps the entries
+     * in memory. Returns `true` when a snapshot was written.
+     */
+    flush() {
+        if (this.flushTimer !== undefined) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        if (!this.dirty)
+            return false;
+        const snapshot = {
+            schemaVersion: CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION,
+            representations: [...this.representations.entries()]
+                .filter(([key, entry]) => !containsCredentialShape(key) && isPersistableRepresentation(entry, this.maxEntryTextLength))
+                .map(([key, entry]) => [key, entry]),
+            negatives: [...this.negatives.entries()]
+                .filter(([key, entry]) => !containsCredentialShape(key) && isPersistableNegative(entry))
+                .map(([key, entry]) => [key, entry]),
+        };
+        let serialized;
+        try {
+            serialized = JSON.stringify(snapshot);
+        }
+        catch {
+            return false;
+        }
+        if (Buffer.byteLength(serialized, "utf8") > this.maxBytes) {
+            // Drop the oldest half and retry once rather than growing forever.
+            const keys = [...this.representations.keys()];
+            if (keys.length === 0)
+                return false;
+            const dropCount = Math.max(1, Math.ceil(keys.length / 2));
+            for (const key of keys.slice(0, dropCount))
+                this.representations.delete(key);
+            return this.flush();
+        }
+        const tempPath = `${this.snapshotPath}.${process.pid}.tmp`;
+        try {
+            fs.mkdirSync(path.dirname(this.snapshotPath), { recursive: true });
+            fs.writeFileSync(tempPath, serialized, { encoding: "utf8", mode: 0o600 });
+            fs.renameSync(tempPath, this.snapshotPath);
+            this.dirty = false;
+            return true;
+        }
+        catch {
+            try {
+                fs.rmSync(tempPath, { force: true });
+            }
+            catch {
+                // The temp file is unlinkable; nothing further to do.
+            }
+            return false;
+        }
+    }
+    /** Cancel any pending flush and persist immediately. Safe to call more than once. */
+    close() {
+        this.flush();
+    }
+    getInvalidationSnapshot() {
+        return this.invalidationSnapshot;
+    }
+    setInvalidationSnapshot(snapshot) {
+        this.invalidationSnapshot = createContextCacheInvalidationSnapshot({
+            forkId: snapshot.forkId,
+            worktreeFingerprint: snapshot.worktreeFingerprint,
+            activeModelId: snapshot.activeModelId,
+            compactionModelId: snapshot.compactionModelId,
+            globalEpoch: snapshot.globalEpoch,
+            transcriptRepair: snapshot.counters.transcriptRepair,
+            toolResultDisposition: snapshot.counters.toolResultDisposition,
+            evidenceReceipt: snapshot.counters.evidenceReceipt,
+            userSteering: snapshot.counters.userSteering,
+            settings: snapshot.counters.settings,
+        });
+    }
+    readRepresentation(key) {
+        const entry = readLru(this.representations, key);
+        return entry ? { entry, layer: this.layer } : undefined;
+    }
+    writeRepresentation(input) {
+        writeLru(this.representations, input.key, input.entry, this.maxEntries);
+        if ((!containsCredentialShape(input.key) && isPersistableRepresentation(input.entry, this.maxEntryTextLength)) ||
+            fs.existsSync(this.snapshotPath)) {
+            this.markDirty();
+        }
+    }
+    deleteRepresentation(key) {
+        if (this.representations.delete(key))
+            this.markDirty();
+    }
+    readNegativeRepresentation(key) {
+        return readLru(this.negatives, key);
+    }
+    writeNegativeRepresentation(input) {
+        writeLru(this.negatives, input.key, { reason: input.reason, createdAtEpochMs: this.now(), layer: this.layer }, this.maxEntries);
+        this.markDirty();
+    }
+    deleteNegativeRepresentation(key) {
+        if (this.negatives.delete(key))
+            this.markDirty();
+    }
+    readPlan(key) {
+        const entry = readLru(this.plans, key);
+        return entry ? { entry, layer: "session" } : undefined;
+    }
+    writePlan(input) {
+        writeLru(this.plans, input.key, input.entry, this.maxEntries);
+    }
+    deletePlan(key) {
+        this.plans.delete(key);
+    }
+}
+//# sourceMappingURL=context-budget-v2-cache-disk.js.map

package/dist/core/context-budget-v2-cache-disk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-v2-cache-disk.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-cache-disk.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Workspace-layer disk persistence for the context-budget-v2 representation\n * cache.\n *\n * The in-memory provider (`context-budget-v2-cache-provider.ts`) dies with the\n * process, so every new session re-renders and re-compresses context it already\n * paid for. This provider keeps the same synchronous\n * `ContextBudgetCacheProviderV2` contract and adds a bounded, atomically\n * written JSON snapshot on disk.\n *\n * Scope: representation entries and negative entries only. Plan entries stay in\n * memory on purpose — a plan is session-scoped (its key folds in the\n * invalidation snapshot), so persisting it would only ever store misses.\n *\n * Safety: reads go through the same validator as the memory provider\n * (`validateContextBudgetRepresentationCacheEntryV2`), which re-checks source\n * hash, representation fingerprint, model, tokenizer, policy version and TTL.\n * A corrupt, truncated, oversized, or schema-mismatched snapshot is discarded\n * and the cache simply starts empty; a cache is never load-bearing for\n * correctness.\n */\n\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { containsCredentialShape } from \"./compaction/transaction.ts\";\nimport {\n\ttype ContextCacheInvalidationSnapshot,\n\tcreateContextCacheInvalidationSnapshot,\n} from \"./context-budget-v2-cache-invalidation.ts\";\nimport type {\n\tContextBudgetCacheLayerV2,\n\tContextBudgetCacheProviderV2,\n\tContextBudgetNegativeCacheEntryV2,\n\tContextBudgetPlanCacheEntryV2,\n\tContextBudgetPlanCacheReadV2,\n\tContextBudgetRepresentationCacheEntryV2,\n\tContextBudgetRepresentationCacheReadV2,\n} from \"./context-budget-v2-types.ts\";\n\nexport const CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION = \"context-budget-v2-diskcache-1\" as const;\n\n/** Default cap on persisted representation entries. */\nexport const DEFAULT_DISK_CACHE_MAX_ENTRIES = 2048;\n/** Default cap on the persisted snapshot size. Oversized snapshots are dropped on load. */\nexport const DEFAULT_DISK_CACHE_MAX_BYTES = 32 * 1024 * 1024;\n/** Default write-behind debounce. Collapses a burst of writes into a single flush. */\nexport const DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS = 750;\n/** Default cap on a single persisted representation's text length. */\nexport const DEFAULT_DISK_CACHE_MAX_ENTRY_TEXT_LENGTH = 512 * 1024;\n\nexport interface DiskContextBudgetCacheOptionsV2 {\n\t/** Directory holding the snapshot file. Created on first flush. */\n\treadonly dir: string;\n\t/** Cache layer reported on reads. Defaults to `workspace`. */\n\treadonly layer?: ContextBudgetCacheLayerV2;\n\t/** Max persisted representation entries (LRU). */\n\treadonly maxEntries?: number;\n\t/** Max accepted snapshot size in bytes. */\n\treadonly maxBytes?: number;\n\t/** Max persisted text length for a single entry. */\n\treadonly maxEntryTextLength?: number;\n\t/** Write-behind debounce in ms. `0` flushes synchronously on every write. */\n\treadonly flushDebounceMs?: number;\n\t/** Injectable clock, for tests. */\n\treadonly now?: () => number;\n}\n\ninterface DiskSnapshotFileV2 {\n\treadonly schemaVersion: typeof CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION;\n\treadonly representations: readonly (readonly [string, ContextBudgetRepresentationCacheEntryV2])[];\n\treadonly negatives: readonly (readonly [string, ContextBudgetNegativeCacheEntryV2])[];\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction containsCredentialShapeInValue(value: unknown): boolean {\n\tconst pending: unknown[] = [value];\n\tconst seen = new Set<object>();\n\twhile (pending.length > 0) {\n\t\tconst current = pending.pop();\n\t\tif (typeof current === \"string\") {\n\t\t\tif (containsCredentialShape(current)) return true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (typeof current !== \"object\" || current === null || seen.has(current)) continue;\n\t\tseen.add(current);\n\t\tif (Array.isArray(current)) {\n\t\t\tpending.push(...current);\n\t\t\tcontinue;\n\t\t}\n\t\tfor (const [key, nested] of Object.entries(current)) {\n\t\t\tif (containsCredentialShape(key)) return true;\n\t\t\tpending.push(nested);\n\t\t}\n\t}\n\treturn false;\n}\n\nfunction isPersistableRepresentation(\n\tvalue: unknown,\n\tmaxEntryTextLength: number,\n): value is ContextBudgetRepresentationCacheEntryV2 {\n\tif (!isRecord(value)) return false;\n\tif (typeof value.kind !== \"string\") return false;\n\tif (typeof value.text !== \"string\" || value.text.length > maxEntryTextLength) return false;\n\tif (containsCredentialShapeInValue(value)) return false;\n\tconst estimated = value.estimatedTokens;\n\tif (typeof estimated !== \"number\" || !Number.isFinite(estimated) || estimated < 0) return false;\n\tif (typeof value.fidelity !== \"string\") return false;\n\tif (typeof value.sourceHash !== \"string\" || value.sourceHash.length === 0) return false;\n\tif (typeof value.representationFingerprint !== \"string\") return false;\n\tif (typeof value.modelId !== \"string\") return false;\n\tif (typeof value.tokenizerId !== \"string\") return false;\n\tif (typeof value.policyVersion !== \"string\") return false;\n\treturn true;\n}\n\nfunction isPersistableNegative(value: unknown): value is ContextBudgetNegativeCacheEntryV2 {\n\treturn isRecord(value) && typeof value.reason === \"string\" && !containsCredentialShapeInValue(value);\n}\n\nfunction readLru<T>(store: Map<string, T>, key: string): T | undefined {\n\tconst entry = store.get(key);\n\tif (entry === undefined) return undefined;\n\tstore.delete(key);\n\tstore.set(key, entry);\n\treturn entry;\n}\n\nfunction writeLru<T>(store: Map<string, T>, key: string, entry: T, maxEntries: number): void {\n\tstore.delete(key);\n\tstore.set(key, entry);\n\twhile (store.size > maxEntries) {\n\t\tconst oldestKey = store.keys().next().value;\n\t\tif (oldestKey === undefined) return;\n\t\tstore.delete(oldestKey);\n\t}\n}\n\n/**\n * Create a disk backed workspace cache provider. Loading is synchronous and\n * best-effort: any failure yields an empty in-memory cache rather than throwing,\n * because a cache miss is always a legal outcome.\n */\nexport function createDiskContextBudgetCacheProviderV2(\n\toptions: DiskContextBudgetCacheOptionsV2,\n): DiskContextBudgetCacheProviderV2 {\n\treturn new DiskContextBudgetCacheProviderV2(options);\n}\n\nexport class DiskContextBudgetCacheProviderV2 implements ContextBudgetCacheProviderV2 {\n\tprivate readonly representations = new Map<string, ContextBudgetRepresentationCacheEntryV2>();\n\tprivate readonly negatives = new Map<string, ContextBudgetNegativeCacheEntryV2>();\n\t/** Plans stay in memory: their keys are session-scoped, so persisting them stores only misses. */\n\tprivate readonly plans = new Map<string, ContextBudgetPlanCacheEntryV2>();\n\tprivate readonly layer: ContextBudgetCacheLayerV2;\n\tprivate readonly maxEntries: number;\n\tprivate readonly maxBytes: number;\n\tprivate readonly maxEntryTextLength: number;\n\tprivate readonly flushDebounceMs: number;\n\tprivate readonly now: () => number;\n\tprivate readonly snapshotPath: string;\n\tprivate invalidationSnapshot: ContextCacheInvalidationSnapshot | undefined;\n\tprivate dirty = false;\n\tprivate flushTimer: ReturnType<typeof setTimeout> | undefined;\n\tprivate loadError: string | undefined;\n\n\tconstructor(options: DiskContextBudgetCacheOptionsV2) {\n\t\tthis.layer = options.layer ?? \"workspace\";\n\t\tthis.maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_DISK_CACHE_MAX_ENTRIES);\n\t\tthis.maxBytes = Math.max(1024, options.maxBytes ?? DEFAULT_DISK_CACHE_MAX_BYTES);\n\t\tthis.maxEntryTextLength = Math.max(1, options.maxEntryTextLength ?? DEFAULT_DISK_CACHE_MAX_ENTRY_TEXT_LENGTH);\n\t\tthis.flushDebounceMs = Math.max(0, options.flushDebounceMs ?? DEFAULT_DISK_CACHE_FLUSH_DEBOUNCE_MS);\n\t\tthis.now = options.now ?? Date.now;\n\t\tthis.snapshotPath = path.join(options.dir, \"representations.json\");\n\t\tthis.load();\n\t}\n\n\t/** Absolute path of the persisted snapshot. */\n\tget snapshotFilePath(): string {\n\t\treturn this.snapshotPath;\n\t}\n\n\t/** Reason the on-disk snapshot was rejected, if it was. `undefined` on a clean load or a cold start. */\n\tget lastLoadError(): string | undefined {\n\t\treturn this.loadError;\n\t}\n\n\t/** Number of representation entries currently held. */\n\tget size(): number {\n\t\treturn this.representations.size;\n\t}\n\n\tprivate load(): void {\n\t\tlet raw: string;\n\t\ttry {\n\t\t\tconst stat = fs.statSync(this.snapshotPath);\n\t\t\tif (stat.size > this.maxBytes) {\n\t\t\t\tthis.loadError = `snapshot exceeds maxBytes (${stat.size} > ${this.maxBytes})`;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\traw = fs.readFileSync(this.snapshotPath, \"utf8\");\n\t\t} catch {\n\t\t\t// Cold start: no snapshot yet, or it is unreadable. Both are normal.\n\t\t\treturn;\n\t\t}\n\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(raw);\n\t\t} catch {\n\t\t\tthis.loadError = \"snapshot is not valid JSON\";\n\t\t\treturn;\n\t\t}\n\t\tif (!isRecord(parsed) || parsed.schemaVersion !== CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION) {\n\t\t\tthis.loadError = \"snapshot schema mismatch\";\n\t\t\treturn;\n\t\t}\n\n\t\tif (containsCredentialShapeInValue(parsed)) {\n\t\t\tthis.loadError = \"snapshot contains credential-shaped text\";\n\t\t\ttry {\n\t\t\t\tfs.rmSync(this.snapshotPath, { force: true });\n\t\t\t} catch {\n\t\t\t\t// The unsafe snapshot remains unreadable to this provider.\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\n\t\tconst representations = Array.isArray(parsed.representations) ? parsed.representations : [];\n\t\tfor (const pair of representations) {\n\t\t\tif (!Array.isArray(pair) || pair.length !== 2) continue;\n\t\t\tconst [key, entry] = pair as [unknown, unknown];\n\t\t\tif (typeof key !== \"string\" || key.length === 0) continue;\n\t\t\tif (!isPersistableRepresentation(entry, this.maxEntryTextLength)) continue;\n\t\t\twriteLru(this.representations, key, entry, this.maxEntries);\n\t\t}\n\n\t\tconst negatives = Array.isArray(parsed.negatives) ? parsed.negatives : [];\n\t\tfor (const pair of negatives) {\n\t\t\tif (!Array.isArray(pair) || pair.length !== 2) continue;\n\t\t\tconst [key, entry] = pair as [unknown, unknown];\n\t\t\tif (typeof key !== \"string\" || key.length === 0) continue;\n\t\t\tif (!isPersistableNegative(entry)) continue;\n\t\t\twriteLru(this.negatives, key, entry, this.maxEntries);\n\t\t}\n\t}\n\n\tprivate markDirty(): void {\n\t\tthis.dirty = true;\n\t\tif (this.flushDebounceMs === 0) {\n\t\t\tthis.flush();\n\t\t\treturn;\n\t\t}\n\t\tif (this.flushTimer !== undefined) return;\n\t\tthis.flushTimer = setTimeout(() => {\n\t\t\tthis.flushTimer = undefined;\n\t\t\tthis.flush();\n\t\t}, this.flushDebounceMs);\n\t\tthis.flushTimer.unref?.();\n\t}\n\n\t/**\n\t * Write the snapshot to disk atomically (temp file + rename). Best-effort:\n\t * a failed flush leaves the previous snapshot intact and keeps the entries\n\t * in memory. Returns `true` when a snapshot was written.\n\t */\n\tflush(): boolean {\n\t\tif (this.flushTimer !== undefined) {\n\t\t\tclearTimeout(this.flushTimer);\n\t\t\tthis.flushTimer = undefined;\n\t\t}\n\t\tif (!this.dirty) return false;\n\t\tconst snapshot: DiskSnapshotFileV2 = {\n\t\t\tschemaVersion: CONTEXT_BUDGET_DISK_CACHE_SCHEMA_VERSION,\n\t\t\trepresentations: [...this.representations.entries()]\n\t\t\t\t.filter(\n\t\t\t\t\t([key, entry]) =>\n\t\t\t\t\t\t!containsCredentialShape(key) && isPersistableRepresentation(entry, this.maxEntryTextLength),\n\t\t\t\t)\n\t\t\t\t.map(([key, entry]) => [key, entry] as const),\n\t\t\tnegatives: [...this.negatives.entries()]\n\t\t\t\t.filter(([key, entry]) => !containsCredentialShape(key) && isPersistableNegative(entry))\n\t\t\t\t.map(([key, entry]) => [key, entry] as const),\n\t\t};\n\t\tlet serialized: string;\n\t\ttry {\n\t\t\tserialized = JSON.stringify(snapshot);\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t\tif (Buffer.byteLength(serialized, \"utf8\") > this.maxBytes) {\n\t\t\t// Drop the oldest half and retry once rather than growing forever.\n\t\t\tconst keys = [...this.representations.keys()];\n\t\t\tif (keys.length === 0) return false;\n\t\t\tconst dropCount = Math.max(1, Math.ceil(keys.length / 2));\n\t\t\tfor (const key of keys.slice(0, dropCount)) this.representations.delete(key);\n\t\t\treturn this.flush();\n\t\t}\n\t\tconst tempPath = `${this.snapshotPath}.${process.pid}.tmp`;\n\t\ttry {\n\t\t\tfs.mkdirSync(path.dirname(this.snapshotPath), { recursive: true });\n\t\t\tfs.writeFileSync(tempPath, serialized, { encoding: \"utf8\", mode: 0o600 });\n\t\t\tfs.renameSync(tempPath, this.snapshotPath);\n\t\t\tthis.dirty = false;\n\t\t\treturn true;\n\t\t} catch {\n\t\t\ttry {\n\t\t\t\tfs.rmSync(tempPath, { force: true });\n\t\t\t} catch {\n\t\t\t\t// The temp file is unlinkable; nothing further to do.\n\t\t\t}\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Cancel any pending flush and persist immediately. Safe to call more than once. */\n\tclose(): void {\n\t\tthis.flush();\n\t}\n\n\tgetInvalidationSnapshot(): ContextCacheInvalidationSnapshot | undefined {\n\t\treturn this.invalidationSnapshot;\n\t}\n\n\tsetInvalidationSnapshot(snapshot: ContextCacheInvalidationSnapshot): void {\n\t\tthis.invalidationSnapshot = createContextCacheInvalidationSnapshot({\n\t\t\tforkId: snapshot.forkId,\n\t\t\tworktreeFingerprint: snapshot.worktreeFingerprint,\n\t\t\tactiveModelId: snapshot.activeModelId,\n\t\t\tcompactionModelId: snapshot.compactionModelId,\n\t\t\tglobalEpoch: snapshot.globalEpoch,\n\t\t\ttranscriptRepair: snapshot.counters.transcriptRepair,\n\t\t\ttoolResultDisposition: snapshot.counters.toolResultDisposition,\n\t\t\tevidenceReceipt: snapshot.counters.evidenceReceipt,\n\t\t\tuserSteering: snapshot.counters.userSteering,\n\t\t\tsettings: snapshot.counters.settings,\n\t\t});\n\t}\n\n\treadRepresentation(key: string): ContextBudgetRepresentationCacheReadV2 | undefined {\n\t\tconst entry = readLru(this.representations, key);\n\t\treturn entry ? { entry, layer: this.layer } : undefined;\n\t}\n\n\twriteRepresentation(input: { readonly key: string; readonly entry: ContextBudgetRepresentationCacheEntryV2 }): void {\n\t\twriteLru(this.representations, input.key, input.entry, this.maxEntries);\n\t\tif (\n\t\t\t(!containsCredentialShape(input.key) && isPersistableRepresentation(input.entry, this.maxEntryTextLength)) ||\n\t\t\tfs.existsSync(this.snapshotPath)\n\t\t) {\n\t\t\tthis.markDirty();\n\t\t}\n\t}\n\n\tdeleteRepresentation(key: string): void {\n\t\tif (this.representations.delete(key)) this.markDirty();\n\t}\n\n\treadNegativeRepresentation(key: string): ContextBudgetNegativeCacheEntryV2 | undefined {\n\t\treturn readLru(this.negatives, key);\n\t}\n\n\twriteNegativeRepresentation(input: { readonly key: string; readonly reason: string }): void {\n\t\twriteLru(\n\t\t\tthis.negatives,\n\t\t\tinput.key,\n\t\t\t{ reason: input.reason, createdAtEpochMs: this.now(), layer: this.layer },\n\t\t\tthis.maxEntries,\n\t\t);\n\t\tthis.markDirty();\n\t}\n\n\tdeleteNegativeRepresentation(key: string): void {\n\t\tif (this.negatives.delete(key)) this.markDirty();\n\t}\n\n\treadPlan(key: string): ContextBudgetPlanCacheReadV2 | undefined {\n\t\tconst entry = readLru(this.plans, key);\n\t\treturn entry ? { entry, layer: \"session\" } : undefined;\n\t}\n\n\twritePlan(input: { readonly key: string; readonly entry: ContextBudgetPlanCacheEntryV2 }): void {\n\t\twriteLru(this.plans, input.key, input.entry, this.maxEntries);\n\t}\n\n\tdeletePlan(key: string): void {\n\t\tthis.plans.delete(key);\n\t}\n}\n"]}