@caupulican/pi-adaptative 0.81.42 → 0.81.43

package/dist/core/learning/reflection-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"reflection-engine.js","sourceRoot":"","sources":["../../../src/core/learning/reflection-engine.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Usage } from \"@caupulican/pi-ai\";\n\nexport type StopReason = \"stop\" | \"toolUse\" | \"aborted\" | \"error\" | string;\n\nexport interface IsolatedCompletionResult {\n\ttext: string;\n\tusage: Usage;\n\tstopReason: StopReason;\n}\n\nexport type ReflectionTrigger = \"complex\" | \"corrective\" | \"session-end\" | \"none\";\n\nexport interface DemandSignals {\n\ttrigger: ReflectionTrigger;\n\ttoolCallCount: number;\n\thadCorrection: boolean;\n\tcontextHeadroomPct: number; // 0..100\n\tusefulLately: number; // 0..1 rolling score\n}\n\nexport interface DemandPlan {\n\tact: \"skip\" | \"reflect\";\n\treason: string;\n\ttokenBudget: number;\n}\n\n/**\n * Pure zero-I/O heuristic to decide whether the current turn justifies a reflection run\n * and determine the token budget under the cheap-tool net-negative doctrine.\n */\nexport function decideDemand(signals: DemandSignals): DemandPlan {\n\tif (signals.trigger === \"none\") {\n\t\treturn { act: \"skip\", reason: \"No trigger detected\", tokenBudget: 0 };\n\t}\n\tif (signals.contextHeadroomPct < 10) {\n\t\treturn { act: \"skip\", reason: \"Context headroom is critically low (< 10%)\", tokenBudget: 0 };\n\t}\n\n\t// Dynamic token budget based on headroom (keep reflection bounded between 500 and 1500 tokens)\n\tconst baseBudget = 1000;\n\tconst tokenBudget = Math.max(500, Math.min(1500, Math.round(baseBudget * (signals.contextHeadroomPct / 100))));\n\n\tif (signals.hadCorrection) {\n\t\treturn { act: \"reflect\", reason: \"Correction detected in the turn\", tokenBudget };\n\t}\n\tif (signals.trigger === \"session-end\") {\n\t\treturn { act: \"reflect\", reason: \"Session end reflection triggered\", tokenBudget };\n\t}\n\tif (signals.trigger === \"complex\") {\n\t\tif (signals.toolCallCount >= 3) {\n\t\t\treturn { act: \"reflect\", reason: `Complex turn with ${signals.toolCallCount} tool calls`, tokenBudget };\n\t\t}\n\t}\n\n\treturn { act: \"skip\", reason: \"Signals do not justify reflection overhead\", tokenBudget: 0 };\n}\n\nexport interface ReflectionInput {\n\trecentTurnText: string; // host serializes the just-finished turn\n\texistingMemory: string; // current MEMORY.md + USER.md snapshot\n\tplan: DemandPlan;\n\t// host-injected isolated completion function:\n\tcomplete: (systemPrompt: string, userPrompt: string) => Promise<IsolatedCompletionResult>;\n}\n\nexport type ReflectionWrite =\n\t| { kind: \"memory_add\"; section: \"MEMORY\" | \"USER\"; text: string }\n\t| { kind: \"memory_replace\"; target: string; text: string }\n\t| { kind: \"memory_remove\"; target: string }\n\t// R7 memory-to-behavior: promote a recurring procedural workflow into an executable skill.\n\t| { kind: \"promote_skill\"; name: string; description: string; body: string };\n\nexport interface ReflectionResult {\n\twrites: ReflectionWrite[];\n\tusage: Usage;\n\trationale: string;\n}\n\n/**\n * STATIC reflection system prompt (Hermes-parity #33). It is byte-identical across every reflection\n * pass — the variable parts (existing memory snapshot + the turn transcript) live in the USER prompt —\n * so the provider prompt-cache reuses this prefix instead of re-billing it each pass (cost guard).\n * Do NOT interpolate per-call data into this constant or caching breaks.\n */\nexport const REFLECTION_SYSTEM_PROMPT = `You are a reflection engine. Your job is to analyze the recent conversation turn, compare it against the agent's existing memory, and decide if any memory updates are needed.\n\nMemory guidelines:\n- \"MEMORY\" is for project facts, configuration, repeatable workflows, and coding findings.\n- \"USER\" is for user preferences, patterns, and style specifications.\n- Avoid duplicate facts. If the fact is already represented, do not add it.\n- CONFRONT existing memory: if the new turn contradicts or updates an existing fact, use \"memory_replace\" or \"memory_remove\" to supersede the old fact rather than blindly appending.\n- Keep memories short, factual, and direct. No fluff.\n- Do NOT capture transient/environment-specific noise: tool/network failures, one-off errors, or a single narrative event. Persist only durable facts and preferences.\n- PROMOTE to behavior: if the turn established a REPEATABLE, multi-step PROCEDURE/workflow (not a one-off fact) that should govern a future class of tasks, emit a \"promote_skill\" instead of (or in addition to) a memory fact. Only promote a genuinely reusable procedure — never a single fact, a one-off narrative, or environment-specific noise. Prefer a memory fact when unsure.\n\nYou must output your analysis and writes in the following JSON format inside a \\`\\`\\`json\\`\\`\\` code fence:\n{\n  \"rationale\": \"Explanation of your reasoning\",\n  \"writes\": [\n    { \"kind\": \"memory_add\", \"section\": \"MEMORY\" | \"USER\", \"text\": \"New direct fact to append\" },\n    { \"kind\": \"memory_replace\", \"target\": \"Exact text substring to replace\", \"text\": \"New replacement text\" },\n    { \"kind\": \"memory_remove\", \"target\": \"Exact text substring to remove\" },\n    { \"kind\": \"promote_skill\", \"name\": \"kebab-case-skill-name\", \"description\": \"one line of when to use it\", \"body\": \"Markdown: the step-by-step procedure\" }\n  ]\n}\n`;\n\nexport class ReflectionEngine {\n\t/**\n\t * Build the reflection prompt, call the injected isolated complete(),\n\t * parse the response, confront existing memory, and return memory writes.\n\t * Zero direct I/O.\n\t */\n\tasync reflect(input: ReflectionInput): Promise<ReflectionResult> {\n\t\tconst systemPrompt = REFLECTION_SYSTEM_PROMPT;\n\n\t\t// Variable inputs go in the USER prompt so the system prefix above stays cache-stable (#33).\n\t\tconst userPrompt = `Existing Memory snapshot:\n${input.existingMemory}\n\nRecent turn transcript:\n${input.recentTurnText}\n\nAnalyze this turn against the existing memory and output your memory updates.`;\n\n\t\tlet usage: Usage | undefined;\n\t\ttry {\n\t\t\tconst compResult = await input.complete(systemPrompt, userPrompt);\n\t\t\tusage = compResult.usage;\n\t\t\tconst text = compResult.text;\n\n\t\t\tconst jsonMatch = text.match(/```json\\s*([\\s\\S]*?)\\s*```/) || text.match(/{[\\s\\S]*}/);\n\t\t\tif (!jsonMatch) {\n\t\t\t\treturn {\n\t\t\t\t\twrites: [],\n\t\t\t\t\tusage: compResult.usage,\n\t\t\t\t\trationale: `Failed to locate JSON response. Raw text:\\n${text}`,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tconst parsed = JSON.parse(jsonMatch[1] || jsonMatch[0]);\n\t\t\tconst rationale = parsed.rationale || \"\";\n\t\t\tconst writes: ReflectionWrite[] = [];\n\n\t\t\tif (Array.isArray(parsed.writes)) {\n\t\t\t\tfor (const w of parsed.writes) {\n\t\t\t\t\tif (w && typeof w === \"object\") {\n\t\t\t\t\t\tif (\n\t\t\t\t\t\t\tw.kind === \"memory_add\" &&\n\t\t\t\t\t\t\t(w.section === \"MEMORY\" || w.section === \"USER\") &&\n\t\t\t\t\t\t\ttypeof w.text === \"string\"\n\t\t\t\t\t\t) {\n\t\t\t\t\t\t\twrites.push({ kind: \"memory_add\", section: w.section, text: w.text });\n\t\t\t\t\t\t} else if (\n\t\t\t\t\t\t\tw.kind === \"memory_replace\" &&\n\t\t\t\t\t\t\ttypeof w.target === \"string\" &&\n\t\t\t\t\t\t\ttypeof w.text === \"string\"\n\t\t\t\t\t\t) {\n\t\t\t\t\t\t\twrites.push({ kind: \"memory_replace\", target: w.target, text: w.text });\n\t\t\t\t\t\t} else if (w.kind === \"memory_remove\" && typeof w.target === \"string\") {\n\t\t\t\t\t\t\twrites.push({ kind: \"memory_remove\", target: w.target });\n\t\t\t\t\t\t} else if (\n\t\t\t\t\t\t\tw.kind === \"promote_skill\" &&\n\t\t\t\t\t\t\ttypeof w.name === \"string\" &&\n\t\t\t\t\t\t\ttypeof w.description === \"string\" &&\n\t\t\t\t\t\t\ttypeof w.body === \"string\"\n\t\t\t\t\t\t) {\n\t\t\t\t\t\t\twrites.push({ kind: \"promote_skill\", name: w.name, description: w.description, body: w.body });\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\twrites,\n\t\t\t\tusage: compResult.usage,\n\t\t\t\trationale,\n\t\t\t};\n\t\t} catch (err) {\n\t\t\t// Zeroed/fallback usage representation\n\t\t\tconst emptyUsage: Usage = {\n\t\t\t\tinput: 0,\n\t\t\t\toutput: 0,\n\t\t\t\tcacheRead: 0,\n\t\t\t\tcacheWrite: 0,\n\t\t\t\ttotalTokens: 0,\n\t\t\t\tcost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },\n\t\t\t};\n\t\t\treturn {\n\t\t\t\twrites: [],\n\t\t\t\tusage: usage ?? emptyUsage,\n\t\t\t\trationale: `Error during reflection: ${String(err)}`,\n\t\t\t};\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"reflection-engine.js","sourceRoot":"","sources":["../../../src/core/learning/reflection-engine.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Usage } from \"@caupulican/pi-ai\";\n\nexport type StopReason = \"stop\" | \"toolUse\" | \"aborted\" | \"error\" | string;\n\nexport interface IsolatedCompletionResult {\n\ttext: string;\n\tusage: Usage;\n\tstopReason: StopReason;\n}\n\nexport type ReflectionTrigger = \"complex\" | \"corrective\" | \"durable\" | \"session-end\" | \"none\";\n\nexport interface DemandSignals {\n\ttrigger: ReflectionTrigger;\n\ttoolCallCount: number;\n\thadCorrection: boolean;\n\tcontextHeadroomPct: number; // 0..100\n\tusefulLately: number; // 0..1 rolling score\n}\n\nexport interface DemandPlan {\n\tact: \"skip\" | \"reflect\";\n\treason: string;\n\ttokenBudget: number;\n}\n\n/**\n * Pure zero-I/O heuristic to decide whether the current turn justifies a reflection run\n * and determine the token budget under the cheap-tool net-negative doctrine.\n */\nexport function decideDemand(signals: DemandSignals): DemandPlan {\n\tif (signals.trigger === \"none\") {\n\t\treturn { act: \"skip\", reason: \"No trigger detected\", tokenBudget: 0 };\n\t}\n\tif (signals.contextHeadroomPct < 10) {\n\t\treturn { act: \"skip\", reason: \"Context headroom is critically low (< 10%)\", tokenBudget: 0 };\n\t}\n\n\t// Dynamic token budget based on headroom (keep reflection bounded between 500 and 1500 tokens)\n\tconst baseBudget = 1000;\n\tconst tokenBudget = Math.max(500, Math.min(1500, Math.round(baseBudget * (signals.contextHeadroomPct / 100))));\n\n\tif (signals.hadCorrection) {\n\t\treturn { act: \"reflect\", reason: \"Correction detected in the turn\", tokenBudget };\n\t}\n\tif (signals.trigger === \"durable\") {\n\t\treturn { act: \"reflect\", reason: \"Durable fact or preference detected in the turn\", tokenBudget };\n\t}\n\tif (signals.trigger === \"session-end\") {\n\t\treturn { act: \"reflect\", reason: \"Session end reflection triggered\", tokenBudget };\n\t}\n\tif (signals.trigger === \"complex\") {\n\t\tif (signals.toolCallCount >= 3) {\n\t\t\treturn { act: \"reflect\", reason: `Complex turn with ${signals.toolCallCount} tool calls`, tokenBudget };\n\t\t}\n\t}\n\n\treturn { act: \"skip\", reason: \"Signals do not justify reflection overhead\", tokenBudget: 0 };\n}\n\nexport interface ReflectionInput {\n\trecentTurnText: string; // host serializes the just-finished turn\n\texistingMemory: string; // current MEMORY.md + USER.md snapshot\n\tplan: DemandPlan;\n\t// host-injected isolated completion function:\n\tcomplete: (systemPrompt: string, userPrompt: string) => Promise<IsolatedCompletionResult>;\n}\n\nexport type ReflectionWrite =\n\t| { kind: \"memory_add\"; section: \"MEMORY\" | \"USER\"; text: string }\n\t| { kind: \"memory_replace\"; target: string; text: string }\n\t| { kind: \"memory_remove\"; target: string }\n\t// R7 memory-to-behavior: promote a recurring procedural workflow into an executable skill.\n\t| { kind: \"promote_skill\"; name: string; description: string; body: string };\n\nexport interface ReflectionResult {\n\twrites: ReflectionWrite[];\n\tusage: Usage;\n\trationale: string;\n}\n\n/**\n * STATIC reflection system prompt (Hermes-parity #33). It is byte-identical across every reflection\n * pass — the variable parts (existing memory snapshot + the turn transcript) live in the USER prompt —\n * so the provider prompt-cache reuses this prefix instead of re-billing it each pass (cost guard).\n * Do NOT interpolate per-call data into this constant or caching breaks.\n */\nexport const REFLECTION_SYSTEM_PROMPT = `You are a reflection engine. Your job is to analyze the recent conversation turn, compare it against the agent's existing memory, and decide if any memory updates are needed.\n\nMemory guidelines:\n- \"MEMORY\" is for project facts, configuration, repeatable workflows, and coding findings.\n- \"USER\" is for user preferences, patterns, and style specifications.\n- Avoid duplicate facts. If the fact is already represented, do not add it.\n- CONFRONT existing memory: if the new turn contradicts or updates an existing fact, use \"memory_replace\" or \"memory_remove\" to supersede the old fact rather than blindly appending.\n- Keep memories short, factual, and direct. No fluff.\n- Do NOT capture transient/environment-specific noise: tool/network failures, one-off errors, or a single narrative event. Persist only durable facts and preferences.\n- PROMOTE to behavior: if the turn established a REPEATABLE, multi-step PROCEDURE/workflow (not a one-off fact) that should govern a future class of tasks, emit a \"promote_skill\" instead of (or in addition to) a memory fact. Only promote a genuinely reusable procedure — never a single fact, a one-off narrative, or environment-specific noise. Prefer a memory fact when unsure.\n\nYou must output your analysis and writes in the following JSON format inside a \\`\\`\\`json\\`\\`\\` code fence:\n{\n  \"rationale\": \"Explanation of your reasoning\",\n  \"writes\": [\n    { \"kind\": \"memory_add\", \"section\": \"MEMORY\" | \"USER\", \"text\": \"New direct fact to append\" },\n    { \"kind\": \"memory_replace\", \"target\": \"Exact text substring to replace\", \"text\": \"New replacement text\" },\n    { \"kind\": \"memory_remove\", \"target\": \"Exact text substring to remove\" },\n    { \"kind\": \"promote_skill\", \"name\": \"kebab-case-skill-name\", \"description\": \"one line of when to use it\", \"body\": \"Markdown: the step-by-step procedure\" }\n  ]\n}\n`;\n\nexport class ReflectionEngine {\n\t/**\n\t * Build the reflection prompt, call the injected isolated complete(),\n\t * parse the response, confront existing memory, and return memory writes.\n\t * Zero direct I/O.\n\t */\n\tasync reflect(input: ReflectionInput): Promise<ReflectionResult> {\n\t\tconst systemPrompt = REFLECTION_SYSTEM_PROMPT;\n\n\t\t// Variable inputs go in the USER prompt so the system prefix above stays cache-stable (#33).\n\t\tconst userPrompt = `Existing Memory snapshot:\n${input.existingMemory}\n\nRecent turn transcript:\n${input.recentTurnText}\n\nAnalyze this turn against the existing memory and output your memory updates.`;\n\n\t\tlet usage: Usage | undefined;\n\t\ttry {\n\t\t\tconst compResult = await input.complete(systemPrompt, userPrompt);\n\t\t\tusage = compResult.usage;\n\t\t\tconst text = compResult.text;\n\n\t\t\tconst jsonMatch = text.match(/```json\\s*([\\s\\S]*?)\\s*```/) || text.match(/{[\\s\\S]*}/);\n\t\t\tif (!jsonMatch) {\n\t\t\t\treturn {\n\t\t\t\t\twrites: [],\n\t\t\t\t\tusage: compResult.usage,\n\t\t\t\t\trationale: `Failed to locate JSON response. Raw text:\\n${text}`,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tconst parsed = JSON.parse(jsonMatch[1] || jsonMatch[0]);\n\t\t\tconst rationale = parsed.rationale || \"\";\n\t\t\tconst writes: ReflectionWrite[] = [];\n\n\t\t\tif (Array.isArray(parsed.writes)) {\n\t\t\t\tfor (const w of parsed.writes) {\n\t\t\t\t\tif (w && typeof w === \"object\") {\n\t\t\t\t\t\tif (\n\t\t\t\t\t\t\tw.kind === \"memory_add\" &&\n\t\t\t\t\t\t\t(w.section === \"MEMORY\" || w.section === \"USER\") &&\n\t\t\t\t\t\t\ttypeof w.text === \"string\"\n\t\t\t\t\t\t) {\n\t\t\t\t\t\t\twrites.push({ kind: \"memory_add\", section: w.section, text: w.text });\n\t\t\t\t\t\t} else if (\n\t\t\t\t\t\t\tw.kind === \"memory_replace\" &&\n\t\t\t\t\t\t\ttypeof w.target === \"string\" &&\n\t\t\t\t\t\t\ttypeof w.text === \"string\"\n\t\t\t\t\t\t) {\n\t\t\t\t\t\t\twrites.push({ kind: \"memory_replace\", target: w.target, text: w.text });\n\t\t\t\t\t\t} else if (w.kind === \"memory_remove\" && typeof w.target === \"string\") {\n\t\t\t\t\t\t\twrites.push({ kind: \"memory_remove\", target: w.target });\n\t\t\t\t\t\t} else if (\n\t\t\t\t\t\t\tw.kind === \"promote_skill\" &&\n\t\t\t\t\t\t\ttypeof w.name === \"string\" &&\n\t\t\t\t\t\t\ttypeof w.description === \"string\" &&\n\t\t\t\t\t\t\ttypeof w.body === \"string\"\n\t\t\t\t\t\t) {\n\t\t\t\t\t\t\twrites.push({ kind: \"promote_skill\", name: w.name, description: w.description, body: w.body });\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\treturn {\n\t\t\t\twrites,\n\t\t\t\tusage: compResult.usage,\n\t\t\t\trationale,\n\t\t\t};\n\t\t} catch (err) {\n\t\t\t// Zeroed/fallback usage representation\n\t\t\tconst emptyUsage: Usage = {\n\t\t\t\tinput: 0,\n\t\t\t\toutput: 0,\n\t\t\t\tcacheRead: 0,\n\t\t\t\tcacheWrite: 0,\n\t\t\t\ttotalTokens: 0,\n\t\t\t\tcost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },\n\t\t\t};\n\t\t\treturn {\n\t\t\t\twrites: [],\n\t\t\t\tusage: usage ?? emptyUsage,\n\t\t\t\trationale: `Error during reflection: ${String(err)}`,\n\t\t\t};\n\t\t}\n\t}\n}\n"]}

