@caupulican/pi-adaptative 0.94.0 → 0.95.0

package/dist/core/learning/auto-learn-settings.js

@@ -0,0 +1,66 @@
+/** The authoritative Auto Learn defaults used by runtime resolution and settings UI. */
+export const DEFAULT_AUTO_LEARN_SETTINGS = {
+    enabled: true,
+    model: "active",
+    thinkingLevel: "low",
+    longSessionMessages: 32,
+    longSessionContextPercent: 70,
+    cooldownMinutes: 24 * 60,
+    leaseMinutes: 90,
+    maxConcurrentLearners: 1,
+    applyHighConfidence: false,
+    reflectionReview: true,
+    reflectionMinToolCalls: 12,
+    reflectionCooldownMinutes: 24 * 60,
+    complexTaskToolCalls: 12,
+};
+export const AUTONOMY_AUTO_LEARN_PRESETS = {
+    off: DEFAULT_AUTO_LEARN_SETTINGS,
+    safe: {
+        ...DEFAULT_AUTO_LEARN_SETTINGS,
+        longSessionMessages: 64,
+        longSessionContextPercent: 85,
+        leaseMinutes: 60,
+    },
+    balanced: {
+        ...DEFAULT_AUTO_LEARN_SETTINGS,
+        longSessionMessages: 64,
+        longSessionContextPercent: 85,
+    },
+    full: {
+        ...DEFAULT_AUTO_LEARN_SETTINGS,
+        longSessionMessages: 64,
+        longSessionContextPercent: 85,
+        applyHighConfidence: true,
+    },
+};
+export function getAutoLearnPreset(mode, current = {}) {
+    const preset = AUTONOMY_AUTO_LEARN_PRESETS[mode] ?? AUTONOMY_AUTO_LEARN_PRESETS.off;
+    return { ...preset, model: current.model?.trim() || preset.model };
+}
+export function resolveAutoLearnSettings(mode, settings = {}) {
+    const preset = getAutoLearnPreset(mode, settings);
+    return {
+        enabled: settings.enabled ?? preset.enabled,
+        model: settings.model?.trim() || preset.model,
+        thinkingLevel: settings.thinkingLevel ?? preset.thinkingLevel,
+        longSessionMessages: settings.longSessionMessages ?? preset.longSessionMessages,
+        longSessionContextPercent: settings.longSessionContextPercent ?? preset.longSessionContextPercent,
+        cooldownMinutes: settings.cooldownMinutes ?? preset.cooldownMinutes,
+        leaseMinutes: settings.leaseMinutes ?? preset.leaseMinutes,
+        maxConcurrentLearners: settings.maxConcurrentLearners ?? preset.maxConcurrentLearners,
+        applyHighConfidence: settings.applyHighConfidence ?? preset.applyHighConfidence,
+        reflectionReview: settings.reflectionReview ?? preset.reflectionReview,
+        reflectionMinToolCalls: settings.reflectionMinToolCalls ?? preset.reflectionMinToolCalls,
+        reflectionCooldownMinutes: settings.reflectionCooldownMinutes ?? preset.reflectionCooldownMinutes,
+        complexTaskToolCalls: settings.complexTaskToolCalls ?? preset.complexTaskToolCalls,
+    };
+}
+/** One settings/environment gate shared by root prompt construction and current-turn cue delivery. */
+export function isCurrentSessionReflectionEnabled(settings, env = process.env) {
+    return (settings.enabled &&
+        settings.reflectionReview &&
+        env.PI_NATIVE_REFLECTION !== "0" &&
+        env.PI_AUTO_LEARN_CHILD !== "1");
+}
+//# sourceMappingURL=auto-learn-settings.js.map

package/dist/core/learning/auto-learn-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-learn-settings.js","sourceRoot":"","sources":["../../../src/core/learning/auto-learn-settings.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AutoLearnSettings, AutonomyMode } from \"../settings-manager.ts\";\n\n/** The authoritative Auto Learn defaults used by runtime resolution and settings UI. */\nexport const DEFAULT_AUTO_LEARN_SETTINGS = {\n\tenabled: true,\n\tmodel: \"active\",\n\tthinkingLevel: \"low\",\n\tlongSessionMessages: 32,\n\tlongSessionContextPercent: 70,\n\tcooldownMinutes: 24 * 60,\n\tleaseMinutes: 90,\n\tmaxConcurrentLearners: 1,\n\tapplyHighConfidence: false,\n\treflectionReview: true,\n\treflectionMinToolCalls: 12,\n\treflectionCooldownMinutes: 24 * 60,\n\tcomplexTaskToolCalls: 12,\n} as const satisfies Required<AutoLearnSettings>;\n\nexport const AUTONOMY_AUTO_LEARN_PRESETS = {\n\toff: DEFAULT_AUTO_LEARN_SETTINGS,\n\tsafe: {\n\t\t...DEFAULT_AUTO_LEARN_SETTINGS,\n\t\tlongSessionMessages: 64,\n\t\tlongSessionContextPercent: 85,\n\t\tleaseMinutes: 60,\n\t},\n\tbalanced: {\n\t\t...DEFAULT_AUTO_LEARN_SETTINGS,\n\t\tlongSessionMessages: 64,\n\t\tlongSessionContextPercent: 85,\n\t},\n\tfull: {\n\t\t...DEFAULT_AUTO_LEARN_SETTINGS,\n\t\tlongSessionMessages: 64,\n\t\tlongSessionContextPercent: 85,\n\t\tapplyHighConfidence: true,\n\t},\n} as const satisfies Record<AutonomyMode, Required<AutoLearnSettings>>;\n\nexport function getAutoLearnPreset(mode: AutonomyMode, current: AutoLearnSettings = {}): Required<AutoLearnSettings> {\n\tconst preset = AUTONOMY_AUTO_LEARN_PRESETS[mode] ?? AUTONOMY_AUTO_LEARN_PRESETS.off;\n\treturn { ...preset, model: current.model?.trim() || preset.model };\n}\n\nexport function resolveAutoLearnSettings(\n\tmode: AutonomyMode,\n\tsettings: AutoLearnSettings = {},\n): Required<AutoLearnSettings> {\n\tconst preset = getAutoLearnPreset(mode, settings);\n\treturn {\n\t\tenabled: settings.enabled ?? preset.enabled,\n\t\tmodel: settings.model?.trim() || preset.model,\n\t\tthinkingLevel: settings.thinkingLevel ?? preset.thinkingLevel,\n\t\tlongSessionMessages: settings.longSessionMessages ?? preset.longSessionMessages,\n\t\tlongSessionContextPercent: settings.longSessionContextPercent ?? preset.longSessionContextPercent,\n\t\tcooldownMinutes: settings.cooldownMinutes ?? preset.cooldownMinutes,\n\t\tleaseMinutes: settings.leaseMinutes ?? preset.leaseMinutes,\n\t\tmaxConcurrentLearners: settings.maxConcurrentLearners ?? preset.maxConcurrentLearners,\n\t\tapplyHighConfidence: settings.applyHighConfidence ?? preset.applyHighConfidence,\n\t\treflectionReview: settings.reflectionReview ?? preset.reflectionReview,\n\t\treflectionMinToolCalls: settings.reflectionMinToolCalls ?? preset.reflectionMinToolCalls,\n\t\treflectionCooldownMinutes: settings.reflectionCooldownMinutes ?? preset.reflectionCooldownMinutes,\n\t\tcomplexTaskToolCalls: settings.complexTaskToolCalls ?? preset.complexTaskToolCalls,\n\t};\n}\n\n/** One settings/environment gate shared by root prompt construction and current-turn cue delivery. */\nexport function isCurrentSessionReflectionEnabled(\n\tsettings: Pick<Required<AutoLearnSettings>, \"enabled\" | \"reflectionReview\">,\n\tenv: NodeJS.ProcessEnv = process.env,\n): boolean {\n\treturn (\n\t\tsettings.enabled &&\n\t\tsettings.reflectionReview &&\n\t\tenv.PI_NATIVE_REFLECTION !== \"0\" &&\n\t\tenv.PI_AUTO_LEARN_CHILD !== \"1\"\n\t);\n}\n"]}