package/dist/core/learning/reflection-turn-analysis.d.ts

@@ -0,0 +1,20 @@
+import type { AgentMessage } from "@caupulican/pi-agent-core";
+import type { DemandSignals } from "./reflection-engine.ts";
+export declare function boundReflectionSemanticText(text: string, maxChars: number): string;
+export interface ReflectionTurnAnalysis {
+    trigger: DemandSignals["trigger"];
+    toolCallCount: number;
+    hadCorrection: boolean;
+    explicitUserMemoryInstruction: boolean;
+    recentTurnText: string;
+    userText: string;
+    assistantText: string;
+    digest: string;
+}
+/**
+ * Produce the only transcript projection used by automatic learning and provider turn-sync hooks.
+ * It retains bounded user/assistant semantics plus tool names/counts, never raw tool-result payloads.
+ */
+export declare function analyzeReflectionTurn(messages: AgentMessage[], complexTaskThreshold: number): ReflectionTurnAnalysis;
+export declare function reflectionTriggerPriority(trigger: DemandSignals["trigger"]): number;
+//# sourceMappingURL=reflection-turn-analysis.d.ts.map

package/dist/core/learning/reflection-turn-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection-turn-analysis.d.ts","sourceRoot":"","sources":["../../../src/core/learning/reflection-turn-analysis.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAW5D,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOlF;AAmCD,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,6BAA6B,EAAE,OAAO,CAAC;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,oBAAoB,EAAE,MAAM,GAAG,sBAAsB,CAsEpH;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,MAAM,CAanF"}

package/dist/core/learning/reflection-turn-analysis.js

@@ -0,0 +1,136 @@
+import { createHash } from "node:crypto";
+const REFLECTION_TURN_MAX_CHARS = 12_000;
+const REFLECTION_ROLE_MAX_CHARS = 6_000;
+const CORRECTION_SIGNAL = /\b(next time|for future|from now on|remember this|don't|do not|avoid|instead|you should|should have|you forgot|you missed|not what i asked|wrong again)\b/i;
+const EXPLICIT_DURABLE_SIGNAL = /\b(remember|store (?:this|that)|keep (?:this|that) in memory|my preference|i prefer|standing rule|always use|never use)\b/i;
+const DURABLE_WORK_SIGNAL = /\b(confirmed root cause|root cause (?:is|was)|fixed|implemented|regression|invariant|durable decision|repeatable workaround)\b/i;
+export function boundReflectionSemanticText(text, maxChars) {
+    const trimmed = text.trim();
+    if (trimmed.length <= maxChars)
+        return trimmed;
+    const marker = "\n...[semantic digest truncated]...\n";
+    const retainedChars = maxChars - marker.length;
+    const headChars = Math.ceil(retainedChars / 2);
+    return `${trimmed.slice(0, headChars).trimEnd()}${marker}${trimmed.slice(-(retainedChars - headChars)).trimStart()}`;
+}
+function redactReflectionSecrets(text) {
+    return text
+        .replace(/-----BEGIN [A-Z ]*(?:PRIVATE|OPENSSH|RSA|DSA|EC) KEY-----[\s\S]*?-----END [A-Z ]*(?:PRIVATE|OPENSSH|RSA|DSA|EC) KEY-----/g, "[redacted-private-key]")
+        .replace(/\b(?:sk|pk)-(?:proj-)?[A-Za-z0-9_-]{12,}/g, "[redacted-api-key]")
+        .replace(/\bsk-ant-[A-Za-z0-9_-]{12,}/g, "[redacted-api-key]")
+        .replace(/\b(?:ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{20,}/g, "[redacted-github-token]")
+        .replace(/\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, "[redacted-aws-access-key]")
+        .replace(/(?:Bearer\s+)[A-Za-z0-9._-]{16,}/gi, "Bearer [redacted]")
+        .replace(/([?&](?:key|token|api_key|access_token|secret|password)=)[^&\s]+/gi, "$1[redacted]")
+        .replace(/((?:access|refresh|token|apiKey|api_key|password|secret|authorization|auth)\s*[:=]\s*)[^\s,'"}]{8,}/gi, "$1[redacted]");
+}
+function messageText(message) {
+    const content = message.content;
+    if (typeof content === "string")
+        return redactReflectionSecrets(content);
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const candidate = block;
+        if (candidate.type === "text" && typeof candidate.text === "string") {
+            parts.push(redactReflectionSecrets(candidate.text));
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * Produce the only transcript projection used by automatic learning and provider turn-sync hooks.
+ * It retains bounded user/assistant semantics plus tool names/counts, never raw tool-result payloads.
+ */
+export function analyzeReflectionTurn(messages, complexTaskThreshold) {
+    const semanticLines = [];
+    const userParts = [];
+    const assistantParts = [];
+    const toolNames = new Set();
+    let toolCalls = 0;
+    let toolResults = 0;
+    for (const message of messages) {
+        const raw = message;
+        const role = String(raw.role ?? "");
+        if (role === "user" || role === "assistant") {
+            const text = messageText(message).trim();
+            if (text) {
+                semanticLines.push(`${role}: ${boundReflectionSemanticText(text, 4_000)}`);
+                if (role === "user")
+                    userParts.push(text);
+                else
+                    assistantParts.push(text);
+            }
+        }
+        const content = raw.content;
+        if (Array.isArray(content)) {
+            for (const block of content) {
+                if (!block || typeof block !== "object")
+                    continue;
+                const candidate = block;
+                if (candidate.type === "toolCall") {
+                    toolCalls += 1;
+                    if (typeof candidate.name === "string")
+                        toolNames.add(candidate.name);
+                }
+            }
+        }
+        if (role === "toolResult" || role === "bashExecution") {
+            toolResults += 1;
+            if (typeof raw.toolName === "string")
+                toolNames.add(raw.toolName);
+            else if (role === "bashExecution")
+                toolNames.add("bash");
+        }
+    }
+    const toolCallCount = Math.max(toolCalls, toolResults);
+    if (toolCallCount > 0) {
+        semanticLines.push(`[tools: ${[...toolNames].sort().join(", ") || "unnamed"}; calls=${toolCallCount}]`);
+    }
+    const userText = boundReflectionSemanticText(userParts.join("\n"), REFLECTION_ROLE_MAX_CHARS);
+    const assistantText = boundReflectionSemanticText(assistantParts.join("\n"), REFLECTION_ROLE_MAX_CHARS);
+    const hadCorrection = CORRECTION_SIGNAL.test(userText);
+    const hasExplicitDurableSignal = userParts.some((part) => EXPLICIT_DURABLE_SIGNAL.test(part));
+    const explicitUserMemoryInstruction = userParts.length > 0 && userParts.every((part) => EXPLICIT_DURABLE_SIGNAL.test(part));
+    const hasDurableSignal = hasExplicitDurableSignal || (toolCallCount > 0 && DURABLE_WORK_SIGNAL.test(assistantText));
+    const trigger = hadCorrection
+        ? "corrective"
+        : hasDurableSignal
+            ? "durable"
+            : toolCallCount >= Math.max(1, complexTaskThreshold)
+                ? "complex"
+                : "none";
+    const recentTurnText = boundReflectionSemanticText(semanticLines.join("\n"), REFLECTION_TURN_MAX_CHARS);
+    const digest = createHash("sha256")
+        .update(`${recentTurnText}\0${toolCallCount}\0${trigger}`)
+        .digest("hex")
+        .slice(0, 24);
+    return {
+        trigger,
+        toolCallCount,
+        hadCorrection,
+        explicitUserMemoryInstruction,
+        recentTurnText,
+        userText,
+        assistantText,
+        digest,
+    };
+}
+export function reflectionTriggerPriority(trigger) {
+    switch (trigger) {
+        case "corrective":
+            return 4;
+        case "durable":
+            return 3;
+        case "complex":
+            return 2;
+        case "session-end":
+            return 1;
+        default:
+            return 0;
+    }
+}
+//# sourceMappingURL=reflection-turn-analysis.js.map

package/dist/core/learning/reflection-turn-analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection-turn-analysis.js","sourceRoot":"","sources":["../../../src/core/learning/reflection-turn-analysis.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { AgentMessage } from \"@caupulican/pi-agent-core\";\nimport type { DemandSignals } from \"./reflection-engine.ts\";\n\nconst REFLECTION_TURN_MAX_CHARS = 12_000;\nconst REFLECTION_ROLE_MAX_CHARS = 6_000;\nconst CORRECTION_SIGNAL =\n\t/\\b(next time|for future|from now on|remember this|don't|do not|avoid|instead|you should|should have|you forgot|you missed|not what i asked|wrong again)\\b/i;\nconst EXPLICIT_DURABLE_SIGNAL =\n\t/\\b(remember|store (?:this|that)|keep (?:this|that) in memory|my preference|i prefer|standing rule|always use|never use)\\b/i;\nconst DURABLE_WORK_SIGNAL =\n\t/\\b(confirmed root cause|root cause (?:is|was)|fixed|implemented|regression|invariant|durable decision|repeatable workaround)\\b/i;\n\nexport function boundReflectionSemanticText(text: string, maxChars: number): string {\n\tconst trimmed = text.trim();\n\tif (trimmed.length <= maxChars) return trimmed;\n\tconst marker = \"\\n...[semantic digest truncated]...\\n\";\n\tconst retainedChars = maxChars - marker.length;\n\tconst headChars = Math.ceil(retainedChars / 2);\n\treturn `${trimmed.slice(0, headChars).trimEnd()}${marker}${trimmed.slice(-(retainedChars - headChars)).trimStart()}`;\n}\n\nfunction redactReflectionSecrets(text: string): string {\n\treturn text\n\t\t.replace(\n\t\t\t/-----BEGIN [A-Z ]*(?:PRIVATE|OPENSSH|RSA|DSA|EC) KEY-----[\\s\\S]*?-----END [A-Z ]*(?:PRIVATE|OPENSSH|RSA|DSA|EC) KEY-----/g,\n\t\t\t\"[redacted-private-key]\",\n\t\t)\n\t\t.replace(/\\b(?:sk|pk)-(?:proj-)?[A-Za-z0-9_-]{12,}/g, \"[redacted-api-key]\")\n\t\t.replace(/\\bsk-ant-[A-Za-z0-9_-]{12,}/g, \"[redacted-api-key]\")\n\t\t.replace(/\\b(?:ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{20,}/g, \"[redacted-github-token]\")\n\t\t.replace(/\\b(?:AKIA|ASIA)[0-9A-Z]{16}\\b/g, \"[redacted-aws-access-key]\")\n\t\t.replace(/(?:Bearer\\s+)[A-Za-z0-9._-]{16,}/gi, \"Bearer [redacted]\")\n\t\t.replace(/([?&](?:key|token|api_key|access_token|secret|password)=)[^&\\s]+/gi, \"$1[redacted]\")\n\t\t.replace(\n\t\t\t/((?:access|refresh|token|apiKey|api_key|password|secret|authorization|auth)\\s*[:=]\\s*)[^\\s,'\"}]{8,}/gi,\n\t\t\t\"$1[redacted]\",\n\t\t);\n}\n\nfunction messageText(message: AgentMessage): string {\n\tconst content = (message as unknown as { content?: unknown }).content;\n\tif (typeof content === \"string\") return redactReflectionSecrets(content);\n\tif (!Array.isArray(content)) return \"\";\n\tconst parts: string[] = [];\n\tfor (const block of content) {\n\t\tif (!block || typeof block !== \"object\") continue;\n\t\tconst candidate = block as { type?: unknown; text?: unknown };\n\t\tif (candidate.type === \"text\" && typeof candidate.text === \"string\") {\n\t\t\tparts.push(redactReflectionSecrets(candidate.text));\n\t\t}\n\t}\n\treturn parts.join(\"\\n\");\n}\n\nexport interface ReflectionTurnAnalysis {\n\ttrigger: DemandSignals[\"trigger\"];\n\ttoolCallCount: number;\n\thadCorrection: boolean;\n\texplicitUserMemoryInstruction: boolean;\n\trecentTurnText: string;\n\tuserText: string;\n\tassistantText: string;\n\tdigest: string;\n}\n\n/**\n * Produce the only transcript projection used by automatic learning and provider turn-sync hooks.\n * It retains bounded user/assistant semantics plus tool names/counts, never raw tool-result payloads.\n */\nexport function analyzeReflectionTurn(messages: AgentMessage[], complexTaskThreshold: number): ReflectionTurnAnalysis {\n\tconst semanticLines: string[] = [];\n\tconst userParts: string[] = [];\n\tconst assistantParts: string[] = [];\n\tconst toolNames = new Set<string>();\n\tlet toolCalls = 0;\n\tlet toolResults = 0;\n\n\tfor (const message of messages) {\n\t\tconst raw = message as unknown as Record<string, unknown>;\n\t\tconst role = String(raw.role ?? \"\");\n\t\tif (role === \"user\" || role === \"assistant\") {\n\t\t\tconst text = messageText(message).trim();\n\t\t\tif (text) {\n\t\t\t\tsemanticLines.push(`${role}: ${boundReflectionSemanticText(text, 4_000)}`);\n\t\t\t\tif (role === \"user\") userParts.push(text);\n\t\t\t\telse assistantParts.push(text);\n\t\t\t}\n\t\t}\n\t\tconst content = raw.content;\n\t\tif (Array.isArray(content)) {\n\t\t\tfor (const block of content) {\n\t\t\t\tif (!block || typeof block !== \"object\") continue;\n\t\t\t\tconst candidate = block as Record<string, unknown>;\n\t\t\t\tif (candidate.type === \"toolCall\") {\n\t\t\t\t\ttoolCalls += 1;\n\t\t\t\t\tif (typeof candidate.name === \"string\") toolNames.add(candidate.name);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tif (role === \"toolResult\" || role === \"bashExecution\") {\n\t\t\ttoolResults += 1;\n\t\t\tif (typeof raw.toolName === \"string\") toolNames.add(raw.toolName);\n\t\t\telse if (role === \"bashExecution\") toolNames.add(\"bash\");\n\t\t}\n\t}\n\n\tconst toolCallCount = Math.max(toolCalls, toolResults);\n\tif (toolCallCount > 0) {\n\t\tsemanticLines.push(`[tools: ${[...toolNames].sort().join(\", \") || \"unnamed\"}; calls=${toolCallCount}]`);\n\t}\n\tconst userText = boundReflectionSemanticText(userParts.join(\"\\n\"), REFLECTION_ROLE_MAX_CHARS);\n\tconst assistantText = boundReflectionSemanticText(assistantParts.join(\"\\n\"), REFLECTION_ROLE_MAX_CHARS);\n\tconst hadCorrection = CORRECTION_SIGNAL.test(userText);\n\tconst hasExplicitDurableSignal = userParts.some((part) => EXPLICIT_DURABLE_SIGNAL.test(part));\n\tconst explicitUserMemoryInstruction =\n\t\tuserParts.length > 0 && userParts.every((part) => EXPLICIT_DURABLE_SIGNAL.test(part));\n\tconst hasDurableSignal = hasExplicitDurableSignal || (toolCallCount > 0 && DURABLE_WORK_SIGNAL.test(assistantText));\n\tconst trigger: DemandSignals[\"trigger\"] = hadCorrection\n\t\t? \"corrective\"\n\t\t: hasDurableSignal\n\t\t\t? \"durable\"\n\t\t\t: toolCallCount >= Math.max(1, complexTaskThreshold)\n\t\t\t\t? \"complex\"\n\t\t\t\t: \"none\";\n\tconst recentTurnText = boundReflectionSemanticText(semanticLines.join(\"\\n\"), REFLECTION_TURN_MAX_CHARS);\n\tconst digest = createHash(\"sha256\")\n\t\t.update(`${recentTurnText}\\0${toolCallCount}\\0${trigger}`)\n\t\t.digest(\"hex\")\n\t\t.slice(0, 24);\n\treturn {\n\t\ttrigger,\n\t\ttoolCallCount,\n\t\thadCorrection,\n\t\texplicitUserMemoryInstruction,\n\t\trecentTurnText,\n\t\tuserText,\n\t\tassistantText,\n\t\tdigest,\n\t};\n}\n\nexport function reflectionTriggerPriority(trigger: DemandSignals[\"trigger\"]): number {\n\tswitch (trigger) {\n\t\tcase \"corrective\":\n\t\t\treturn 4;\n\t\tcase \"durable\":\n\t\t\treturn 3;\n\t\tcase \"complex\":\n\t\t\treturn 2;\n\t\tcase \"session-end\":\n\t\t\treturn 1;\n\t\tdefault:\n\t\t\treturn 0;\n\t}\n}\n"]}

package/dist/core/learning/session-learning-decision.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-learning-decision.d.ts","sourceRoot":"","sources":["../../../src/core/learning/session-learning-decision.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAIN,KAAK,sBAAsB,EAC3B,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,6BAA6B,sBAAsB,CAAC;AAEjE,MAAM,MAAM,+BAA+B,GAAG,sBAAsB,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;AASnG,wBAAgB,8BAA8B,CAC7C,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACzD,QAAQ,EAAE,gBAAgB,GACxB,MAAM,CAER;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,gBAAgB,EAAE,CAEjG","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { LearningDecision } from \"../autonomy/contracts.ts\";\nimport {\n\tappendSessionSnapshot,\n\tgetSessionSnapshots,\n\ttype SessionSnapshotCodec,\n\ttype SessionSnapshotPayload,\n} from \"../session-snapshot.ts\";\nimport { cloneLearningDecisionForStorage, isLearningDecision } from \"./learning-gate.ts\";\n\nexport const LEARNING_DECISION_CUSTOM_TYPE = \"learning_decision\";\n\nexport type LearningDecisionSnapshotPayload = SessionSnapshotPayload<\"decision\", LearningDecision>;\n\nconst LEARNING_DECISION_SNAPSHOT_CODEC: SessionSnapshotCodec<LearningDecision, \"decision\"> = {\n\tcustomType: LEARNING_DECISION_CUSTOM_TYPE,\n\tvalueKey: \"decision\",\n\tisValue: isLearningDecision,\n\tclone: cloneLearningDecisionForStorage,\n};\n\nexport function appendLearningDecisionSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tdecision: LearningDecision,\n): string {\n\treturn appendSessionSnapshot(sessionManager, LEARNING_DECISION_SNAPSHOT_CODEC, decision);\n}\n\nexport function getLearningDecisionSnapshots(entries: readonly SessionEntry[]): LearningDecision[] {\n\treturn getSessionSnapshots(entries, LEARNING_DECISION_SNAPSHOT_CODEC);\n}\n"]}
+{"version":3,"file":"session-learning-decision.d.ts","sourceRoot":"","sources":["../../../src/core/learning/session-learning-decision.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAIN,KAAK,sBAAsB,EAC3B,MAAM,wBAAwB,CAAC;AAGhC,eAAO,MAAM,6BAA6B,sBAAsB,CAAC;AAEjE,MAAM,MAAM,+BAA+B,GAAG,sBAAsB,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;AASnG,wBAAgB,8BAA8B,CAC7C,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACzD,QAAQ,EAAE,gBAAgB,GACxB,MAAM,CAER;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,gBAAgB,EAAE,CAEjG"}

package/dist/core/learning/session-learning-decision.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-learning-decision.js","sourceRoot":"","sources":["../../../src/core/learning/session-learning-decision.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,qBAAqB,EACrB,mBAAmB,GAGnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,+BAA+B,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEzF,MAAM,CAAC,MAAM,6BAA6B,GAAG,mBAAmB,CAAC;AAIjE,MAAM,gCAAgC,GAAuD;IAC5F,UAAU,EAAE,6BAA6B;IACzC,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,kBAAkB;IAC3B,KAAK,EAAE,+BAA+B;CACtC,CAAC;AAEF,MAAM,UAAU,8BAA8B,CAC7C,cAAyD,EACzD,QAA0B,EACjB;IACT,OAAO,qBAAqB,CAAC,cAAc,EAAE,gCAAgC,EAAE,QAAQ,CAAC,CAAC;AAAA,CACzF;AAED,MAAM,UAAU,4BAA4B,CAAC,OAAgC,EAAsB;IAClG,OAAO,mBAAmB,CAAC,OAAO,EAAE,gCAAgC,CAAC,CAAC;AAAA,CACtE","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { LearningDecision } from \"../autonomy/contracts.ts\";\nimport {\n\tappendSessionSnapshot,\n\tgetSessionSnapshots,\n\ttype SessionSnapshotCodec,\n\ttype SessionSnapshotPayload,\n} from \"../session-snapshot.ts\";\nimport { cloneLearningDecisionForStorage, isLearningDecision } from \"./learning-gate.ts\";\n\nexport const LEARNING_DECISION_CUSTOM_TYPE = \"learning_decision\";\n\nexport type LearningDecisionSnapshotPayload = SessionSnapshotPayload<\"decision\", LearningDecision>;\n\nconst LEARNING_DECISION_SNAPSHOT_CODEC: SessionSnapshotCodec<LearningDecision, \"decision\"> = {\n\tcustomType: LEARNING_DECISION_CUSTOM_TYPE,\n\tvalueKey: \"decision\",\n\tisValue: isLearningDecision,\n\tclone: cloneLearningDecisionForStorage,\n};\n\nexport function appendLearningDecisionSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tdecision: LearningDecision,\n): string {\n\treturn appendSessionSnapshot(sessionManager, LEARNING_DECISION_SNAPSHOT_CODEC, decision);\n}\n\nexport function getLearningDecisionSnapshots(entries: readonly SessionEntry[]): LearningDecision[] {\n\treturn getSessionSnapshots(entries, LEARNING_DECISION_SNAPSHOT_CODEC);\n}\n"]}
+{"version":3,"file":"session-learning-decision.js","sourceRoot":"","sources":["../../../src/core/learning/session-learning-decision.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,qBAAqB,EACrB,mBAAmB,GAGnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,+BAA+B,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEzF,MAAM,CAAC,MAAM,6BAA6B,GAAG,mBAAmB,CAAC;AAIjE,MAAM,gCAAgC,GAAuD;IAC5F,UAAU,EAAE,6BAA6B;IACzC,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,kBAAkB;IAC3B,KAAK,EAAE,+BAA+B;CACtC,CAAC;AAEF,MAAM,UAAU,8BAA8B,CAC7C,cAAyD,EACzD,QAA0B;IAE1B,OAAO,qBAAqB,CAAC,cAAc,EAAE,gCAAgC,EAAE,QAAQ,CAAC,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,OAAgC;IAC5E,OAAO,mBAAmB,CAAC,OAAO,EAAE,gCAAgC,CAAC,CAAC;AACvE,CAAC","sourcesContent":["import type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { LearningDecision } from \"../autonomy/contracts.ts\";\nimport {\n\tappendSessionSnapshot,\n\tgetSessionSnapshots,\n\ttype SessionSnapshotCodec,\n\ttype SessionSnapshotPayload,\n} from \"../session-snapshot.ts\";\nimport { cloneLearningDecisionForStorage, isLearningDecision } from \"./learning-gate.ts\";\n\nexport const LEARNING_DECISION_CUSTOM_TYPE = \"learning_decision\";\n\nexport type LearningDecisionSnapshotPayload = SessionSnapshotPayload<\"decision\", LearningDecision>;\n\nconst LEARNING_DECISION_SNAPSHOT_CODEC: SessionSnapshotCodec<LearningDecision, \"decision\"> = {\n\tcustomType: LEARNING_DECISION_CUSTOM_TYPE,\n\tvalueKey: \"decision\",\n\tisValue: isLearningDecision,\n\tclone: cloneLearningDecisionForStorage,\n};\n\nexport function appendLearningDecisionSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tdecision: LearningDecision,\n): string {\n\treturn appendSessionSnapshot(sessionManager, LEARNING_DECISION_SNAPSHOT_CODEC, decision);\n}\n\nexport function getLearningDecisionSnapshots(entries: readonly SessionEntry[]): LearningDecision[] {\n\treturn getSessionSnapshots(entries, LEARNING_DECISION_SNAPSHOT_CODEC);\n}\n"]}

package/dist/core/learning/skill-curator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-curator.d.ts","sourceRoot":"","sources":["../../../src/core/learning/skill-curator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,uFAAqF;AACrF,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC9B,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAkG;IAClG,gBAAgB,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,eAAO,MAAM,uBAAuB,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,CAG/D,CAAC;AAEF,MAAM,WAAW,iBAAiB;IACjC,+EAA+E;IAC/E,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,sGAAsG;IACtG,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,iBAAiB,CAgC7G;AAWD;;;;GAIG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,SAAS,EAAE,MAAM,EAI5B;IAED;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAWzC;IAED,kEAAkE;IAClE,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,iBAAiB,CAOlG;IAED;;;;;OAKG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBzG;IAED,qFAAqF;IACrF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,2FAA2F;IAC3F,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,kBAAkB,IAAI,iBAAiB,EAAE,CA+BxC;IAED,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;CAOjB;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI9D","sourcesContent":["/**\n * Skill curator (Hermes-parity #32). Reflection (R7) promotes recurring procedures into SKILL.md files;\n * without curation they accumulate forever, bloating tool/context and raising per-turn cost. The curator\n * tracks usage of PROMOTED skills (frontmatter `promoted: true`) and PROPOSES — never auto-applies —\n * archiving stale ones and consolidating overlapping ones. Hand-authored user skills are never touched.\n *\n * Design (locked with agy): propose-only, session-start + idle triggers (not per-turn), restorable\n * archive (non-destructive), and consolidation is a flagged suggestion (never an auto-merge).\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { jaccard, tokenize } from \"../tools/skill-audit.ts\";\nimport { withFileLock, withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\n\n/** Per-promoted-skill signal the proposal logic reasons over. Pure data — no I/O. */\nexport interface PromotedSkillInfo {\n\tname: string;\n\t/** When the skill file was created (ms epoch); guards a freshly-promoted skill from instant archival. */\n\tcreatedMs: number;\n\t/** Last time the skill was loaded/used (ms epoch); 0 if never used. */\n\tlastUsedMs: number;\n\tuseCount: number;\n\t/** Tokens from name+description+body, for overlap detection. */\n\tkeywords: string[];\n}\n\nexport interface CuratorOptions {\n\t/** A promoted skill unused and older than this many days is proposed for archival. Default 30. */\n\tstaleDays: number;\n\t/** Token-Jaccard ≥ this between two promoted skills flags them for consolidation. Default 0.5. */\n\toverlapThreshold: number;\n\t/** Current time (ms epoch); injected so the proposal logic stays pure/testable. */\n\tnow: number;\n}\n\nexport const DEFAULT_CURATOR_OPTIONS: Omit<CuratorOptions, \"now\"> = {\n\tstaleDays: 30,\n\toverlapThreshold: 0.5,\n};\n\nexport interface CurationProposals {\n\t/** Promoted skills proposed for (restorable) archival, with a human reason. */\n\tarchive: Array<{ name: string; reason: string }>;\n\t/** Pairs of promoted skills that overlap enough to consider merging (flag only, never auto-merge). */\n\tconsolidate: Array<{ names: [string, string]; overlap: number }>;\n}\n\n/**\n * Pure proposal logic: decide which promoted skills to PROPOSE archiving (stale + unused) and which pairs\n * overlap enough to PROPOSE consolidating. Returns suggestions only; the caller applies them on approval.\n */\nexport function computeCurationProposals(skills: PromotedSkillInfo[], opts: CuratorOptions): CurationProposals {\n\tconst staleMs = opts.staleDays * 86_400_000;\n\tconst archive: CurationProposals[\"archive\"] = [];\n\tfor (const s of skills) {\n\t\t// \"Stale\" = never recently used AND not freshly promoted: measure age from the most recent of\n\t\t// last-use / creation so a brand-new skill isn't archived before it has had a chance to be used.\n\t\tconst lastSeen = Math.max(s.lastUsedMs, s.createdMs);\n\t\tconst ageMs = opts.now - lastSeen;\n\t\tif (ageMs > staleMs) {\n\t\t\tconst days = Math.floor(ageMs / 86_400_000);\n\t\t\tarchive.push({\n\t\t\t\tname: s.name,\n\t\t\t\treason: s.useCount === 0 ? `never used, ${days}d old` : `unused for ${days}d (${s.useCount} total uses)`,\n\t\t\t});\n\t\t}\n\t}\n\n\tconst consolidate: CurationProposals[\"consolidate\"] = [];\n\tconst archiving = new Set(archive.map((a) => a.name));\n\tfor (let i = 0; i < skills.length; i++) {\n\t\tfor (let j = i + 1; j < skills.length; j++) {\n\t\t\tconst a = skills[i];\n\t\t\tconst b = skills[j];\n\t\t\t// Don't propose consolidating something already proposed for archival.\n\t\t\tif (archiving.has(a.name) || archiving.has(b.name)) continue;\n\t\t\tconst overlap = jaccard(a.keywords, b.keywords);\n\t\t\tif (overlap >= opts.overlapThreshold) {\n\t\t\t\tconsolidate.push({ names: [a.name, b.name], overlap });\n\t\t\t}\n\t\t}\n\t}\n\treturn { archive, consolidate };\n}\n\ninterface UsageRecord {\n\tlastUsedMs: number;\n\tuseCount: number;\n}\ntype UsageMap = Record<string, UsageRecord>;\n\n/** Cap on how much of a skill body feeds keyword extraction (keeps overlap detection cheap). */\nconst KEYWORD_SOURCE_CAP = 4000;\n\n/**\n * Filesystem layer over {@link computeCurationProposals}: reads promoted SKILL.md files + the usage\n * sidecar, and archives/restores skills non-destructively. The current time is injected so callers (and\n * tests) control \"now\".\n */\nexport class SkillCurator {\n\tprivate readonly skillsDir: string;\n\tprivate readonly archiveDir: string;\n\tprivate readonly usageFile: string;\n\n\tconstructor(skillsDir: string) {\n\t\tthis.skillsDir = skillsDir;\n\t\tthis.archiveDir = join(skillsDir, \".archive\");\n\t\tthis.usageFile = join(skillsDir, \".usage.json\");\n\t}\n\n\t/**\n\t * Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort.\n\t * Load-mutate-write runs under a single exclusive lock so two concurrent uses (e.g. two sessions\n\t * loading the same skill around the same time) can't both read the old usage map and drop a count.\n\t */\n\trecordUse(name: string, now: number): void {\n\t\ttry {\n\t\t\twithFileLockSync(this.usageFile, () => {\n\t\t\t\tconst usage = this.loadUsage();\n\t\t\t\tconst prev = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\t\tusage[name] = { lastUsedMs: now, useCount: prev.useCount + 1 };\n\t\t\t\twriteFileAtomicSync(this.usageFile, JSON.stringify(usage, null, 2));\n\t\t\t});\n\t\t} catch {\n\t\t\t// usage tracking must never disrupt a turn\n\t\t}\n\t}\n\n\t/** Build the proposals from the current promoted-skill corpus. */\n\tproposeCuration(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): CurationProposals {\n\t\tconst skills = this.loadPromotedSkills();\n\t\treturn computeCurationProposals(skills, {\n\t\t\tnow,\n\t\t\tstaleDays: options.staleDays ?? DEFAULT_CURATOR_OPTIONS.staleDays,\n\t\t\toverlapThreshold: options.overlapThreshold ?? DEFAULT_CURATOR_OPTIONS.overlapThreshold,\n\t\t});\n\t}\n\n\t/**\n\t * Auto-archive every stale promoted skill in ONE locked batch (#32 default-on). The lock serializes\n\t * curation across sessions sharing this `agentDir` so a concurrent session can't archive a folder\n\t * mid-rename (agy's race mitigation). Returns the names archived (for the host to announce). Never\n\t * throws; on lock contention it simply does nothing this run.\n\t */\n\tasync autoArchiveStale(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): Promise<string[]> {\n\t\tif (!existsSync(this.skillsDir)) return [];\n\t\ttry {\n\t\t\treturn await withFileLock(\n\t\t\t\tthis.skillsDir,\n\t\t\t\t() => {\n\t\t\t\t\tconst archived: string[] = [];\n\t\t\t\t\tfor (const a of this.proposeCuration(now, options).archive) {\n\t\t\t\t\t\tif (this.archiveSkill(a.name)) archived.push(a.name);\n\t\t\t\t\t}\n\t\t\t\t\treturn archived;\n\t\t\t\t},\n\t\t\t\t{ retries: 2 },\n\t\t\t);\n\t\t} catch {\n\t\t\treturn []; // another session holds the lock, or fs error — skip this run\n\t\t}\n\t}\n\n\t/** Move a promoted skill into `.archive/` (restorable). Returns true if archived. */\n\tarchiveSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || !this.isPromoted(name)) return false;\n\t\t\tmkdirSync(this.archiveDir, { recursive: true });\n\t\t\trenameSync(from, join(this.archiveDir, name));\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Restore an archived skill back into the active skills dir. Returns true if restored. */\n\trestoreSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.archiveDir, name);\n\t\t\tconst to = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || existsSync(to)) return false;\n\t\t\trenameSync(from, to);\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tloadPromotedSkills(): PromotedSkillInfo[] {\n\t\tconst out: PromotedSkillInfo[] = [];\n\t\tlet entries: string[];\n\t\ttry {\n\t\t\tentries = readdirSync(this.skillsDir);\n\t\t} catch {\n\t\t\treturn out;\n\t\t}\n\t\tconst usage = this.loadUsage();\n\t\tfor (const name of entries) {\n\t\t\tif (name.startsWith(\".\")) continue; // skip .archive, .usage.json\n\t\t\tconst file = join(this.skillsDir, name, \"SKILL.md\");\n\t\t\tlet raw: string;\n\t\t\tlet createdMs = 0;\n\t\t\ttry {\n\t\t\t\traw = readFileSync(file, \"utf-8\");\n\t\t\t\tcreatedMs = statSync(file).birthtimeMs || statSync(file).mtimeMs;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!isPromotedFrontmatter(raw)) continue;\n\t\t\tconst u = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tout.push({\n\t\t\t\tname,\n\t\t\t\tcreatedMs,\n\t\t\t\tlastUsedMs: u.lastUsedMs,\n\t\t\t\tuseCount: u.useCount,\n\t\t\t\tkeywords: tokenize(raw.slice(0, KEYWORD_SOURCE_CAP)),\n\t\t\t});\n\t\t}\n\t\treturn out;\n\t}\n\n\tprivate isPromoted(name: string): boolean {\n\t\ttry {\n\t\t\treturn isPromotedFrontmatter(readFileSync(join(this.skillsDir, name, \"SKILL.md\"), \"utf-8\"));\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tprivate loadUsage(): UsageMap {\n\t\ttry {\n\t\t\treturn JSON.parse(readFileSync(this.usageFile, \"utf-8\")) as UsageMap;\n\t\t} catch {\n\t\t\treturn {};\n\t\t}\n\t}\n}\n\n/** True if a SKILL.md's YAML frontmatter declares `promoted: true` (reflection-generated). */\nexport function isPromotedFrontmatter(content: string): boolean {\n\tconst fm = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n\tif (!fm) return false;\n\treturn /^\\s*promoted\\s*:\\s*true\\s*$/im.test(fm[1]);\n}\n"]}
+{"version":3,"file":"skill-curator.d.ts","sourceRoot":"","sources":["../../../src/core/learning/skill-curator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC9B,kGAAkG;IAClG,SAAS,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,gBAAgB,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,eAAO,MAAM,uBAAuB,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,CAG/D,CAAC;AAEF,MAAM,WAAW,iBAAiB;IACjC,+EAA+E;IAC/E,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,sGAAsG;IACtG,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,iBAAiB,CAgC7G;AAWD;;;;GAIG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,YAAY,SAAS,EAAE,MAAM,EAI5B;IAED;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAWzC;IAED,kEAAkE;IAClE,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,iBAAiB,CAOlG;IAED;;;;;OAKG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,CAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBzG;IAED,qFAAqF;IACrF,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,2FAA2F;IAC3F,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUlC;IAED,kBAAkB,IAAI,iBAAiB,EAAE,CA+BxC;IAED,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,SAAS;CAOjB;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI9D"}

package/dist/core/learning/skill-curator.js

@@ -60,9 +60,6 @@ const KEYWORD_SOURCE_CAP = 4000;
  * tests) control "now".
  */
 export class SkillCurator {
-    skillsDir;
-    archiveDir;
-    usageFile;
     constructor(skillsDir) {
         this.skillsDir = skillsDir;
         this.archiveDir = join(skillsDir, ".archive");

package/dist/core/learning/skill-curator.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-curator.js","sourceRoot":"","sources":["../../../src/core/learning/skill-curator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Skill curator (Hermes-parity #32). Reflection (R7) promotes recurring procedures into SKILL.md files;\n * without curation they accumulate forever, bloating tool/context and raising per-turn cost. The curator\n * tracks usage of PROMOTED skills (frontmatter `promoted: true`) and PROPOSES — never auto-applies —\n * archiving stale ones and consolidating overlapping ones. Hand-authored user skills are never touched.\n *\n * Design (locked with agy): propose-only, session-start + idle triggers (not per-turn), restorable\n * archive (non-destructive), and consolidation is a flagged suggestion (never an auto-merge).\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { jaccard, tokenize } from \"../tools/skill-audit.ts\";\nimport { withFileLock, withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\n\n/** Per-promoted-skill signal the proposal logic reasons over. Pure data — no I/O. */\nexport interface PromotedSkillInfo {\n\tname: string;\n\t/** When the skill file was created (ms epoch); guards a freshly-promoted skill from instant archival. */\n\tcreatedMs: number;\n\t/** Last time the skill was loaded/used (ms epoch); 0 if never used. */\n\tlastUsedMs: number;\n\tuseCount: number;\n\t/** Tokens from name+description+body, for overlap detection. */\n\tkeywords: string[];\n}\n\nexport interface CuratorOptions {\n\t/** A promoted skill unused and older than this many days is proposed for archival. Default 30. */\n\tstaleDays: number;\n\t/** Token-Jaccard ≥ this between two promoted skills flags them for consolidation. Default 0.5. */\n\toverlapThreshold: number;\n\t/** Current time (ms epoch); injected so the proposal logic stays pure/testable. */\n\tnow: number;\n}\n\nexport const DEFAULT_CURATOR_OPTIONS: Omit<CuratorOptions, \"now\"> = {\n\tstaleDays: 30,\n\toverlapThreshold: 0.5,\n};\n\nexport interface CurationProposals {\n\t/** Promoted skills proposed for (restorable) archival, with a human reason. */\n\tarchive: Array<{ name: string; reason: string }>;\n\t/** Pairs of promoted skills that overlap enough to consider merging (flag only, never auto-merge). */\n\tconsolidate: Array<{ names: [string, string]; overlap: number }>;\n}\n\n/**\n * Pure proposal logic: decide which promoted skills to PROPOSE archiving (stale + unused) and which pairs\n * overlap enough to PROPOSE consolidating. Returns suggestions only; the caller applies them on approval.\n */\nexport function computeCurationProposals(skills: PromotedSkillInfo[], opts: CuratorOptions): CurationProposals {\n\tconst staleMs = opts.staleDays * 86_400_000;\n\tconst archive: CurationProposals[\"archive\"] = [];\n\tfor (const s of skills) {\n\t\t// \"Stale\" = never recently used AND not freshly promoted: measure age from the most recent of\n\t\t// last-use / creation so a brand-new skill isn't archived before it has had a chance to be used.\n\t\tconst lastSeen = Math.max(s.lastUsedMs, s.createdMs);\n\t\tconst ageMs = opts.now - lastSeen;\n\t\tif (ageMs > staleMs) {\n\t\t\tconst days = Math.floor(ageMs / 86_400_000);\n\t\t\tarchive.push({\n\t\t\t\tname: s.name,\n\t\t\t\treason: s.useCount === 0 ? `never used, ${days}d old` : `unused for ${days}d (${s.useCount} total uses)`,\n\t\t\t});\n\t\t}\n\t}\n\n\tconst consolidate: CurationProposals[\"consolidate\"] = [];\n\tconst archiving = new Set(archive.map((a) => a.name));\n\tfor (let i = 0; i < skills.length; i++) {\n\t\tfor (let j = i + 1; j < skills.length; j++) {\n\t\t\tconst a = skills[i];\n\t\t\tconst b = skills[j];\n\t\t\t// Don't propose consolidating something already proposed for archival.\n\t\t\tif (archiving.has(a.name) || archiving.has(b.name)) continue;\n\t\t\tconst overlap = jaccard(a.keywords, b.keywords);\n\t\t\tif (overlap >= opts.overlapThreshold) {\n\t\t\t\tconsolidate.push({ names: [a.name, b.name], overlap });\n\t\t\t}\n\t\t}\n\t}\n\treturn { archive, consolidate };\n}\n\ninterface UsageRecord {\n\tlastUsedMs: number;\n\tuseCount: number;\n}\ntype UsageMap = Record<string, UsageRecord>;\n\n/** Cap on how much of a skill body feeds keyword extraction (keeps overlap detection cheap). */\nconst KEYWORD_SOURCE_CAP = 4000;\n\n/**\n * Filesystem layer over {@link computeCurationProposals}: reads promoted SKILL.md files + the usage\n * sidecar, and archives/restores skills non-destructively. The current time is injected so callers (and\n * tests) control \"now\".\n */\nexport class SkillCurator {\n\tprivate readonly skillsDir: string;\n\tprivate readonly archiveDir: string;\n\tprivate readonly usageFile: string;\n\n\tconstructor(skillsDir: string) {\n\t\tthis.skillsDir = skillsDir;\n\t\tthis.archiveDir = join(skillsDir, \".archive\");\n\t\tthis.usageFile = join(skillsDir, \".usage.json\");\n\t}\n\n\t/**\n\t * Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort.\n\t * Load-mutate-write runs under a single exclusive lock so two concurrent uses (e.g. two sessions\n\t * loading the same skill around the same time) can't both read the old usage map and drop a count.\n\t */\n\trecordUse(name: string, now: number): void {\n\t\ttry {\n\t\t\twithFileLockSync(this.usageFile, () => {\n\t\t\t\tconst usage = this.loadUsage();\n\t\t\t\tconst prev = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\t\tusage[name] = { lastUsedMs: now, useCount: prev.useCount + 1 };\n\t\t\t\twriteFileAtomicSync(this.usageFile, JSON.stringify(usage, null, 2));\n\t\t\t});\n\t\t} catch {\n\t\t\t// usage tracking must never disrupt a turn\n\t\t}\n\t}\n\n\t/** Build the proposals from the current promoted-skill corpus. */\n\tproposeCuration(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): CurationProposals {\n\t\tconst skills = this.loadPromotedSkills();\n\t\treturn computeCurationProposals(skills, {\n\t\t\tnow,\n\t\t\tstaleDays: options.staleDays ?? DEFAULT_CURATOR_OPTIONS.staleDays,\n\t\t\toverlapThreshold: options.overlapThreshold ?? DEFAULT_CURATOR_OPTIONS.overlapThreshold,\n\t\t});\n\t}\n\n\t/**\n\t * Auto-archive every stale promoted skill in ONE locked batch (#32 default-on). The lock serializes\n\t * curation across sessions sharing this `agentDir` so a concurrent session can't archive a folder\n\t * mid-rename (agy's race mitigation). Returns the names archived (for the host to announce). Never\n\t * throws; on lock contention it simply does nothing this run.\n\t */\n\tasync autoArchiveStale(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): Promise<string[]> {\n\t\tif (!existsSync(this.skillsDir)) return [];\n\t\ttry {\n\t\t\treturn await withFileLock(\n\t\t\t\tthis.skillsDir,\n\t\t\t\t() => {\n\t\t\t\t\tconst archived: string[] = [];\n\t\t\t\t\tfor (const a of this.proposeCuration(now, options).archive) {\n\t\t\t\t\t\tif (this.archiveSkill(a.name)) archived.push(a.name);\n\t\t\t\t\t}\n\t\t\t\t\treturn archived;\n\t\t\t\t},\n\t\t\t\t{ retries: 2 },\n\t\t\t);\n\t\t} catch {\n\t\t\treturn []; // another session holds the lock, or fs error — skip this run\n\t\t}\n\t}\n\n\t/** Move a promoted skill into `.archive/` (restorable). Returns true if archived. */\n\tarchiveSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || !this.isPromoted(name)) return false;\n\t\t\tmkdirSync(this.archiveDir, { recursive: true });\n\t\t\trenameSync(from, join(this.archiveDir, name));\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Restore an archived skill back into the active skills dir. Returns true if restored. */\n\trestoreSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.archiveDir, name);\n\t\t\tconst to = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || existsSync(to)) return false;\n\t\t\trenameSync(from, to);\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tloadPromotedSkills(): PromotedSkillInfo[] {\n\t\tconst out: PromotedSkillInfo[] = [];\n\t\tlet entries: string[];\n\t\ttry {\n\t\t\tentries = readdirSync(this.skillsDir);\n\t\t} catch {\n\t\t\treturn out;\n\t\t}\n\t\tconst usage = this.loadUsage();\n\t\tfor (const name of entries) {\n\t\t\tif (name.startsWith(\".\")) continue; // skip .archive, .usage.json\n\t\t\tconst file = join(this.skillsDir, name, \"SKILL.md\");\n\t\t\tlet raw: string;\n\t\t\tlet createdMs = 0;\n\t\t\ttry {\n\t\t\t\traw = readFileSync(file, \"utf-8\");\n\t\t\t\tcreatedMs = statSync(file).birthtimeMs || statSync(file).mtimeMs;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!isPromotedFrontmatter(raw)) continue;\n\t\t\tconst u = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tout.push({\n\t\t\t\tname,\n\t\t\t\tcreatedMs,\n\t\t\t\tlastUsedMs: u.lastUsedMs,\n\t\t\t\tuseCount: u.useCount,\n\t\t\t\tkeywords: tokenize(raw.slice(0, KEYWORD_SOURCE_CAP)),\n\t\t\t});\n\t\t}\n\t\treturn out;\n\t}\n\n\tprivate isPromoted(name: string): boolean {\n\t\ttry {\n\t\t\treturn isPromotedFrontmatter(readFileSync(join(this.skillsDir, name, \"SKILL.md\"), \"utf-8\"));\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tprivate loadUsage(): UsageMap {\n\t\ttry {\n\t\t\treturn JSON.parse(readFileSync(this.usageFile, \"utf-8\")) as UsageMap;\n\t\t} catch {\n\t\t\treturn {};\n\t\t}\n\t}\n}\n\n/** True if a SKILL.md's YAML frontmatter declares `promoted: true` (reflection-generated). */\nexport function isPromotedFrontmatter(content: string): boolean {\n\tconst fm = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n\tif (!fm) return false;\n\treturn /^\\s*promoted\\s*:\\s*true\\s*$/im.test(fm[1]);\n}\n"]}
+{"version":3,"file":"skill-curator.js","sourceRoot":"","sources":["../../../src/core/learning/skill-curator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Skill curator (Hermes-parity #32). Reflection (R7) promotes recurring procedures into SKILL.md files;\n * without curation they accumulate forever, bloating tool/context and raising per-turn cost. The curator\n * tracks usage of PROMOTED skills (frontmatter `promoted: true`) and PROPOSES — never auto-applies —\n * archiving stale ones and consolidating overlapping ones. Hand-authored user skills are never touched.\n *\n * Design (locked with agy): propose-only, session-start + idle triggers (not per-turn), restorable\n * archive (non-destructive), and consolidation is a flagged suggestion (never an auto-merge).\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { jaccard, tokenize } from \"../tools/skill-audit.ts\";\nimport { withFileLock, withFileLockSync, writeFileAtomicSync } from \"../util/atomic-file.ts\";\n\n/** Per-promoted-skill signal the proposal logic reasons over. Pure data — no I/O. */\nexport interface PromotedSkillInfo {\n\tname: string;\n\t/** When the skill file was created (ms epoch); guards a freshly-promoted skill from instant archival. */\n\tcreatedMs: number;\n\t/** Last time the skill was loaded/used (ms epoch); 0 if never used. */\n\tlastUsedMs: number;\n\tuseCount: number;\n\t/** Tokens from name+description+body, for overlap detection. */\n\tkeywords: string[];\n}\n\nexport interface CuratorOptions {\n\t/** A promoted skill unused and older than this many days is proposed for archival. Default 30. */\n\tstaleDays: number;\n\t/** Token-Jaccard ≥ this between two promoted skills flags them for consolidation. Default 0.5. */\n\toverlapThreshold: number;\n\t/** Current time (ms epoch); injected so the proposal logic stays pure/testable. */\n\tnow: number;\n}\n\nexport const DEFAULT_CURATOR_OPTIONS: Omit<CuratorOptions, \"now\"> = {\n\tstaleDays: 30,\n\toverlapThreshold: 0.5,\n};\n\nexport interface CurationProposals {\n\t/** Promoted skills proposed for (restorable) archival, with a human reason. */\n\tarchive: Array<{ name: string; reason: string }>;\n\t/** Pairs of promoted skills that overlap enough to consider merging (flag only, never auto-merge). */\n\tconsolidate: Array<{ names: [string, string]; overlap: number }>;\n}\n\n/**\n * Pure proposal logic: decide which promoted skills to PROPOSE archiving (stale + unused) and which pairs\n * overlap enough to PROPOSE consolidating. Returns suggestions only; the caller applies them on approval.\n */\nexport function computeCurationProposals(skills: PromotedSkillInfo[], opts: CuratorOptions): CurationProposals {\n\tconst staleMs = opts.staleDays * 86_400_000;\n\tconst archive: CurationProposals[\"archive\"] = [];\n\tfor (const s of skills) {\n\t\t// \"Stale\" = never recently used AND not freshly promoted: measure age from the most recent of\n\t\t// last-use / creation so a brand-new skill isn't archived before it has had a chance to be used.\n\t\tconst lastSeen = Math.max(s.lastUsedMs, s.createdMs);\n\t\tconst ageMs = opts.now - lastSeen;\n\t\tif (ageMs > staleMs) {\n\t\t\tconst days = Math.floor(ageMs / 86_400_000);\n\t\t\tarchive.push({\n\t\t\t\tname: s.name,\n\t\t\t\treason: s.useCount === 0 ? `never used, ${days}d old` : `unused for ${days}d (${s.useCount} total uses)`,\n\t\t\t});\n\t\t}\n\t}\n\n\tconst consolidate: CurationProposals[\"consolidate\"] = [];\n\tconst archiving = new Set(archive.map((a) => a.name));\n\tfor (let i = 0; i < skills.length; i++) {\n\t\tfor (let j = i + 1; j < skills.length; j++) {\n\t\t\tconst a = skills[i];\n\t\t\tconst b = skills[j];\n\t\t\t// Don't propose consolidating something already proposed for archival.\n\t\t\tif (archiving.has(a.name) || archiving.has(b.name)) continue;\n\t\t\tconst overlap = jaccard(a.keywords, b.keywords);\n\t\t\tif (overlap >= opts.overlapThreshold) {\n\t\t\t\tconsolidate.push({ names: [a.name, b.name], overlap });\n\t\t\t}\n\t\t}\n\t}\n\treturn { archive, consolidate };\n}\n\ninterface UsageRecord {\n\tlastUsedMs: number;\n\tuseCount: number;\n}\ntype UsageMap = Record<string, UsageRecord>;\n\n/** Cap on how much of a skill body feeds keyword extraction (keeps overlap detection cheap). */\nconst KEYWORD_SOURCE_CAP = 4000;\n\n/**\n * Filesystem layer over {@link computeCurationProposals}: reads promoted SKILL.md files + the usage\n * sidecar, and archives/restores skills non-destructively. The current time is injected so callers (and\n * tests) control \"now\".\n */\nexport class SkillCurator {\n\tprivate readonly skillsDir: string;\n\tprivate readonly archiveDir: string;\n\tprivate readonly usageFile: string;\n\n\tconstructor(skillsDir: string) {\n\t\tthis.skillsDir = skillsDir;\n\t\tthis.archiveDir = join(skillsDir, \".archive\");\n\t\tthis.usageFile = join(skillsDir, \".usage.json\");\n\t}\n\n\t/**\n\t * Record that a promoted skill was loaded/used (bumps count + last-used). Best-effort.\n\t * Load-mutate-write runs under a single exclusive lock so two concurrent uses (e.g. two sessions\n\t * loading the same skill around the same time) can't both read the old usage map and drop a count.\n\t */\n\trecordUse(name: string, now: number): void {\n\t\ttry {\n\t\t\twithFileLockSync(this.usageFile, () => {\n\t\t\t\tconst usage = this.loadUsage();\n\t\t\t\tconst prev = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\t\tusage[name] = { lastUsedMs: now, useCount: prev.useCount + 1 };\n\t\t\t\twriteFileAtomicSync(this.usageFile, JSON.stringify(usage, null, 2));\n\t\t\t});\n\t\t} catch {\n\t\t\t// usage tracking must never disrupt a turn\n\t\t}\n\t}\n\n\t/** Build the proposals from the current promoted-skill corpus. */\n\tproposeCuration(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): CurationProposals {\n\t\tconst skills = this.loadPromotedSkills();\n\t\treturn computeCurationProposals(skills, {\n\t\t\tnow,\n\t\t\tstaleDays: options.staleDays ?? DEFAULT_CURATOR_OPTIONS.staleDays,\n\t\t\toverlapThreshold: options.overlapThreshold ?? DEFAULT_CURATOR_OPTIONS.overlapThreshold,\n\t\t});\n\t}\n\n\t/**\n\t * Auto-archive every stale promoted skill in ONE locked batch (#32 default-on). The lock serializes\n\t * curation across sessions sharing this `agentDir` so a concurrent session can't archive a folder\n\t * mid-rename (agy's race mitigation). Returns the names archived (for the host to announce). Never\n\t * throws; on lock contention it simply does nothing this run.\n\t */\n\tasync autoArchiveStale(now: number, options: Partial<Omit<CuratorOptions, \"now\">> = {}): Promise<string[]> {\n\t\tif (!existsSync(this.skillsDir)) return [];\n\t\ttry {\n\t\t\treturn await withFileLock(\n\t\t\t\tthis.skillsDir,\n\t\t\t\t() => {\n\t\t\t\t\tconst archived: string[] = [];\n\t\t\t\t\tfor (const a of this.proposeCuration(now, options).archive) {\n\t\t\t\t\t\tif (this.archiveSkill(a.name)) archived.push(a.name);\n\t\t\t\t\t}\n\t\t\t\t\treturn archived;\n\t\t\t\t},\n\t\t\t\t{ retries: 2 },\n\t\t\t);\n\t\t} catch {\n\t\t\treturn []; // another session holds the lock, or fs error — skip this run\n\t\t}\n\t}\n\n\t/** Move a promoted skill into `.archive/` (restorable). Returns true if archived. */\n\tarchiveSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || !this.isPromoted(name)) return false;\n\t\t\tmkdirSync(this.archiveDir, { recursive: true });\n\t\t\trenameSync(from, join(this.archiveDir, name));\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Restore an archived skill back into the active skills dir. Returns true if restored. */\n\trestoreSkill(name: string): boolean {\n\t\ttry {\n\t\t\tconst from = join(this.archiveDir, name);\n\t\t\tconst to = join(this.skillsDir, name);\n\t\t\tif (!existsSync(join(from, \"SKILL.md\")) || existsSync(to)) return false;\n\t\t\trenameSync(from, to);\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tloadPromotedSkills(): PromotedSkillInfo[] {\n\t\tconst out: PromotedSkillInfo[] = [];\n\t\tlet entries: string[];\n\t\ttry {\n\t\t\tentries = readdirSync(this.skillsDir);\n\t\t} catch {\n\t\t\treturn out;\n\t\t}\n\t\tconst usage = this.loadUsage();\n\t\tfor (const name of entries) {\n\t\t\tif (name.startsWith(\".\")) continue; // skip .archive, .usage.json\n\t\t\tconst file = join(this.skillsDir, name, \"SKILL.md\");\n\t\t\tlet raw: string;\n\t\t\tlet createdMs = 0;\n\t\t\ttry {\n\t\t\t\traw = readFileSync(file, \"utf-8\");\n\t\t\t\tcreatedMs = statSync(file).birthtimeMs || statSync(file).mtimeMs;\n\t\t\t} catch {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!isPromotedFrontmatter(raw)) continue;\n\t\t\tconst u = usage[name] ?? { lastUsedMs: 0, useCount: 0 };\n\t\t\tout.push({\n\t\t\t\tname,\n\t\t\t\tcreatedMs,\n\t\t\t\tlastUsedMs: u.lastUsedMs,\n\t\t\t\tuseCount: u.useCount,\n\t\t\t\tkeywords: tokenize(raw.slice(0, KEYWORD_SOURCE_CAP)),\n\t\t\t});\n\t\t}\n\t\treturn out;\n\t}\n\n\tprivate isPromoted(name: string): boolean {\n\t\ttry {\n\t\t\treturn isPromotedFrontmatter(readFileSync(join(this.skillsDir, name, \"SKILL.md\"), \"utf-8\"));\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\tprivate loadUsage(): UsageMap {\n\t\ttry {\n\t\t\treturn JSON.parse(readFileSync(this.usageFile, \"utf-8\")) as UsageMap;\n\t\t} catch {\n\t\t\treturn {};\n\t\t}\n\t}\n}\n\n/** True if a SKILL.md's YAML frontmatter declares `promoted: true` (reflection-generated). */\nexport function isPromotedFrontmatter(content: string): boolean {\n\tconst fm = content.match(/^---\\n([\\s\\S]*?)\\n---/);\n\tif (!fm) return false;\n\treturn /^\\s*promoted\\s*:\\s*true\\s*$/im.test(fm[1]);\n}\n"]}

package/dist/core/local-runtime-controller.d.ts

@@ -77,7 +77,16 @@ export declare class LocalRuntimeController {
      * see {@link isPiManagedPrismLlamaCppModel}, which never matches a user's own hand-configured
      * `llama-cpp` entry such as the built-in `llama-cpp/local` catalog model). */
     private isManagedLocalModel;
+    /** Three-way readiness dispatch shared by ensureIsolatedModelReady/ensureForegroundModelReady/
+     * ensureRouteModelReady — one place to add a new managed-local kind instead of tripling a ternary. */
     private ensureManagedLocalReadiness;
+    /** Consent-gated install dispatch, paired with {@link ensureManagedLocalReadiness}. Prism
+     * llama.cpp has no consent step here: unlike Ollama's #31 first-run "install the binary?" and
+     * Transformers' "install the runtime?" prompts (which handle a runtime that was NEVER installed),
+     * a prism model only reaches this gate after a prior `/models add` already installed the runtime
+     * and the curated-menu pick already WAS the consent (same doctrine as the Transformers
+     * precedent) — a later self-heal (re-download a missing file, restart a dead server) is
+     * maintaining an install the user already approved, not a fresh one needing to be asked again. */
     private maybeInstallManagedLocalOnConsent;
     /**
      * ALWAYS scoped to both the server AND the exact model — never bare `serverUrl`. A single Ollama
@@ -91,6 +100,8 @@ export declare class LocalRuntimeController {
      */
     private confirmationKey;
     private invalidateIfLastCallFailed;
+    private unconfirmedKey;
+    private ensureResidentWithAdapter;
     private ensureOllamaResident;
     private ensureTransformersResident;
     private createResidencyArbiter;
@@ -122,7 +133,35 @@ export declare class LocalRuntimeController {
         reason: string;
         installGuide?: string[];
     }>;
+    /**
+     * Readiness gate for a pi-registered prism llama.cpp model (Bonsai-27B) — "usable when needed",
+     * not "served once at install time": healthy at its registered baseUrl -> proceed (no downloads,
+     * no spawn); not healthy -> re-verify BOTH GGUF files exist on disk, re-downloading any missing
+     * one, then serve with the vision projector ALWAYS attached (see
+     * {@link ensurePrismModelFilesThenServe} — the sole path allowed to call `runtime.serve()` for
+     * this model) -> proceed; any stage fails -> the turn fails with that stage's error and
+     * llama-server is never spawned half-configured. No consent dialog here (contrast
+     * maybeInstallOllamaOnConsent/maybeInstallTransformersOnConsent) — see
+     * maybeInstallManagedLocalOnConsent's doc comment for why. Reuses the model's already-registered
+     * `contextWindow` for a re-serve rather than re-deriving from current host RAM, so a restarted
+     * server can never end up with a different served context than the rest of the session (e.g.
+     * compaction) already assumes.
+     */
     private ensurePrismLlamaCppModelReady;
+    /**
+     * #31: the ONE case a routed local model's unreadiness can be fixed automatically is a missing
+     * ollama binary — an unreachable server can't be helped by installing, so that reason is left to
+     * the graceful-fallback warning below unchanged. Only offered when there's an interactive UI to
+     * ask through: headless/RPC/print sessions have no UI context and fall straight through, same as
+     * declining or timing out (both resolve confirm() to false). Reverses "pi never runs installers
+     * itself" specifically for this one path — the user is asked first, the download is pi's own
+     * (never curl|sh), and it lands in pi's own runtimes dir (see OllamaRuntime.installManaged).
+     *
+     * Pauses/resumes the routing working-indicator around the confirm dialog itself (re-emitting
+     * routing_end/routing_start — both already idempotent, see interactive-mode.ts's handlers) so an
+     * animated spinner doesn't fight a dialog the user is trying to read and answer; the indicator
+     * comes back for the download/extract that follows a "yes", which is genuine processing feedback.
+     */
     private maybeInstallOllamaOnConsent;
     private maybeInstallTransformersOnConsent;
     /**

package/dist/core/local-runtime-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-runtime-controller.d.ts","sourceRoot":"","sources":["../../src/core/local-runtime-controller.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Local-runtime (Ollama) lifecycle controller.\n *\n * Extracted verbatim from agent-session.ts (god-file decomposition). Owns the cached, per-server\n * {@link OllamaRuntime} instances, the \"confirmed up this session\" flag, and the router's readiness\n * gate for a turn routed to a local (`ollama`) model — including the #31 install-on-consent flow and\n * the #27 graceful tier-escalation fallback. Takes narrow deps (agent dir, a last-assistant-message\n * accessor, the session's UI context/event emitter, and the router's own tier resolver) rather than\n * the whole AgentSession.\n */\n\nimport { totalmem } from \"node:os\";\nimport type { Api, AssistantMessage, Model } from \"@caupulican/pi-ai\";\nimport type { AgentSessionEvent } from \"./agent-session-contracts.ts\";\nimport type { RouteDecision } from \"./autonomy/contracts.ts\";\nimport type { ExtensionUIContext } from \"./extensions/index.ts\";\nimport { type PrismLlamaCppDeps, PrismLlamaCppRuntime } from \"./models/llamacpp-runtime.ts\";\nimport { HF_TRANSFORMERS_PROVIDER, OLLAMA_PROVIDER } from \"./models/local-registration.ts\";\nimport {\n\ttype LocalRuntimeDeps,\n\tOllamaRuntime,\n\tresolveTransformersBaseUrl,\n\tTransformersRuntime,\n} from \"./models/local-runtime.ts\";\nimport { matchesInstalledLocalModel } from \"./models/model-ref.ts\";\nimport {\n\tensurePrismModelFilesThenServe,\n\tisPiManagedPrismLlamaCppModel,\n\tisPrismLlamaCppServerHealthy,\n\tPRISM_LLAMACPP_DESCRIPTORS,\n\tPRISM_LLAMACPP_SERVE_PORT,\n} from \"./models/prism-llamacpp-lifecycle.ts\";\nimport {\n\tOllamaRuntimeResidencyAdapter,\n\ttype RuntimeEvictionRecord,\n\ttype RuntimeResidencyAdapter,\n\tRuntimeResidencyArbiter,\n\tTransformersRuntimeResidencyAdapter,\n} from \"./models/runtime-arbiter.ts\";\n\n/** User-facing router tiers in ascending order — \"learning\" is never selected for a user turn, so\n * it has no place in the escalation ladder (#27's ensureRouteModelReady walks this forward only). */\nconst MODEL_ROUTER_TIER_ORDER: readonly (\"cheap\" | \"medium\" | \"expensive\")[] = [\"cheap\", \"medium\", \"expensive\"];\n\n/** How long the #31 \"install ollama now?\" confirm waits before auto-dismissing (same as a \"No\") —\n * long enough to read and decide, short enough that an unattended session doesn't hang a turn on it. */\nconst OLLAMA_INSTALL_CONFIRM_TIMEOUT_MS = 30_000;\n\nfunction parseWrongOllamaStoreReason(\n\treason: string,\n): { activePath: string; modelCount: number; ownedPath: string } | undefined {\n\tif (!reason.startsWith(\"wrong_store:\")) return undefined;\n\tconst parts = reason.slice(\"wrong_store:\".length).split(\":\");\n\tif (parts.length < 3) return undefined;\n\tconst [activePath, countText, ...ownedPathParts] = parts;\n\tconst modelCount = Number(countText);\n\treturn {\n\t\tactivePath,\n\t\tmodelCount: Number.isFinite(modelCount) ? modelCount : 0,\n\t\townedPath: ownedPathParts.join(\":\"),\n\t};\n}\n\nexport interface LocalRuntimeControllerDeps {\n\t/** Root directory OllamaRuntime instances are scoped under — fixed for the session's lifetime. */\n\tagentDir: string;\n\t/** Test-injectable seams for OllamaRuntime's own fetch/spawn/exists calls; unset in production. */\n\tlocalRuntimeDeps?: LocalRuntimeDeps;\n\t/** Test-injectable seams for PrismLlamaCppRuntime's own fetch/spawn/exists calls; unset in\n\t * production (see {@link getPrismLlamaCppRuntime}). */\n\tprismLlamaCppDeps?: PrismLlamaCppDeps;\n\t/** The session's last assistant message, to detect a just-failed local call and drop a stale\n\t * \"confirmed up\" flag. */\n\tgetLastAssistantMessage(): AssistantMessage | undefined;\n\t/** The session's live interactive UI context, if any — undefined in headless/RPC/print modes. */\n\tgetUIContext(): ExtensionUIContext | undefined;\n\t/** Emits a session event (only ever `warning` / `routing_start` / `routing_end` from this controller). */\n\temit(event: AgentSessionEvent): void;\n\t/** Resolves the model configured for a router tier, respecting configured auth — owned by the\n\t * router itself, not this controller. */\n\tresolveConfiguredTierModel(tier: \"medium\" | \"expensive\"): Model<Api> | undefined;\n\t/** `${provider}/${id}` label for a model, for warning/confirm text. */\n\tformatModel(model: Model<Api>): string;\n}\n\nexport class LocalRuntimeController {\n\t/** Lazy, cached by baseUrl so the router path and any other caller share one instance per server. */\n\tprivate readonly _runtimes = new Map<string, OllamaRuntime>();\n\t/** Lazy, cached by model+baseUrl so the router and `/models` share one sidecar handle per HF model. */\n\tprivate readonly _transformersRuntimes = new Map<string, TransformersRuntime>();\n\t/** Lazy, cached (not baseUrl-keyed like the two above — pi's prism install is a single managed\n\t * instance under agentDir, never an externally-configured server) so `/models add`, `/models\n\t * stop`, `/models remove`, and the readiness gate below all share the SAME instance and can\n\t * reliably reattach to a process this session started (`stop()`/`isRunning()` rely on in-memory\n\t * child-process state). */\n\tprivate _prismLlamaCppRuntime: PrismLlamaCppRuntime | undefined;\n\t/** Server URLs confirmed reachable THIS session — skips the health-check round trip on every\n\t * local-routed turn once warm. Keyed the same way as _runtimes. */\n\tprivate readonly _confirmedUp = new Set<string>();\n\t/** All live runtime adapters participate in one session-wide residency view. */\n\tprivate readonly _residencyAdapters = new Map<string, RuntimeResidencyAdapter>();\n\tprivate readonly _recentEvictions: RuntimeEvictionRecord[] = [];\n\n\tprivate readonly deps: LocalRuntimeControllerDeps;\n\n\tconstructor(deps: LocalRuntimeControllerDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\t/**\n\t * Shared {@link OllamaRuntime} for a given server, lazily created and cached by baseUrl so every\n\t * caller — the router's readiness gate below and any host UI's own model-lifecycle commands\n\t * (e.g. `/models`) — sees and can stop the SAME pi-managed process instead of each tracking its\n\t * own untracked child.\n\t */\n\tgetLocalRuntime(baseUrl?: string): OllamaRuntime {\n\t\tconst key = baseUrl ?? \"default\";\n\t\tlet runtime = this._runtimes.get(key);\n\t\tif (!runtime) {\n\t\t\truntime = new OllamaRuntime({ agentDir: this.deps.agentDir, baseUrl, deps: this.deps.localRuntimeDeps });\n\t\t\tthis._runtimes.set(key, runtime);\n\t\t}\n\t\treturn runtime;\n\t}\n\n\tgetTransformersRuntime(modelId: string, baseUrl?: string): TransformersRuntime {\n\t\tconst resolvedBaseUrl = baseUrl?.replace(/\\/$/, \"\") ?? resolveTransformersBaseUrl(modelId);\n\t\tconst key = this._transformersRuntimeKey(modelId, resolvedBaseUrl);\n\t\tlet runtime = this._transformersRuntimes.get(key);\n\t\tif (!runtime) {\n\t\t\truntime = new TransformersRuntime({\n\t\t\t\tagentDir: this.deps.agentDir,\n\t\t\t\tmodelId,\n\t\t\t\tbaseUrl: resolvedBaseUrl,\n\t\t\t\tdeps: this.deps.localRuntimeDeps,\n\t\t\t});\n\t\t\tthis._transformersRuntimes.set(key, runtime);\n\t\t}\n\t\treturn runtime;\n\t}\n\n\t/**\n\t * Shared {@link PrismLlamaCppRuntime} for pi's own managed prism install — lazily created, cached\n\t * for the controller's lifetime so `/models` (add/stop/remove) and the readiness gate below\n\t * always see and can stop the SAME pi-managed process.\n\t */\n\tgetPrismLlamaCppRuntime(): PrismLlamaCppRuntime {\n\t\tif (!this._prismLlamaCppRuntime) {\n\t\t\tthis._prismLlamaCppRuntime = new PrismLlamaCppRuntime({\n\t\t\t\tagentDir: this.deps.agentDir,\n\t\t\t\tdeps: this.deps.prismLlamaCppDeps,\n\t\t\t});\n\t\t}\n\t\treturn this._prismLlamaCppRuntime;\n\t}\n\n\t/** models.json registers a local model's baseUrl as `<server>/v1` (OpenAI-compat); the runtime's\n\t * own health/boot endpoints are on the Ollama-native server root. */\n\tderiveOllamaServerUrl(modelBaseUrl: string): string {\n\t\treturn modelBaseUrl.replace(/\\/v1\\/?$/, \"\");\n\t}\n\n\tprivate deriveOpenAICompatServerUrl(modelBaseUrl: string): string {\n\t\treturn modelBaseUrl.replace(/\\/v1\\/?$/, \"\");\n\t}\n\n\tprivate isManagedLocalProvider(provider: string): boolean {\n\t\treturn provider === OLLAMA_PROVIDER || provider === HF_TRANSFORMERS_PROVIDER;\n\t}\n\n\t/** Ollama/Transformers (provider-scoped) OR a pi-registered prism llama.cpp model (id-scoped —\n\t * see {@link isPiManagedPrismLlamaCppModel}, which never matches a user's own hand-configured\n\t * `llama-cpp` entry such as the built-in `llama-cpp/local` catalog model). */\n\tprivate isManagedLocalModel(model: Model<Api>): boolean {\n\t\treturn this.isManagedLocalProvider(model.provider) || isPiManagedPrismLlamaCppModel(model);\n\t}\n\n\t/** Three-way readiness dispatch shared by ensureIsolatedModelReady/ensureForegroundModelReady/\n\t * ensureRouteModelReady — one place to add a new managed-local kind instead of tripling a ternary. */\n\tprivate async ensureManagedLocalReadiness(\n\t\tmodel: Model<Api>,\n\t): Promise<{ ready: boolean; reason: string; installGuide?: string[] }> {\n\t\tif (model.provider === OLLAMA_PROVIDER) return this.ensureLocalModelReady(model);\n\t\tif (model.provider === HF_TRANSFORMERS_PROVIDER) return this.ensureTransformersModelReady(model);\n\t\treturn this.ensurePrismLlamaCppModelReady(model);\n\t}\n\n\t/** Consent-gated install dispatch, paired with {@link ensureManagedLocalReadiness}. Prism\n\t * llama.cpp has no consent step here: unlike Ollama's #31 first-run \"install the binary?\" and\n\t * Transformers' \"install the runtime?\" prompts (which handle a runtime that was NEVER installed),\n\t * a prism model only reaches this gate after a prior `/models add` already installed the runtime\n\t * and the curated-menu pick already WAS the consent (same doctrine as the Transformers\n\t * precedent) — a later self-heal (re-download a missing file, restart a dead server) is\n\t * maintaining an install the user already approved, not a fresh one needing to be asked again. */\n\tprivate async maybeInstallManagedLocalOnConsent(\n\t\tmodel: Model<Api>,\n\t\treadiness: { ready: boolean; reason: string; installGuide?: string[] },\n\t): Promise<{ ready: boolean; reason: string; installGuide?: string[]; installAttemptError?: string }> {\n\t\tif (model.provider === OLLAMA_PROVIDER) return this.maybeInstallOllamaOnConsent(model, readiness);\n\t\tif (model.provider === HF_TRANSFORMERS_PROVIDER) return this.maybeInstallTransformersOnConsent(model, readiness);\n\t\treturn readiness;\n\t}\n\n\t/**\n\t * ALWAYS scoped to both the server AND the exact model — never bare `serverUrl`. A single Ollama\n\t * (or prism) server can host several models, and a serverUrl-only key let the FIRST model\n\t * confirmed on a server silently wave through every other model requested on that same server:\n\t * the cache hit at {@link ensureLocalModelReady}/{@link ensurePrismLlamaCppModelReady} short-\n\t * circuits BEFORE the installed-model check and the residency arbiter run, so a genuinely missing\n\t * model surfaced as a raw runtime error instead of `model_missing_on_server`, and residency\n\t * bookkeeping silently skipped a model it never actually admitted. Transformers already had this\n\t * right (one server per model, by construction); this makes every provider consistent.\n\t */\n\tprivate confirmationKey(model: Model<Api>, serverUrl: string): string {\n\t\treturn `${serverUrl}\\0${model.id}`;\n\t}\n\n\tprivate invalidateIfLastCallFailed(model: Model<Api>, serverUrl: string): void {\n\t\tconst lastAssistant = this.deps.getLastAssistantMessage();\n\t\tif (\n\t\t\tlastAssistant?.stopReason === \"error\" &&\n\t\t\tlastAssistant.provider === model.provider &&\n\t\t\tlastAssistant.model === model.id\n\t\t) {\n\t\t\tthis._confirmedUp.delete(this.confirmationKey(model, serverUrl));\n\t\t}\n\t}\n\n\tprivate async ensureOllamaResident(\n\t\tmodel: Model<Api>,\n\t\truntime: OllamaRuntime,\n\t\tknownSizeBytes?: number,\n\t): Promise<{ ok: boolean; reason?: string }> {\n\t\tlet bytes = knownSizeBytes ?? 0;\n\t\tif (knownSizeBytes === undefined) {\n\t\t\ttry {\n\t\t\t\tconst installed = await runtime.list();\n\t\t\t\tbytes = installed.find((entry) => matchesInstalledLocalModel(model.id, entry.name))?.sizeBytes ?? 0;\n\t\t\t} catch {\n\t\t\t\t// Residency is best-effort; a list failure falls back to a zero-byte admission request.\n\t\t\t}\n\t\t}\n\t\tconst serverUrl = this.deriveOllamaServerUrl(model.baseUrl);\n\t\tconst adapterId = `ollama:${serverUrl}`;\n\t\tthis._residencyAdapters.set(adapterId, new OllamaRuntimeResidencyAdapter(adapterId, runtime));\n\t\tconst arbiter = this.createResidencyArbiter();\n\t\ttry {\n\t\t\tconst nowMs = Date.now();\n\t\t\tconst plan = await arbiter.ensureResident(adapterId, {\n\t\t\t\tmodel: model.id,\n\t\t\t\tbytes,\n\t\t\t\trole: \"active\",\n\t\t\t\tpriority: 100,\n\t\t\t\tnowMs,\n\t\t\t\tpinActiveModel: model.id,\n\t\t\t\trecentEvictions: this._recentEvictions,\n\t\t\t\t// Cold Ollama loads can legitimately take several minutes. The actual adaptive stream\n\t\t\t\t// owns that wait; readiness must not front-run it with a 60-second empty generation.\n\t\t\t\tloadModel: false,\n\t\t\t});\n\t\t\tthis.recordEvictions(plan.evict, model.id, nowMs, adapterId);\n\t\t\treturn plan.status === \"fits\" ? { ok: true } : { ok: false, reason: `residency_refused:${plan.reason}` };\n\t\t} catch (error) {\n\t\t\treturn { ok: false, reason: `residency_error:${error instanceof Error ? error.message : String(error)}` };\n\t\t}\n\t}\n\n\tprivate async ensureTransformersResident(\n\t\tmodel: Model<Api>,\n\t\truntime: TransformersRuntime,\n\t): Promise<{ ok: boolean; reason?: string }> {\n\t\tconst serverUrl = this.deriveOpenAICompatServerUrl(model.baseUrl);\n\t\tconst adapterId = `transformers:${model.id}:${serverUrl}`;\n\t\tthis._residencyAdapters.set(adapterId, new TransformersRuntimeResidencyAdapter(adapterId, runtime, model.id, 0));\n\t\tconst arbiter = this.createResidencyArbiter();\n\t\ttry {\n\t\t\tconst nowMs = Date.now();\n\t\t\tconst plan = await arbiter.ensureResident(adapterId, {\n\t\t\t\tmodel: model.id,\n\t\t\t\tbytes: 0,\n\t\t\t\trole: \"active\",\n\t\t\t\tpriority: 100,\n\t\t\t\tnowMs,\n\t\t\t\tpinActiveModel: model.id,\n\t\t\t\trecentEvictions: this._recentEvictions,\n\t\t\t\tloadModel: false,\n\t\t\t});\n\t\t\tthis.recordEvictions(plan.evict, model.id, nowMs, adapterId);\n\t\t\treturn plan.status === \"fits\" ? { ok: true } : { ok: false, reason: `residency_refused:${plan.reason}` };\n\t\t} catch (error) {\n\t\t\treturn { ok: false, reason: `residency_error:${error instanceof Error ? error.message : String(error)}` };\n\t\t}\n\t}\n\n\tprivate createResidencyArbiter(): RuntimeResidencyArbiter {\n\t\treturn new RuntimeResidencyArbiter({\n\t\t\tbudgetBytes: Math.floor(totalmem() * 0.85),\n\t\t\tadapters: [...this._residencyAdapters.values()],\n\t\t});\n\t}\n\n\tprivate recordEvictions(\n\t\tevicted: readonly { adapterId: string; model: string }[],\n\t\tloaded: string,\n\t\tatMs: number,\n\t\tloadedAdapterId: string,\n\t): void {\n\t\tfor (const resident of evicted) {\n\t\t\tthis._recentEvictions.push({\n\t\t\t\tevicted: resident.model,\n\t\t\t\tloaded,\n\t\t\t\tatMs,\n\t\t\t\tevictedAdapterId: resident.adapterId,\n\t\t\t\tloadedAdapterId,\n\t\t\t});\n\t\t}\n\t\tconst cutoff = atMs - 5 * 60_000;\n\t\twhile (this._recentEvictions[0]?.atMs < cutoff) this._recentEvictions.shift();\n\t}\n\n\t/**\n\t * Readiness gate for every isolated/background completion. Unlike the foreground route gate it\n\t * never prompts or changes tiers: lanes either use the configured model or fail visibly.\n\t */\n\tasync ensureIsolatedModelReady(model: Model<Api>): Promise<void> {\n\t\tif (!this.isManagedLocalModel(model)) return;\n\t\tconst readiness = await this.ensureManagedLocalReadiness(model);\n\t\tif (readiness.ready) return;\n\t\tconst guide = readiness.installGuide?.length ? `\\n${readiness.installGuide.join(\"\\n\")}` : \"\";\n\t\tthrow new Error(\n\t\t\t`Managed local model ${this.deps.formatModel(model)} is unavailable for isolated execution (${readiness.reason}).${guide}`,\n\t\t);\n\t}\n\n\t/**\n\t * Readiness gate for a manually selected/default foreground model when no router route owns the\n\t * turn. Interactive sessions may offer the same managed-install consent as routed turns; the\n\t * selected model is never silently replaced.\n\t */\n\tasync ensureForegroundModelReady(model: Model<Api>): Promise<void> {\n\t\tif (!this.isManagedLocalModel(model)) return;\n\t\tlet readiness: {\n\t\t\tready: boolean;\n\t\t\treason: string;\n\t\t\tinstallGuide?: string[];\n\t\t\tinstallAttemptError?: string;\n\t\t} = await this.ensureManagedLocalReadiness(model);\n\t\tif (!readiness.ready) {\n\t\t\treadiness = await this.maybeInstallManagedLocalOnConsent(model, readiness);\n\t\t}\n\t\tif (readiness.ready) return;\n\t\tconst detail = readiness.installAttemptError ?? readiness.installGuide?.join(\"\\n\") ?? readiness.reason;\n\t\tthrow new Error(`Managed local model ${this.deps.formatModel(model)} is unavailable: ${detail}`);\n\t}\n\n\t/**\n\t * Ensure a routed managed-local model is actually reachable before the turn calls it. No-op (and\n\t * free) for non-local/API models. Caches a \"confirmed up this session\" flag per server (and per\n\t * Transformers model) so steady-state routing pays the health-check round trip once; invalidated\n\t * above when a prior local call failed so a dead sidecar gets re-detected instead of trusted.\n\t */\n\tasync ensureLocalModelReady(\n\t\tmodel: Model<Api>,\n\t): Promise<{ ready: boolean; reason: string; installGuide?: string[] }> {\n\t\tif (model.provider !== OLLAMA_PROVIDER) {\n\t\t\treturn { ready: true, reason: \"not_local\" };\n\t\t}\n\t\tconst serverUrl = this.deriveOllamaServerUrl(model.baseUrl);\n\t\tconst confirmedKey = this.confirmationKey(model, serverUrl);\n\t\tthis.invalidateIfLastCallFailed(model, serverUrl);\n\t\tif (this._confirmedUp.has(confirmedKey)) {\n\t\t\treturn { ready: true, reason: \"confirmed_up_cached\" };\n\t\t}\n\t\tconst runtime = this.getLocalRuntime(serverUrl);\n\t\tconst status = await runtime.detect();\n\t\tif (status.serverUp) {\n\t\t\t// Server ownership is not a capability boundary. Reuse a configured user/system server\n\t\t\t// when it exposes the requested model; this preserves its accelerator settings and warm\n\t\t\t// cache instead of forcing a slower duplicate Pi-owned process/store.\n\t\t\tconst installedEntry = status.serverModels.find((entry) => matchesInstalledLocalModel(model.id, entry.name));\n\t\t\tif (!installedEntry) {\n\t\t\t\treturn {\n\t\t\t\t\tready: false,\n\t\t\t\t\treason: `model_missing_on_server:${model.id}:${status.activeStore?.path ?? \"external/unknown\"}`,\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst resident = await this.ensureOllamaResident(model, runtime, installedEntry.sizeBytes);\n\t\t\tif (!resident.ok) return { ready: false, reason: resident.reason ?? \"residency_refused\" };\n\t\t\tthis._confirmedUp.add(confirmedKey);\n\t\t\treturn {\n\t\t\t\tready: true,\n\t\t\t\treason: status.managedByPi ? \"already_running_managed\" : \"already_running_configured_server\",\n\t\t\t};\n\t\t}\n\t\tif (!status.binaryPath) {\n\t\t\treturn { ready: false, reason: \"binary_missing\", installGuide: runtime.installGuide() };\n\t\t}\n\t\tconst started = await runtime.start();\n\t\tif (started.started) {\n\t\t\tlet installedEntry: { name: string; sizeBytes: number } | undefined;\n\t\t\ttry {\n\t\t\t\tconst installed = await runtime.list();\n\t\t\t\tinstalledEntry = installed.find((entry) => matchesInstalledLocalModel(model.id, entry.name));\n\t\t\t} catch (error) {\n\t\t\t\truntime.stop();\n\t\t\t\treturn {\n\t\t\t\t\tready: false,\n\t\t\t\t\treason: `model_list_failed_after_start:${error instanceof Error ? error.message : String(error)}`,\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (!installedEntry) {\n\t\t\t\truntime.stop();\n\t\t\t\treturn { ready: false, reason: `model_missing_on_started_server:${model.id}` };\n\t\t\t}\n\t\t\tconst resident = await this.ensureOllamaResident(model, runtime, installedEntry.sizeBytes);\n\t\t\tif (!resident.ok) {\n\t\t\t\truntime.stop();\n\t\t\t\treturn { ready: false, reason: resident.reason ?? \"residency_refused\" };\n\t\t\t}\n\t\t\tthis._confirmedUp.add(confirmedKey);\n\t\t}\n\t\treturn { ready: started.started, reason: started.reason };\n\t}\n\n\tasync ensureTransformersModelReady(\n\t\tmodel: Model<Api>,\n\t): Promise<{ ready: boolean; reason: string; installGuide?: string[] }> {\n\t\tif (model.provider !== HF_TRANSFORMERS_PROVIDER) {\n\t\t\treturn { ready: true, reason: \"not_transformers\" };\n\t\t}\n\t\tconst serverUrl = this.deriveOpenAICompatServerUrl(model.baseUrl);\n\t\tconst confirmedKey = this.confirmationKey(model, serverUrl);\n\t\tthis.invalidateIfLastCallFailed(model, serverUrl);\n\t\tif (this._confirmedUp.has(confirmedKey)) {\n\t\t\treturn { ready: true, reason: \"confirmed_up_cached\" };\n\t\t}\n\t\tconst runtime = this.getTransformersRuntime(model.id, serverUrl);\n\t\tconst status = await runtime.detect();\n\t\tif (status.serverUp) {\n\t\t\tconst resident = await this.ensureTransformersResident(model, runtime);\n\t\t\tif (!resident.ok) return { ready: false, reason: resident.reason ?? \"residency_refused\" };\n\t\t\tthis._confirmedUp.add(confirmedKey);\n\t\t\treturn { ready: true, reason: \"already_running\" };\n\t\t}\n\t\tif (!status.runtimeInstalled) {\n\t\t\treturn { ready: false, reason: \"runtime_missing\", installGuide: runtime.installGuide() };\n\t\t}\n\t\tconst started = await runtime.start();\n\t\tif (started.started || started.reason === \"already_running\") {\n\t\t\tconst resident = await this.ensureTransformersResident(model, runtime);\n\t\t\tif (!resident.ok) return { ready: false, reason: resident.reason ?? \"residency_refused\" };\n\t\t\tthis._confirmedUp.add(confirmedKey);\n\t\t\treturn { ready: true, reason: started.reason };\n\t\t}\n\t\treturn { ready: false, reason: started.reason };\n\t}\n\n\t/**\n\t * Readiness gate for a pi-registered prism llama.cpp model (Bonsai-27B) — \"usable when needed\",\n\t * not \"served once at install time\": healthy at its registered baseUrl -> proceed (no downloads,\n\t * no spawn); not healthy -> re-verify BOTH GGUF files exist on disk, re-downloading any missing\n\t * one, then serve with the vision projector ALWAYS attached (see\n\t * {@link ensurePrismModelFilesThenServe} — the sole path allowed to call `runtime.serve()` for\n\t * this model) -> proceed; any stage fails -> the turn fails with that stage's error and\n\t * llama-server is never spawned half-configured. No consent dialog here (contrast\n\t * maybeInstallOllamaOnConsent/maybeInstallTransformersOnConsent) — see\n\t * maybeInstallManagedLocalOnConsent's doc comment for why. Reuses the model's already-registered\n\t * `contextWindow` for a re-serve rather than re-deriving from current host RAM, so a restarted\n\t * server can never end up with a different served context than the rest of the session (e.g.\n\t * compaction) already assumes.\n\t */\n\tprivate async ensurePrismLlamaCppModelReady(\n\t\tmodel: Model<Api>,\n\t): Promise<{ ready: boolean; reason: string; installGuide?: string[] }> {\n\t\tif (!isPiManagedPrismLlamaCppModel(model)) {\n\t\t\treturn { ready: true, reason: \"not_pi_managed_llama_cpp\" };\n\t\t}\n\t\tconst serverUrl = this.deriveOpenAICompatServerUrl(model.baseUrl);\n\t\tconst confirmedKey = this.confirmationKey(model, serverUrl);\n\t\tthis.invalidateIfLastCallFailed(model, serverUrl);\n\t\tif (this._confirmedUp.has(confirmedKey)) {\n\t\t\treturn { ready: true, reason: \"confirmed_up_cached\" };\n\t\t}\n\t\tif (await isPrismLlamaCppServerHealthy(serverUrl, this.deps.prismLlamaCppDeps?.fetchFn)) {\n\t\t\tthis._confirmedUp.add(confirmedKey);\n\t\t\treturn { ready: true, reason: \"already_running\" };\n\t\t}\n\t\tconst descriptor = PRISM_LLAMACPP_DESCRIPTORS[model.id];\n\t\tif (!descriptor) {\n\t\t\t// Unreachable given the isPiManagedPrismLlamaCppModel check above (same lookup table), but\n\t\t\t// an honest failure beats a silent bad-cast if the two ever drift apart.\n\t\t\treturn { ready: false, reason: `no_curated_descriptor:${model.id}` };\n\t\t}\n\t\tconst served = await ensurePrismModelFilesThenServe(\n\t\t\tthis.getPrismLlamaCppRuntime(),\n\t\t\tdescriptor,\n\t\t\t{ port: PRISM_LLAMACPP_SERVE_PORT, numCtx: model.contextWindow },\n\t\t\t() => {},\n\t\t);\n\t\tif (!served.ok) {\n\t\t\treturn { ready: false, reason: `${served.stage}:${served.error}` };\n\t\t}\n\t\tthis._confirmedUp.add(confirmedKey);\n\t\treturn { ready: true, reason: \"started\" };\n\t}\n\n\t/**\n\t * #31: the ONE case a routed local model's unreadiness can be fixed automatically is a missing\n\t * ollama binary — an unreachable server can't be helped by installing, so that reason is left to\n\t * the graceful-fallback warning below unchanged. Only offered when there's an interactive UI to\n\t * ask through: headless/RPC/print sessions have no UI context and fall straight through, same as\n\t * declining or timing out (both resolve confirm() to false). Reverses \"pi never runs installers\n\t * itself\" specifically for this one path — the user is asked first, the download is pi's own\n\t * (never curl|sh), and it lands in pi's own runtimes dir (see OllamaRuntime.installManaged).\n\t *\n\t * Pauses/resumes the routing working-indicator around the confirm dialog itself (re-emitting\n\t * routing_end/routing_start — both already idempotent, see interactive-mode.ts's handlers) so an\n\t * animated spinner doesn't fight a dialog the user is trying to read and answer; the indicator\n\t * comes back for the download/extract that follows a \"yes\", which is genuine processing feedback.\n\t */\n\tprivate async maybeInstallOllamaOnConsent(\n\t\tmodel: Model<Api>,\n\t\treadiness: { ready: boolean; reason: string; installGuide?: string[] },\n\t): Promise<{ ready: boolean; reason: string; installGuide?: string[]; installAttemptError?: string }> {\n\t\tconst ui = this.deps.getUIContext();\n\t\tif (!ui || readiness.ready || readiness.reason !== \"binary_missing\") return readiness;\n\n\t\tconst modelLabel = this.deps.formatModel(model);\n\t\tthis.deps.emit({ type: \"routing_end\" });\n\t\tlet confirmed: boolean;\n\t\ttry {\n\t\t\tconfirmed = await ui.confirm(\n\t\t\t\t\"Install Ollama?\",\n\t\t\t\t`Ollama isn't installed, so the local model \"${modelLabel}\" can't run. Pi can download and ` +\n\t\t\t\t\t\"install it now (a large one-time download, possibly over 1 GB depending on your platform) \" +\n\t\t\t\t\t\"into its own runtimes folder — never curl|sh, never touching anything outside pi's own \" +\n\t\t\t\t\t\"directory. Install it now?\",\n\t\t\t\t{ timeout: OLLAMA_INSTALL_CONFIRM_TIMEOUT_MS },\n\t\t\t);\n\t\t} finally {\n\t\t\tthis.deps.emit({ type: \"routing_start\" });\n\t\t}\n\t\tif (!confirmed) return readiness;\n\n\t\tconst serverUrl = this.deriveOllamaServerUrl(model.baseUrl);\n\t\tconst runtime = this.getLocalRuntime(serverUrl);\n\t\tlet installResult: { ok: boolean; error?: string };\n\t\ttry {\n\t\t\tinstallResult = await runtime.installManaged((status) => ui.setStatus(\"ollama-install\", status));\n\t\t} finally {\n\t\t\tui.setStatus(\"ollama-install\", undefined);\n\t\t}\n\t\tif (!installResult.ok) {\n\t\t\treturn { ready: false, reason: \"install_failed\", installAttemptError: installResult.error };\n\t\t}\n\t\treturn this.ensureLocalModelReady(model);\n\t}\n\n\tprivate async maybeInstallTransformersOnConsent(\n\t\tmodel: Model<Api>,\n\t\treadiness: { ready: boolean; reason: string; installGuide?: string[] },\n\t): Promise<{ ready: boolean; reason: string; installGuide?: string[]; installAttemptError?: string }> {\n\t\tconst ui = this.deps.getUIContext();\n\t\tif (!ui || readiness.ready || readiness.reason !== \"runtime_missing\") return readiness;\n\n\t\tconst modelLabel = this.deps.formatModel(model);\n\t\tthis.deps.emit({ type: \"routing_end\" });\n\t\tlet confirmed: boolean;\n\t\ttry {\n\t\t\tconfirmed = await ui.confirm(\n\t\t\t\t\"Install Transformers runtime?\",\n\t\t\t\t`The Hugging Face model \"${modelLabel}\" needs a pi-managed Python venv with Transformers ` +\n\t\t\t\t\t\"and CPU PyTorch before it can run. Pi will install those packages into its own runtimes \" +\n\t\t\t\t\t\"folder, download the model into a pi-owned Hugging Face cache, and leave system Python, \" +\n\t\t\t\t\t\"your Ollama models, and your user HF cache untouched. Install it now?\",\n\t\t\t\t{ timeout: OLLAMA_INSTALL_CONFIRM_TIMEOUT_MS },\n\t\t\t);\n\t\t} finally {\n\t\t\tthis.deps.emit({ type: \"routing_start\" });\n\t\t}\n\t\tif (!confirmed) return readiness;\n\n\t\tconst serverUrl = this.deriveOpenAICompatServerUrl(model.baseUrl);\n\t\tconst runtime = this.getTransformersRuntime(model.id, serverUrl);\n\t\tlet installResult: { ok: boolean; error?: string };\n\t\ttry {\n\t\t\tinstallResult = await runtime.installManaged((status) => ui.setStatus(\"transformers-install\", status));\n\t\t} finally {\n\t\t\tui.setStatus(\"transformers-install\", undefined);\n\t\t}\n\t\tif (!installResult.ok) {\n\t\t\treturn { ready: false, reason: \"install_failed\", installAttemptError: installResult.error };\n\t\t}\n\t\tlet downloadResult: { ok: boolean; error?: string };\n\t\ttry {\n\t\t\tdownloadResult = await runtime.downloadModel((status) => ui.setStatus(\"transformers-download\", status));\n\t\t} finally {\n\t\t\tui.setStatus(\"transformers-download\", undefined);\n\t\t}\n\t\tif (!downloadResult.ok) {\n\t\t\treturn { ready: false, reason: \"download_failed\", installAttemptError: downloadResult.error };\n\t\t}\n\t\treturn this.ensureTransformersModelReady(model);\n\t}\n\n\t/**\n\t * Router-swap gate (#27): a turn routed to a local model (any tier, including an executor-direct\n\t * route — both carry tier \"cheap\") must not dead-end the turn just because ollama isn't up.\n\t * Never a SILENT swap: every fallback is announced in a warning that states (i) the local model\n\t * was unavailable and WHY — binary missing surfaces the install guide inline; any other reason\n\t * gets a \"check that ollama is running\" hint — and (ii) which tier is now handling the turn, so\n\t * the cost shift is never a surprise. Escalates cheap -> medium -> expensive, skipping any\n\t * unconfigured intermediate tier, reusing the router's own existing \"model unavailable\"\n\t * resolution (resolveConfiguredTierModel) rather than inventing a new fallback mechanism.\n\t * Escalation is bounded: tier strictly increases each hop, so it terminates within two hops.\n\t *\n\t * Before the warning/escalation below: #31's consent gate gets one shot at fixing a missing\n\t * binary interactively (see maybeInstallOllamaOnConsent) — declining, timing out, running\n\t * headless, or the install attempt itself failing all fall through here unchanged, just with an\n\t * honest reason (an install that failed is worded as a failed install, not re-labeled as if\n\t * nothing was ever tried).\n\t */\n\tasync ensureRouteModelReady(\n\t\tresolved: { decision: RouteDecision; model: Model<Api> } | undefined,\n\t): Promise<{ decision: RouteDecision; model: Model<Api> } | undefined> {\n\t\tlet current = resolved;\n\t\twhile (current && this.isManagedLocalModel(current.model)) {\n\t\t\tlet readiness: { ready: boolean; reason: string; installGuide?: string[]; installAttemptError?: string } =\n\t\t\t\tawait this.ensureManagedLocalReadiness(current.model);\n\t\t\tif (!readiness.ready) {\n\t\t\t\treadiness = await this.maybeInstallManagedLocalOnConsent(current.model, readiness);\n\t\t\t}\n\t\t\tif (readiness.ready) return current;\n\n\t\t\t// Walk the remaining tiers in order (never back down to cheap) and take the first one that\n\t\t\t// actually resolves — an unconfigured intermediate tier (e.g. no mediumModel set) must be\n\t\t\t// skipped, not treated as \"no fallback available\".\n\t\t\tconst startIndex = MODEL_ROUTER_TIER_ORDER.indexOf(current.decision.tier as \"cheap\" | \"medium\" | \"expensive\");\n\t\t\tlet escalated: { tier: \"medium\" | \"expensive\"; model: Model<Api> } | undefined;\n\t\t\tfor (let i = startIndex + 1; startIndex !== -1 && i < MODEL_ROUTER_TIER_ORDER.length; i++) {\n\t\t\t\tconst tier = MODEL_ROUTER_TIER_ORDER[i] as \"medium\" | \"expensive\";\n\t\t\t\tconst model = this.deps.resolveConfiguredTierModel(tier);\n\t\t\t\tif (model) {\n\t\t\t\t\tescalated = { tier, model };\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tconst modelLabel = this.deps.formatModel(current.model);\n\t\t\tconst localRuntimeName =\n\t\t\t\tcurrent.model.provider === OLLAMA_PROVIDER\n\t\t\t\t\t? \"ollama\"\n\t\t\t\t\t: current.model.provider === HF_TRANSFORMERS_PROVIDER\n\t\t\t\t\t\t? \"Transformers\"\n\t\t\t\t\t\t: \"prism llama.cpp\";\n\t\t\tconst wrongStore = parseWrongOllamaStoreReason(readiness.reason);\n\t\t\tconst whyText = readiness.installAttemptError\n\t\t\t\t? `pi tried to install it just now, but the install attempt failed: ${readiness.installAttemptError}`\n\t\t\t\t: readiness.installGuide\n\t\t\t\t\t? [\n\t\t\t\t\t\t\tcurrent.model.provider === OLLAMA_PROVIDER\n\t\t\t\t\t\t\t\t? \"the ollama binary is not installed.\"\n\t\t\t\t\t\t\t\t: \"the pi-managed Transformers runtime is not installed.\",\n\t\t\t\t\t\t\t...readiness.installGuide,\n\t\t\t\t\t\t].join(\"\\n\")\n\t\t\t\t\t: wrongStore\n\t\t\t\t\t\t? `an Ollama server is already running with store ${wrongStore.activePath} (${wrongStore.modelCount} model(s)); pi's owned store is ${wrongStore.ownedPath}. Stop the other server or run /models import, then retry.`\n\t\t\t\t\t\t: current.model.provider === OLLAMA_PROVIDER\n\t\t\t\t\t\t\t? `its ${localRuntimeName} server is not reachable (${readiness.reason}) — check that ollama is running.`\n\t\t\t\t\t\t\t: `its ${localRuntimeName} server is not reachable (${readiness.reason}) — check that the runtime is running.`;\n\t\t\tconst fallbackText = escalated\n\t\t\t\t? `Falling back to the ${escalated.tier} tier for this turn.`\n\t\t\t\t: \"No other tier is configured — falling back to the session's default model.\";\n\t\t\tthis.deps.emit({\n\t\t\t\ttype: \"warning\",\n\t\t\t\tmessage: `Local model \"${modelLabel}\" is unavailable: ${whyText}\\n${fallbackText}`,\n\t\t\t});\n\n\t\t\tif (!escalated) return undefined; // no higher tier resolves — caller falls back to the session default\n\t\t\tcurrent = {\n\t\t\t\tmodel: escalated.model,\n\t\t\t\tdecision: {\n\t\t\t\t\t...current.decision,\n\t\t\t\t\ttier: escalated.tier,\n\t\t\t\t\tfallbackFrom: current.decision.tier,\n\t\t\t\t\treasonCode: \"local_model_not_ready_fallback\",\n\t\t\t\t\treasons: [\n\t\t\t\t\t\t...current.decision.reasons,\n\t\t\t\t\t\t`Local model not ready (${readiness.reason}); escalated to ${escalated.tier}`,\n\t\t\t\t\t],\n\t\t\t\t\tmodel: this.deps.formatModel(escalated.model),\n\t\t\t\t},\n\t\t\t};\n\t\t}\n\t\treturn current;\n\t}\n\n\t/**\n\t * Stop every pi-spawned local runtime (Ollama, Transformers, prism llama.cpp) that no longer\n\t * backs any model in `eligibleModels` — the caller's post-reload/profile-switch configuration\n\t * (typically: the foreground model plus whatever the model router's tiers still resolve to).\n\t * Called by the reload path so a local model dropped from the live configuration doesn't leave\n\t * its child process running untracked for the rest of the process lifetime.\n\t *\n\t * Never touches a server this session merely DETECTED (a user/system-run Ollama server, or any\n\t * server that was already up when first probed): {@link OllamaRuntime.stop}/\n\t * {@link TransformersRuntime.stop}/{@link PrismLlamaCppRuntime.stop} already no-op unless the\n\t * instance holds a live pi-spawned child-process handle (see each class's own `stop()`), so\n\t * calling `stop()` unconditionally on every cached instance below is safe by construction — it\n\t * can never kill a process pi didn't start.\n\t *\n\t * Never stops a runtime still backing an eligible model. Eligibility is checked at the SAME\n\t * granularity each map is keyed at: `_runtimes` is keyed by Ollama serverUrl (one server can host\n\t * several models), so it survives as long as ANY eligible model still points at that server;\n\t * `_transformersRuntimes` is keyed by (modelId, serverUrl) — one runtime per model, so eligibility\n\t * is exact; the prism runtime is a single pi-owned instance that survives while ANY eligible model\n\t * is pi-managed prism.\n\t *\n\t * The `_confirmedUp` cache is pruned separately, in ONE pass over every provider: since\n\t * `confirmationKey` is uniformly `${serverUrl}\\0${model.id}` across every provider, a single\n\t * eligible-keys set built the same way covers all three providers. This also correctly drops a\n\t * model's stale confirmation even when its SERVER survives (e.g. two Ollama models on one server,\n\t * only one still eligible) — a case the coarser per-server runtime eviction above can't see on\n\t * its own.\n\t */\n\treconcile(eligibleModels: readonly Model<Api>[]): void {\n\t\tconst eligibleOllamaServers = new Set(\n\t\t\teligibleModels\n\t\t\t\t.filter((model) => model.provider === OLLAMA_PROVIDER)\n\t\t\t\t.map((model) => this.deriveOllamaServerUrl(model.baseUrl)),\n\t\t);\n\t\tfor (const [serverUrl, runtime] of this._runtimes) {\n\t\t\tif (eligibleOllamaServers.has(serverUrl)) continue;\n\t\t\truntime.stop();\n\t\t\tthis._runtimes.delete(serverUrl);\n\t\t}\n\n\t\tconst eligibleTransformersRuntimeKeys = new Set(\n\t\t\teligibleModels\n\t\t\t\t.filter((model) => model.provider === HF_TRANSFORMERS_PROVIDER)\n\t\t\t\t.map((model) => this._transformersRuntimeKey(model.id, this.deriveOllamaServerUrl(model.baseUrl))),\n\t\t);\n\t\tfor (const [runtimeKey, runtime] of this._transformersRuntimes) {\n\t\t\tif (eligibleTransformersRuntimeKeys.has(runtimeKey)) continue;\n\t\t\truntime.stop();\n\t\t\tthis._transformersRuntimes.delete(runtimeKey);\n\t\t}\n\n\t\tif (this._prismLlamaCppRuntime && !eligibleModels.some((model) => isPiManagedPrismLlamaCppModel(model))) {\n\t\t\tthis._prismLlamaCppRuntime.stop();\n\t\t\tthis._prismLlamaCppRuntime = undefined;\n\t\t}\n\n\t\t// deriveOllamaServerUrl strips a trailing `/v1` regardless of provider (same body as the\n\t\t// private deriveOpenAICompatServerUrl it mirrors), so it's safe to reuse here for every\n\t\t// managed-local provider's baseUrl when building the confirmationKey-shaped eligible set.\n\t\tconst eligibleConfirmationKeys = new Set(\n\t\t\teligibleModels\n\t\t\t\t.filter((model) => this.isManagedLocalModel(model))\n\t\t\t\t.map((model) => this.confirmationKey(model, this.deriveOllamaServerUrl(model.baseUrl))),\n\t\t);\n\t\tfor (const key of this._confirmedUp) {\n\t\t\tif (!eligibleConfirmationKeys.has(key)) this._confirmedUp.delete(key);\n\t\t}\n\t}\n\n\t/** Full teardown of every pi-spawned local runtime — reconcile against an empty eligible set. */\n\tdispose(): void {\n\t\tthis.reconcile([]);\n\t}\n\n\t/** Shared cache-key shape for {@link _transformersRuntimes}, factored out so\n\t * {@link getTransformersRuntime} and {@link reconcile} can never drift apart. */\n\tprivate _transformersRuntimeKey(modelId: string, resolvedBaseUrl: string): string {\n\t\treturn `${modelId}\\0${resolvedBaseUrl}`;\n\t}\n}\n"]}
+{"version":3,"file":"local-runtime-controller.d.ts","sourceRoot":"","sources":["../../src/core/local-runtime-controller.ts"],"names":[],"mappings":"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"}