package/dist/core/learning/learning-audit.d.ts

@@ -9,13 +9,17 @@ import type { ReflectionWrite } from "./reflection-engine.ts";
  * log, so `/autonomy diagnostics` can explain what changed, why, and how to undo it — and
  * `rollbackLearningWrite` can execute the inverse operation.
  */
-export type LearningRollbackKind = "memory_remove" | "memory_restore" | "memory_add" | "archive_skill";
+export type LearningRollbackKind = "memory_remove" | "memory_restore" | "memory_add" | "okf_remove" | "okf_organize" | "archive_skill";
 export interface LearningRollbackPlan {
     kind: LearningRollbackKind;
     /** Text currently present because of the change (to remove/replace), or the skill name to archive. */
     target?: string;
     /** Original text to restore (memory_restore/memory_add). */
     previous?: string;
+    /** Compare-and-delete guard for a structured record created by this exact audited write. */
+    expectedDigest?: string;
+    /** Organization rollback only: false when the OKF record predated this hot-memory move. */
+    removeOkf?: boolean;
     instructions: string;
 }
 export type LearningAuditAction = "apply" | "apply_failed" | "propose" | "rollback";

package/dist/core/learning/learning-audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"learning-audit.d.ts","sourceRoot":"","sources":["../../../src/core/learning/learning-audit.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;AAChC,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;GAKG;AAEH,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,gBAAgB,GAAG,YAAY,GAAG,eAAe,CAAC;AAEvG,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACrB;AAKD,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,cAAc,GAAG,SAAS,GAAG,UAAU,CAAC;AAEpF;;0DAE0D;AAC1D,eAAO,MAAM,+BAA+B,wBAAwB,CAAC;AAErE,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CAClB;AAeD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,qBAAqB,CAO7G;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAS/E;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,eAAe,GAAG,oBAAoB,CA4B3F;AA8BD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAYlF;AAED,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAMnG;AAED,eAAO,MAAM,0BAA0B,mBAAmB,CAAC;AAE3D,MAAM,MAAM,4BAA4B,GAAG,sBAAsB,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC;AASjG,wBAAgB,2BAA2B,CAC1C,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACzD,MAAM,EAAE,mBAAmB,GACzB,MAAM,CAER;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,mBAAmB,EAAE,CAEjG"}
+{"version":3,"file":"learning-audit.d.ts","sourceRoot":"","sources":["../../../src/core/learning/learning-audit.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;AAChC,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;GAKG;AAEH,MAAM,MAAM,oBAAoB,GAC7B,eAAe,GACf,gBAAgB,GAChB,YAAY,GACZ,YAAY,GACZ,cAAc,GACd,eAAe,CAAC;AAEnB,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACrB;AAKD,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,cAAc,GAAG,SAAS,GAAG,UAAU,CAAC;AAEpF;;0DAE0D;AAC1D,eAAO,MAAM,+BAA+B,wBAAwB,CAAC;AAErE,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CAClB;AAmBD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,qBAAqB,CAO7G;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAW/E;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,eAAe,GAAG,oBAAoB,CA0C3F;AAuCD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAYlF;AAED,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAMnG;AAED,eAAO,MAAM,0BAA0B,mBAAmB,CAAC;AAE3D,MAAM,MAAM,4BAA4B,GAAG,sBAAsB,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC;AASjG,wBAAgB,2BAA2B,CAC1C,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACzD,MAAM,EAAE,mBAAmB,GACzB,MAAM,CAER;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,mBAAmB,EAAE,CAEjG"}

package/dist/core/learning/learning-audit.js

@@ -7,6 +7,10 @@ function describeWrite(write) {
     switch (write.kind) {
         case "memory_add":
             return `Add ${write.section} memory: ${write.text}`;
+        case "okf_add":
+            return `Add OKF ${write.type}: ${write.title}`;
+        case "okf_organize":
+            return `Organize MEMORY fact into OKF ${write.type}: ${write.title}`;
         case "memory_replace":
             return `Replace memory "${write.target}" with "${write.text}"`;
         case "memory_remove":
@@ -36,6 +40,8 @@ export function contradictionsForReflectionWrite(write) {
         case "memory_remove":
             return 1;
         case "memory_add":
+        case "okf_add":
+        case "okf_organize":
         case "promote_skill":
             return 0;
     }
@@ -48,6 +54,20 @@ export function rollbackPlanForReflectionWrite(write) {
                 target: write.text,
                 instructions: `Remove the added ${write.section} memory text.`,
             };
+        case "okf_add":
+            return {
+                kind: "okf_remove",
+                target: `${write.type}\0${write.title}`,
+                instructions: "Remove the added structured OKF memory record.",
+            };
+        case "okf_organize":
+            return {
+                kind: "okf_organize",
+                target: `${write.type}\0${write.title}`,
+                previous: write.sourceText,
+                removeOkf: true,
+                instructions: "Restore the exact hot-memory source first, then remove only the audited OKF record.",
+            };
         case "memory_replace":
             return {
                 kind: "memory_restore",
@@ -70,7 +90,14 @@ export function rollbackPlanForReflectionWrite(write) {
     }
 }
 const AUDIT_ACTIONS = ["apply", "apply_failed", "propose", "rollback"];
-const ROLLBACK_KINDS = ["memory_remove", "memory_restore", "memory_add", "archive_skill"];
+const ROLLBACK_KINDS = [
+    "memory_remove",
+    "memory_restore",
+    "memory_add",
+    "okf_remove",
+    "okf_organize",
+    "archive_skill",
+];
 const LAYERS = ["memory", "skill", "prompt", "extension", "tool", "script", "settings", "source"];
 function isOptionalString(value) {
     return value === undefined || typeof value === "string";
@@ -83,6 +110,10 @@ function isLearningRollbackPlan(value) {
         return false;
     if (!isOptionalString(plan.target) || !isOptionalString(plan.previous))
         return false;
+    if (!isOptionalString(plan.expectedDigest))
+        return false;
+    if (plan.removeOkf !== undefined && typeof plan.removeOkf !== "boolean")
+        return false;
     return typeof plan.instructions === "string";
 }
 function isLearningDecisionShape(value) {

package/dist/core/learning/learning-audit.js.map

@@ -1 +1 @@
-{"version":3,"file":"learning-audit.js","sourceRoot":"","sources":["../../../src/core/learning/learning-audit.ts"],"names":[],"mappings":"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","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 type { DurableChangeLayer, DurableChangeProposal } from \"./learning-gate.ts\";\nimport type { ReflectionWrite } from \"./reflection-engine.ts\";\n\n/**\n * Audit + rollback metadata for durable learning changes. Every reflection-sourced write that the\n * learning policy applies (or converts to a proposal) leaves one of these records in the session\n * log, so `/autonomy diagnostics` can explain what changed, why, and how to undo it — and\n * `rollbackLearningWrite` can execute the inverse operation.\n */\n\nexport type LearningRollbackKind = \"memory_remove\" | \"memory_restore\" | \"memory_add\" | \"archive_skill\";\n\nexport interface LearningRollbackPlan {\n\tkind: LearningRollbackKind;\n\t/** Text currently present because of the change (to remove/replace), or the skill name to archive. */\n\ttarget?: string;\n\t/** Original text to restore (memory_restore/memory_add). */\n\tprevious?: string;\n\tinstructions: string;\n}\n\n// \"apply_failed\" is distinct from \"apply\": the gate decided to apply, but the underlying write tool\n// (e.g. the memory tool) refused it (budget exceeded, drift, threat) without throwing. It must never\n// be treated as \"apply\" by a rollback-eligibility check — there is nothing durable to undo.\nexport type LearningAuditAction = \"apply\" | \"apply_failed\" | \"propose\" | \"rollback\";\n\n/** reasonCode for an \"apply_failed\" audit — distinct from the gate's own reasonCode (e.g.\n * \"eligible_auto_apply\") so the record is honest about WHERE it stopped: the gate approved the\n * write, but the write tool refused it after the fact. */\nexport const APPLY_WRITE_REFUSED_REASON_CODE = \"apply_write_refused\";\n\nexport interface LearningAuditRecord {\n\tid: string;\n\tproposalId: string;\n\tlayer: DurableChangeLayer;\n\taction: LearningAuditAction;\n\tsummary: string;\n\treasonCode: string;\n\tdecision: LearningDecision;\n\trollback?: LearningRollbackPlan;\n\t/** For action \"rollback\": the audit id of the applied change this record undoes. */\n\trollbackOf?: string;\n\tcreatedAt: string;\n}\n\nfunction describeWrite(write: ReflectionWrite): string {\n\tswitch (write.kind) {\n\t\tcase \"memory_add\":\n\t\t\treturn `Add ${write.section} memory: ${write.text}`;\n\t\tcase \"memory_replace\":\n\t\t\treturn `Replace memory \"${write.target}\" with \"${write.text}\"`;\n\t\tcase \"memory_remove\":\n\t\t\treturn `Remove memory: ${write.target}`;\n\t\tcase \"promote_skill\":\n\t\t\treturn `Promote skill \"${write.name}\": ${write.description}`;\n\t}\n}\n\nexport function proposalFromReflectionWrite(write: ReflectionWrite, proposalId: string): DurableChangeProposal {\n\treturn {\n\t\tid: proposalId,\n\t\tlayer: write.kind === \"promote_skill\" ? \"skill\" : \"memory\",\n\t\tsummary: describeWrite(write),\n\t\trollbackPlan: rollbackPlanForReflectionWrite(write).instructions,\n\t};\n}\n\n/**\n * Contradiction count a reflection write carries against existing durable knowledge. A\n * `memory_replace`/`memory_remove` is only emitted when the reflection engine CONFRONTS an existing\n * fact (it supersedes or deletes it) — that supersession is the gate's contradiction signal, so such\n * a write must route through approval rather than silently overwriting prior memory. A `memory_add`\n * or `promote_skill` is purely additive and contradicts nothing.\n */\nexport function contradictionsForReflectionWrite(write: ReflectionWrite): number {\n\tswitch (write.kind) {\n\t\tcase \"memory_replace\":\n\t\tcase \"memory_remove\":\n\t\t\treturn 1;\n\t\tcase \"memory_add\":\n\t\tcase \"promote_skill\":\n\t\t\treturn 0;\n\t}\n}\n\nexport function rollbackPlanForReflectionWrite(write: ReflectionWrite): LearningRollbackPlan {\n\tswitch (write.kind) {\n\t\tcase \"memory_add\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_remove\",\n\t\t\t\ttarget: write.text,\n\t\t\t\tinstructions: `Remove the added ${write.section} memory text.`,\n\t\t\t};\n\t\tcase \"memory_replace\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_restore\",\n\t\t\t\ttarget: write.text,\n\t\t\t\tprevious: write.target,\n\t\t\t\tinstructions: \"Replace the new memory text with the original text it overwrote.\",\n\t\t\t};\n\t\tcase \"memory_remove\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_add\",\n\t\t\t\tprevious: write.target,\n\t\t\t\tinstructions: \"Re-add the removed text to the MEMORY file (it may originally have lived in USER).\",\n\t\t\t};\n\t\tcase \"promote_skill\":\n\t\t\treturn {\n\t\t\t\tkind: \"archive_skill\",\n\t\t\t\ttarget: write.name,\n\t\t\t\tinstructions: \"Archive the promoted skill so it no longer loads.\",\n\t\t\t};\n\t}\n}\n\nconst AUDIT_ACTIONS: readonly string[] = [\"apply\", \"apply_failed\", \"propose\", \"rollback\"];\nconst ROLLBACK_KINDS: readonly string[] = [\"memory_remove\", \"memory_restore\", \"memory_add\", \"archive_skill\"];\nconst LAYERS: readonly string[] = [\"memory\", \"skill\", \"prompt\", \"extension\", \"tool\", \"script\", \"settings\", \"source\"];\n\nfunction isOptionalString(value: unknown): boolean {\n\treturn value === undefined || typeof value === \"string\";\n}\n\nfunction isLearningRollbackPlan(value: unknown): value is LearningRollbackPlan {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst plan = value as Record<string, unknown>;\n\tif (typeof plan.kind !== \"string\" || !ROLLBACK_KINDS.includes(plan.kind)) return false;\n\tif (!isOptionalString(plan.target) || !isOptionalString(plan.previous)) return false;\n\treturn typeof plan.instructions === \"string\";\n}\n\nfunction isLearningDecisionShape(value: unknown): value is LearningDecision {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst decision = value as Record<string, unknown>;\n\treturn (\n\t\t(decision.kind === \"no-op\" || decision.kind === \"proposal\" || decision.kind === \"apply\") &&\n\t\ttypeof decision.reasonCode === \"string\" &&\n\t\ttypeof decision.confidence === \"number\" &&\n\t\ttypeof decision.summary === \"string\" &&\n\t\ttypeof decision.requiresApproval === \"boolean\"\n\t);\n}\n\nexport function isLearningAuditRecord(value: unknown): value is LearningAuditRecord {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst record = value as Record<string, unknown>;\n\tif (typeof record.id !== \"string\" || record.id.length === 0) return false;\n\tif (typeof record.proposalId !== \"string\") return false;\n\tif (typeof record.layer !== \"string\" || !LAYERS.includes(record.layer)) return false;\n\tif (typeof record.action !== \"string\" || !AUDIT_ACTIONS.includes(record.action)) return false;\n\tif (typeof record.summary !== \"string\" || typeof record.reasonCode !== \"string\") return false;\n\tif (!isLearningDecisionShape(record.decision)) return false;\n\tif (record.rollback !== undefined && !isLearningRollbackPlan(record.rollback)) return false;\n\tif (!isOptionalString(record.rollbackOf)) return false;\n\treturn typeof record.createdAt === \"string\";\n}\n\nexport function cloneLearningAuditRecordForStorage(record: LearningAuditRecord): LearningAuditRecord {\n\treturn {\n\t\t...record,\n\t\tdecision: { ...record.decision },\n\t\t...(record.rollback ? { rollback: { ...record.rollback } } : {}),\n\t};\n}\n\nexport const LEARNING_AUDIT_CUSTOM_TYPE = \"learning_audit\";\n\nexport type LearningAuditSnapshotPayload = SessionSnapshotPayload<\"record\", LearningAuditRecord>;\n\nconst LEARNING_AUDIT_SNAPSHOT_CODEC: SessionSnapshotCodec<LearningAuditRecord, \"record\"> = {\n\tcustomType: LEARNING_AUDIT_CUSTOM_TYPE,\n\tvalueKey: \"record\",\n\tisValue: isLearningAuditRecord,\n\tclone: cloneLearningAuditRecordForStorage,\n};\n\nexport function appendLearningAuditSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\trecord: LearningAuditRecord,\n): string {\n\treturn appendSessionSnapshot(sessionManager, LEARNING_AUDIT_SNAPSHOT_CODEC, record);\n}\n\nexport function getLearningAuditSnapshots(entries: readonly SessionEntry[]): LearningAuditRecord[] {\n\treturn getSessionSnapshots(entries, LEARNING_AUDIT_SNAPSHOT_CODEC);\n}\n"]}
+{"version":3,"file":"learning-audit.js","sourceRoot":"","sources":["../../../src/core/learning/learning-audit.ts"],"names":[],"mappings":"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","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 type { DurableChangeLayer, DurableChangeProposal } from \"./learning-gate.ts\";\nimport type { ReflectionWrite } from \"./reflection-engine.ts\";\n\n/**\n * Audit + rollback metadata for durable learning changes. Every reflection-sourced write that the\n * learning policy applies (or converts to a proposal) leaves one of these records in the session\n * log, so `/autonomy diagnostics` can explain what changed, why, and how to undo it — and\n * `rollbackLearningWrite` can execute the inverse operation.\n */\n\nexport type LearningRollbackKind =\n\t| \"memory_remove\"\n\t| \"memory_restore\"\n\t| \"memory_add\"\n\t| \"okf_remove\"\n\t| \"okf_organize\"\n\t| \"archive_skill\";\n\nexport interface LearningRollbackPlan {\n\tkind: LearningRollbackKind;\n\t/** Text currently present because of the change (to remove/replace), or the skill name to archive. */\n\ttarget?: string;\n\t/** Original text to restore (memory_restore/memory_add). */\n\tprevious?: string;\n\t/** Compare-and-delete guard for a structured record created by this exact audited write. */\n\texpectedDigest?: string;\n\t/** Organization rollback only: false when the OKF record predated this hot-memory move. */\n\tremoveOkf?: boolean;\n\tinstructions: string;\n}\n\n// \"apply_failed\" is distinct from \"apply\": the gate decided to apply, but the underlying write tool\n// (e.g. the memory tool) refused it (budget exceeded, drift, threat) without throwing. It must never\n// be treated as \"apply\" by a rollback-eligibility check — there is nothing durable to undo.\nexport type LearningAuditAction = \"apply\" | \"apply_failed\" | \"propose\" | \"rollback\";\n\n/** reasonCode for an \"apply_failed\" audit — distinct from the gate's own reasonCode (e.g.\n * \"eligible_auto_apply\") so the record is honest about WHERE it stopped: the gate approved the\n * write, but the write tool refused it after the fact. */\nexport const APPLY_WRITE_REFUSED_REASON_CODE = \"apply_write_refused\";\n\nexport interface LearningAuditRecord {\n\tid: string;\n\tproposalId: string;\n\tlayer: DurableChangeLayer;\n\taction: LearningAuditAction;\n\tsummary: string;\n\treasonCode: string;\n\tdecision: LearningDecision;\n\trollback?: LearningRollbackPlan;\n\t/** For action \"rollback\": the audit id of the applied change this record undoes. */\n\trollbackOf?: string;\n\tcreatedAt: string;\n}\n\nfunction describeWrite(write: ReflectionWrite): string {\n\tswitch (write.kind) {\n\t\tcase \"memory_add\":\n\t\t\treturn `Add ${write.section} memory: ${write.text}`;\n\t\tcase \"okf_add\":\n\t\t\treturn `Add OKF ${write.type}: ${write.title}`;\n\t\tcase \"okf_organize\":\n\t\t\treturn `Organize MEMORY fact into OKF ${write.type}: ${write.title}`;\n\t\tcase \"memory_replace\":\n\t\t\treturn `Replace memory \"${write.target}\" with \"${write.text}\"`;\n\t\tcase \"memory_remove\":\n\t\t\treturn `Remove memory: ${write.target}`;\n\t\tcase \"promote_skill\":\n\t\t\treturn `Promote skill \"${write.name}\": ${write.description}`;\n\t}\n}\n\nexport function proposalFromReflectionWrite(write: ReflectionWrite, proposalId: string): DurableChangeProposal {\n\treturn {\n\t\tid: proposalId,\n\t\tlayer: write.kind === \"promote_skill\" ? \"skill\" : \"memory\",\n\t\tsummary: describeWrite(write),\n\t\trollbackPlan: rollbackPlanForReflectionWrite(write).instructions,\n\t};\n}\n\n/**\n * Contradiction count a reflection write carries against existing durable knowledge. A\n * `memory_replace`/`memory_remove` is only emitted when the reflection engine CONFRONTS an existing\n * fact (it supersedes or deletes it) — that supersession is the gate's contradiction signal, so such\n * a write must route through approval rather than silently overwriting prior memory. A `memory_add`\n * or `promote_skill` is purely additive and contradicts nothing.\n */\nexport function contradictionsForReflectionWrite(write: ReflectionWrite): number {\n\tswitch (write.kind) {\n\t\tcase \"memory_replace\":\n\t\tcase \"memory_remove\":\n\t\t\treturn 1;\n\t\tcase \"memory_add\":\n\t\tcase \"okf_add\":\n\t\tcase \"okf_organize\":\n\t\tcase \"promote_skill\":\n\t\t\treturn 0;\n\t}\n}\n\nexport function rollbackPlanForReflectionWrite(write: ReflectionWrite): LearningRollbackPlan {\n\tswitch (write.kind) {\n\t\tcase \"memory_add\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_remove\",\n\t\t\t\ttarget: write.text,\n\t\t\t\tinstructions: `Remove the added ${write.section} memory text.`,\n\t\t\t};\n\t\tcase \"okf_add\":\n\t\t\treturn {\n\t\t\t\tkind: \"okf_remove\",\n\t\t\t\ttarget: `${write.type}\\0${write.title}`,\n\t\t\t\tinstructions: \"Remove the added structured OKF memory record.\",\n\t\t\t};\n\t\tcase \"okf_organize\":\n\t\t\treturn {\n\t\t\t\tkind: \"okf_organize\",\n\t\t\t\ttarget: `${write.type}\\0${write.title}`,\n\t\t\t\tprevious: write.sourceText,\n\t\t\t\tremoveOkf: true,\n\t\t\t\tinstructions: \"Restore the exact hot-memory source first, then remove only the audited OKF record.\",\n\t\t\t};\n\t\tcase \"memory_replace\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_restore\",\n\t\t\t\ttarget: write.text,\n\t\t\t\tprevious: write.target,\n\t\t\t\tinstructions: \"Replace the new memory text with the original text it overwrote.\",\n\t\t\t};\n\t\tcase \"memory_remove\":\n\t\t\treturn {\n\t\t\t\tkind: \"memory_add\",\n\t\t\t\tprevious: write.target,\n\t\t\t\tinstructions: \"Re-add the removed text to the MEMORY file (it may originally have lived in USER).\",\n\t\t\t};\n\t\tcase \"promote_skill\":\n\t\t\treturn {\n\t\t\t\tkind: \"archive_skill\",\n\t\t\t\ttarget: write.name,\n\t\t\t\tinstructions: \"Archive the promoted skill so it no longer loads.\",\n\t\t\t};\n\t}\n}\n\nconst AUDIT_ACTIONS: readonly string[] = [\"apply\", \"apply_failed\", \"propose\", \"rollback\"];\nconst ROLLBACK_KINDS: readonly string[] = [\n\t\"memory_remove\",\n\t\"memory_restore\",\n\t\"memory_add\",\n\t\"okf_remove\",\n\t\"okf_organize\",\n\t\"archive_skill\",\n];\nconst LAYERS: readonly string[] = [\"memory\", \"skill\", \"prompt\", \"extension\", \"tool\", \"script\", \"settings\", \"source\"];\n\nfunction isOptionalString(value: unknown): boolean {\n\treturn value === undefined || typeof value === \"string\";\n}\n\nfunction isLearningRollbackPlan(value: unknown): value is LearningRollbackPlan {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst plan = value as Record<string, unknown>;\n\tif (typeof plan.kind !== \"string\" || !ROLLBACK_KINDS.includes(plan.kind)) return false;\n\tif (!isOptionalString(plan.target) || !isOptionalString(plan.previous)) return false;\n\tif (!isOptionalString(plan.expectedDigest)) return false;\n\tif (plan.removeOkf !== undefined && typeof plan.removeOkf !== \"boolean\") return false;\n\treturn typeof plan.instructions === \"string\";\n}\n\nfunction isLearningDecisionShape(value: unknown): value is LearningDecision {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst decision = value as Record<string, unknown>;\n\treturn (\n\t\t(decision.kind === \"no-op\" || decision.kind === \"proposal\" || decision.kind === \"apply\") &&\n\t\ttypeof decision.reasonCode === \"string\" &&\n\t\ttypeof decision.confidence === \"number\" &&\n\t\ttypeof decision.summary === \"string\" &&\n\t\ttypeof decision.requiresApproval === \"boolean\"\n\t);\n}\n\nexport function isLearningAuditRecord(value: unknown): value is LearningAuditRecord {\n\tif (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n\tconst record = value as Record<string, unknown>;\n\tif (typeof record.id !== \"string\" || record.id.length === 0) return false;\n\tif (typeof record.proposalId !== \"string\") return false;\n\tif (typeof record.layer !== \"string\" || !LAYERS.includes(record.layer)) return false;\n\tif (typeof record.action !== \"string\" || !AUDIT_ACTIONS.includes(record.action)) return false;\n\tif (typeof record.summary !== \"string\" || typeof record.reasonCode !== \"string\") return false;\n\tif (!isLearningDecisionShape(record.decision)) return false;\n\tif (record.rollback !== undefined && !isLearningRollbackPlan(record.rollback)) return false;\n\tif (!isOptionalString(record.rollbackOf)) return false;\n\treturn typeof record.createdAt === \"string\";\n}\n\nexport function cloneLearningAuditRecordForStorage(record: LearningAuditRecord): LearningAuditRecord {\n\treturn {\n\t\t...record,\n\t\tdecision: { ...record.decision },\n\t\t...(record.rollback ? { rollback: { ...record.rollback } } : {}),\n\t};\n}\n\nexport const LEARNING_AUDIT_CUSTOM_TYPE = \"learning_audit\";\n\nexport type LearningAuditSnapshotPayload = SessionSnapshotPayload<\"record\", LearningAuditRecord>;\n\nconst LEARNING_AUDIT_SNAPSHOT_CODEC: SessionSnapshotCodec<LearningAuditRecord, \"record\"> = {\n\tcustomType: LEARNING_AUDIT_CUSTOM_TYPE,\n\tvalueKey: \"record\",\n\tisValue: isLearningAuditRecord,\n\tclone: cloneLearningAuditRecordForStorage,\n};\n\nexport function appendLearningAuditSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\trecord: LearningAuditRecord,\n): string {\n\treturn appendSessionSnapshot(sessionManager, LEARNING_AUDIT_SNAPSHOT_CODEC, record);\n}\n\nexport function getLearningAuditSnapshots(entries: readonly SessionEntry[]): LearningAuditRecord[] {\n\treturn getSessionSnapshots(entries, LEARNING_AUDIT_SNAPSHOT_CODEC);\n}\n"]}

package/dist/core/learning/reflection-engine.d.ts

@@ -1,4 +1,5 @@
 import type { Usage } from "@caupulican/pi-ai";
+import { type PiOkfType } from "../context/okf-memory.ts";
 import { REFLECTION_SYSTEM_PROMPT } from "../provider-prompt-contracts.ts";
 export { REFLECTION_SYSTEM_PROMPT };
 export type StopReason = "stop" | "toolUse" | "aborted" | "error" | string;
@@ -35,6 +36,25 @@ export type ReflectionWrite = {
     kind: "memory_add";
     section: "MEMORY" | "USER";
     text: string;
+} | {
+    kind: "okf_add";
+    type: PiOkfType;
+    title: string;
+    description: string;
+    scope: "project";
+    text: string;
+    tags?: string[];
+    evidenceRefs: string[];
+} | {
+    kind: "okf_organize";
+    type: PiOkfType;
+    title: string;
+    description: string;
+    scope: "project";
+    text: string;
+    sourceText: string;
+    tags?: string[];
+    evidenceRefs: string[];
 } | {
     kind: "memory_replace";
     target: string;
@@ -53,6 +73,10 @@ export interface ReflectionResult {
     usage: Usage;
     rationale: string;
 }
+/** Maximum number of durable writes accepted from one isolated reflection response. */
+export declare const MAX_REFLECTION_WRITES = 32;
+/** Maximum number of response entries inspected while looking for accepted writes. */
+export declare const MAX_REFLECTION_SCAN_ENTRIES: number;
 /**
  * STATIC reflection system prompt (Hermes-parity #33). It is byte-identical across every reflection
  * pass — the variable parts (existing memory snapshot + the turn transcript) live in the USER prompt —

package/dist/core/learning/reflection-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reflection-engine.d.ts","sourceRoot":"","sources":["../../../src/core/learning/reflection-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAE3E,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAEpC,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3E,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,UAAU,CAAC;CACvB;AAED,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,aAAa,GAAG,MAAM,CAAC;AAE9F,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IAC1B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,UAAU,CA4B/D;AAED,MAAM,WAAW,eAAe;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,UAAU,CAAC;IAEjB,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC1F;AAED,MAAM,MAAM,eAAe,GACxB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAEzC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC5B;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiF/D;CACD"}
+{"version":3,"file":"reflection-engine.d.ts","sourceRoot":"","sources":["../../../src/core/learning/reflection-engine.ts"],"names":[],"mappings":"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"}

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

@@ -1,4 +1,7 @@
+import { OKF_MEMORY_LIMITS, PI_OKF_TYPES, validateOkfMemoryDocumentInput, } from "../context/okf-memory.js";
 import { REFLECTION_SYSTEM_PROMPT } from "../provider-prompt-contracts.js";
+import { MAX_ACTIVE_SKILL_BODY_BYTES } from "../skill-vault.js";
+import { MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_NAME_LENGTH } from "../skills.js";
 export { REFLECTION_SYSTEM_PROMPT };
 /**
  * Pure zero-I/O heuristic to decide whether the current turn justifies a reflection run
@@ -30,6 +33,93 @@ export function decideDemand(signals) {
     }
     return { act: "skip", reason: "Signals do not justify reflection overhead", tokenBudget: 0 };
 }
+/** Maximum number of durable writes accepted from one isolated reflection response. */
+export const MAX_REFLECTION_WRITES = 32;
+/** Maximum number of response entries inspected while looking for accepted writes. */
+export const MAX_REFLECTION_SCAN_ENTRIES = MAX_REFLECTION_WRITES * 4;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function currentHotMemory(existingMemory) {
+    const marker = "## MEMORY.md:\n";
+    const markerIndex = existingMemory.indexOf(marker);
+    if (markerIndex === -1) {
+        // Unit callers may provide a raw MEMORY.md snapshot. A rendered persistent-memory block
+        // without this section, however, proves that MEMORY.md is empty; never treat OKF text as hot memory.
+        return existingMemory.includes("=== Persistent Memory (file-store) ===") ||
+            /<\s*untrusted_content\b/i.test(existingMemory)
+            ? ""
+            : existingMemory;
+    }
+    const afterMemory = existingMemory.slice(markerIndex + marker.length);
+    const boundaries = [afterMemory.indexOf("\n## USER.md:"), afterMemory.search(/<\s*untrusted_content\b/i)].filter((index) => index >= 0);
+    const boundaryIndex = boundaries.length > 0 ? Math.min(...boundaries) : -1;
+    return boundaryIndex === -1 ? afterMemory : afterMemory.slice(0, boundaryIndex);
+}
+function containsExactHotMemoryItem(existingMemory, sourceText) {
+    if (sourceText.length === 0)
+        return false;
+    const memoryLines = currentHotMemory(existingMemory).split("\n");
+    const sourceLines = sourceText.split("\n");
+    return memoryLines.some((_, index) => sourceLines.every((line, offset) => memoryLines[index + offset] === line));
+}
+function boundedText(value, maxChars) {
+    return typeof value === "string" && value.length <= maxChars;
+}
+function boundedSkillBody(value) {
+    return typeof value === "string" && Buffer.byteLength(value, "utf8") <= MAX_ACTIVE_SKILL_BODY_BYTES;
+}
+/** One parser/validation path for both structured reflection operations. */
+function parseStructuredReflectionWrite(value, existingMemory) {
+    if (!isRecord(value) || (value.kind !== "okf_add" && value.kind !== "okf_organize"))
+        return undefined;
+    if (!PI_OKF_TYPES.includes(value.type) ||
+        typeof value.title !== "string" ||
+        typeof value.description !== "string" ||
+        value.scope !== "project" ||
+        typeof value.text !== "string" ||
+        !isStringArray(value.evidenceRefs) ||
+        value.evidenceRefs.length === 0 ||
+        (value.tags !== undefined && !isStringArray(value.tags))) {
+        return undefined;
+    }
+    const common = {
+        type: value.type,
+        title: value.title,
+        description: value.description,
+        scope: "project",
+        text: value.text,
+        ...(value.tags !== undefined ? { tags: value.tags } : {}),
+        evidenceRefs: value.evidenceRefs,
+    };
+    let write;
+    if (value.kind === "okf_organize") {
+        if (typeof value.sourceText !== "string" ||
+            value.sourceText.length === 0 ||
+            value.sourceText.length > OKF_MEMORY_LIMITS.bodyChars ||
+            !containsExactHotMemoryItem(existingMemory, value.sourceText)) {
+            return undefined;
+        }
+        write = { kind: "okf_organize", ...common, sourceText: value.sourceText };
+    }
+    else {
+        write = { kind: "okf_add", ...common };
+    }
+    return validateOkfMemoryDocumentInput({
+        type: write.type,
+        title: write.title,
+        description: write.description,
+        scope: write.scope,
+        body: write.text,
+        tags: write.tags,
+        evidenceRefs: write.evidenceRefs,
+    }, { projectOnly: true, requireEvidence: true }).length === 0
+        ? write
+        : undefined;
+}
 /**
  * STATIC reflection system prompt (Hermes-parity #33). It is byte-identical across every reflection
  * pass — the variable parts (existing memory snapshot + the turn transcript) live in the USER prompt —
@@ -69,25 +159,31 @@ Return JSON updates.`;
             const rationale = parsed.rationale || "";
             const writes = [];
             if (Array.isArray(parsed.writes)) {
-                for (const w of parsed.writes) {
+                const scanCount = Math.min(parsed.writes.length, MAX_REFLECTION_SCAN_ENTRIES);
+                for (let index = 0; index < scanCount && writes.length < MAX_REFLECTION_WRITES; index++) {
+                    const w = parsed.writes[index];
                     if (w && typeof w === "object") {
+                        const structuredWrite = parseStructuredReflectionWrite(w, input.existingMemory);
                         if (w.kind === "memory_add" &&
                             (w.section === "MEMORY" || w.section === "USER") &&
-                            typeof w.text === "string") {
+                            boundedText(w.text, OKF_MEMORY_LIMITS.bodyChars)) {
                             writes.push({ kind: "memory_add", section: w.section, text: w.text });
                         }
+                        else if (structuredWrite) {
+                            writes.push(structuredWrite);
+                        }
                         else if (w.kind === "memory_replace" &&
-                            typeof w.target === "string" &&
-                            typeof w.text === "string") {
+                            boundedText(w.target, OKF_MEMORY_LIMITS.bodyChars) &&
+                            boundedText(w.text, OKF_MEMORY_LIMITS.bodyChars)) {
                             writes.push({ kind: "memory_replace", target: w.target, text: w.text });
                         }
-                        else if (w.kind === "memory_remove" && typeof w.target === "string") {
+                        else if (w.kind === "memory_remove" && boundedText(w.target, OKF_MEMORY_LIMITS.bodyChars)) {
                             writes.push({ kind: "memory_remove", target: w.target });
                         }
                         else if (w.kind === "promote_skill" &&
-                            typeof w.name === "string" &&
-                            typeof w.description === "string" &&
-                            typeof w.body === "string") {
+                            boundedText(w.name, MAX_SKILL_NAME_LENGTH) &&
+                            boundedText(w.description, MAX_SKILL_DESCRIPTION_LENGTH) &&
+                            boundedSkillBody(w.body)) {
                             writes.push({ kind: "promote_skill", name: w.name, description: w.description, body: w.body });
                         }
                     }

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\";\nimport { REFLECTION_SYSTEM_PROMPT } from \"../provider-prompt-contracts.ts\";\n\nexport { REFLECTION_SYSTEM_PROMPT };\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 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:\n${input.existingMemory}\n\nRecent turn transcript:\n${input.recentTurnText}\n\nReturn JSON 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\";\nimport {\n\tOKF_MEMORY_LIMITS,\n\tPI_OKF_TYPES,\n\ttype PiOkfType,\n\tvalidateOkfMemoryDocumentInput,\n} from \"../context/okf-memory.ts\";\nimport { REFLECTION_SYSTEM_PROMPT } from \"../provider-prompt-contracts.ts\";\nimport { MAX_ACTIVE_SKILL_BODY_BYTES } from \"../skill-vault.ts\";\nimport { MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_NAME_LENGTH } from \"../skills.ts\";\n\nexport { REFLECTION_SYSTEM_PROMPT };\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| {\n\t\t\tkind: \"okf_add\";\n\t\t\ttype: PiOkfType;\n\t\t\ttitle: string;\n\t\t\tdescription: string;\n\t\t\tscope: \"project\";\n\t\t\ttext: string;\n\t\t\ttags?: string[];\n\t\t\tevidenceRefs: string[];\n\t  }\n\t| {\n\t\t\tkind: \"okf_organize\";\n\t\t\ttype: PiOkfType;\n\t\t\ttitle: string;\n\t\t\tdescription: string;\n\t\t\tscope: \"project\";\n\t\t\ttext: string;\n\t\t\tsourceText: string;\n\t\t\ttags?: string[];\n\t\t\tevidenceRefs: string[];\n\t  }\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/** Maximum number of durable writes accepted from one isolated reflection response. */\nexport const MAX_REFLECTION_WRITES = 32;\n/** Maximum number of response entries inspected while looking for accepted writes. */\nexport const MAX_REFLECTION_SCAN_ENTRIES = MAX_REFLECTION_WRITES * 4;\n\ntype StructuredReflectionWrite = Extract<ReflectionWrite, { kind: \"okf_add\" | \"okf_organize\" }>;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isStringArray(value: unknown): value is string[] {\n\treturn Array.isArray(value) && value.every((entry) => typeof entry === \"string\");\n}\n\nfunction currentHotMemory(existingMemory: string): string {\n\tconst marker = \"## MEMORY.md:\\n\";\n\tconst markerIndex = existingMemory.indexOf(marker);\n\tif (markerIndex === -1) {\n\t\t// Unit callers may provide a raw MEMORY.md snapshot. A rendered persistent-memory block\n\t\t// without this section, however, proves that MEMORY.md is empty; never treat OKF text as hot memory.\n\t\treturn existingMemory.includes(\"=== Persistent Memory (file-store) ===\") ||\n\t\t\t/<\\s*untrusted_content\\b/i.test(existingMemory)\n\t\t\t? \"\"\n\t\t\t: existingMemory;\n\t}\n\tconst afterMemory = existingMemory.slice(markerIndex + marker.length);\n\tconst boundaries = [afterMemory.indexOf(\"\\n## USER.md:\"), afterMemory.search(/<\\s*untrusted_content\\b/i)].filter(\n\t\t(index) => index >= 0,\n\t);\n\tconst boundaryIndex = boundaries.length > 0 ? Math.min(...boundaries) : -1;\n\treturn boundaryIndex === -1 ? afterMemory : afterMemory.slice(0, boundaryIndex);\n}\n\nfunction containsExactHotMemoryItem(existingMemory: string, sourceText: string): boolean {\n\tif (sourceText.length === 0) return false;\n\tconst memoryLines = currentHotMemory(existingMemory).split(\"\\n\");\n\tconst sourceLines = sourceText.split(\"\\n\");\n\treturn memoryLines.some((_, index) => sourceLines.every((line, offset) => memoryLines[index + offset] === line));\n}\n\nfunction boundedText(value: unknown, maxChars: number): value is string {\n\treturn typeof value === \"string\" && value.length <= maxChars;\n}\n\nfunction boundedSkillBody(value: unknown): value is string {\n\treturn typeof value === \"string\" && Buffer.byteLength(value, \"utf8\") <= MAX_ACTIVE_SKILL_BODY_BYTES;\n}\n\n/** One parser/validation path for both structured reflection operations. */\nfunction parseStructuredReflectionWrite(value: unknown, existingMemory: string): StructuredReflectionWrite | undefined {\n\tif (!isRecord(value) || (value.kind !== \"okf_add\" && value.kind !== \"okf_organize\")) return undefined;\n\tif (\n\t\t!PI_OKF_TYPES.includes(value.type as PiOkfType) ||\n\t\ttypeof value.title !== \"string\" ||\n\t\ttypeof value.description !== \"string\" ||\n\t\tvalue.scope !== \"project\" ||\n\t\ttypeof value.text !== \"string\" ||\n\t\t!isStringArray(value.evidenceRefs) ||\n\t\tvalue.evidenceRefs.length === 0 ||\n\t\t(value.tags !== undefined && !isStringArray(value.tags))\n\t) {\n\t\treturn undefined;\n\t}\n\tconst common = {\n\t\ttype: value.type as PiOkfType,\n\t\ttitle: value.title,\n\t\tdescription: value.description,\n\t\tscope: \"project\" as const,\n\t\ttext: value.text,\n\t\t...(value.tags !== undefined ? { tags: value.tags } : {}),\n\t\tevidenceRefs: value.evidenceRefs,\n\t};\n\tlet write: StructuredReflectionWrite;\n\tif (value.kind === \"okf_organize\") {\n\t\tif (\n\t\t\ttypeof value.sourceText !== \"string\" ||\n\t\t\tvalue.sourceText.length === 0 ||\n\t\t\tvalue.sourceText.length > OKF_MEMORY_LIMITS.bodyChars ||\n\t\t\t!containsExactHotMemoryItem(existingMemory, value.sourceText)\n\t\t) {\n\t\t\treturn undefined;\n\t\t}\n\t\twrite = { kind: \"okf_organize\", ...common, sourceText: value.sourceText };\n\t} else {\n\t\twrite = { kind: \"okf_add\", ...common };\n\t}\n\treturn validateOkfMemoryDocumentInput(\n\t\t{\n\t\t\ttype: write.type,\n\t\t\ttitle: write.title,\n\t\t\tdescription: write.description,\n\t\t\tscope: write.scope,\n\t\t\tbody: write.text,\n\t\t\ttags: write.tags,\n\t\t\tevidenceRefs: write.evidenceRefs,\n\t\t},\n\t\t{ projectOnly: true, requireEvidence: true },\n\t).length === 0\n\t\t? write\n\t\t: undefined;\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 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:\n${input.existingMemory}\n\nRecent turn transcript:\n${input.recentTurnText}\n\nReturn JSON 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\tconst scanCount = Math.min(parsed.writes.length, MAX_REFLECTION_SCAN_ENTRIES);\n\t\t\t\tfor (let index = 0; index < scanCount && writes.length < MAX_REFLECTION_WRITES; index++) {\n\t\t\t\t\tconst w = parsed.writes[index];\n\t\t\t\t\tif (w && typeof w === \"object\") {\n\t\t\t\t\t\tconst structuredWrite = parseStructuredReflectionWrite(w, input.existingMemory);\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\tboundedText(w.text, OKF_MEMORY_LIMITS.bodyChars)\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 (structuredWrite) {\n\t\t\t\t\t\t\twrites.push(structuredWrite);\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\tboundedText(w.target, OKF_MEMORY_LIMITS.bodyChars) &&\n\t\t\t\t\t\t\tboundedText(w.text, OKF_MEMORY_LIMITS.bodyChars)\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\" && boundedText(w.target, OKF_MEMORY_LIMITS.bodyChars)) {\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\tboundedText(w.name, MAX_SKILL_NAME_LENGTH) &&\n\t\t\t\t\t\t\tboundedText(w.description, MAX_SKILL_DESCRIPTION_LENGTH) &&\n\t\t\t\t\t\t\tboundedSkillBody(w.body)\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/local-prefix-warm-controller.d.ts

@@ -0,0 +1,24 @@
+/** Best-effort, preemptible standing-prefix warmup for loopback OpenAI-compatible models. */
+import type { AgentTool, StreamFn } from "@caupulican/pi-agent-core/types";
+import type { Api, Model, SimpleStreamOptions } from "@caupulican/pi-ai";
+import type { RequestAuth } from "./request-auth.ts";
+export interface LocalPrefixWarmControllerDeps {
+    getStreamFn(): StreamFn;
+    getTools(): AgentTool[];
+    getSystemPrompt(): string;
+    getRequestHooks(): Pick<SimpleStreamOptions, "onPayload" | "onResponse">;
+    isRawStreamSimple(streamFn: StreamFn): boolean;
+    getRequiredRequestAuth(model: Model<Api>): Promise<RequestAuth>;
+    ensureManagedModelReady(model: Model<Api>): Promise<void>;
+}
+export declare function isWarmableLocalModel(model: Model<Api>): boolean;
+export declare class LocalPrefixWarmController {
+    private readonly deps;
+    private active;
+    private readonly completed;
+    constructor(deps: LocalPrefixWarmControllerDeps);
+    schedule(model: Model<Api> | undefined): void;
+    cancel(): void;
+    private run;
+}
+//# sourceMappingURL=local-prefix-warm-controller.d.ts.map

package/dist/core/local-prefix-warm-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-prefix-warm-controller.d.ts","sourceRoot":"","sources":["../../src/core/local-prefix-warm-controller.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAG7F,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAIzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,6BAA6B;IAC7C,WAAW,IAAI,QAAQ,CAAC;IACxB,QAAQ,IAAI,SAAS,EAAE,CAAC;IACxB,eAAe,IAAI,MAAM,CAAC;IAC1B,eAAe,IAAI,IAAI,CAAC,mBAAmB,EAAE,WAAW,GAAG,YAAY,CAAC,CAAC;IACzE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC/C,sBAAsB,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAChE,uBAAuB,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAE/D;AAED,qBAAa,yBAAyB;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IACrD,OAAO,CAAC,MAAM,CAAmG;IACjH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAE/C,YAAY,IAAI,EAAE,6BAA6B,EAE9C;IAED,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,IAAI,CAc5C;IAED,MAAM,IAAI,IAAI,CAMb;YAEa,GAAG;CAmCjB"}