@caupulican/pi-adaptative 0.94.0 → 0.95.0

package/dist/core/memory/providers/file-store.js

@@ -2,9 +2,12 @@ import { createHash, randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import { Type } from "typebox";
 import { configFile, managedMemoryStateFile } from "../../agent-paths.js";
+import { OKF_MEMORY_LIMITS, PI_OKF_TYPES, validateOkfMemoryDocumentInput, } from "../../context/okf-memory.js";
 import { hasInvisibleUnicode, scanContextFileThreats, stripInvisibleUnicode, } from "../../security/context-threat-scanner.js";
 import { jaccard, tokenize } from "../../tools/skill-audit.js";
-import { withFileLock, writeFileAtomic } from "../../util/atomic-file.js";
+import { isMissingFileError, withFileLock, writeFileAtomic } from "../../util/atomic-file.js";
+import { OkfProjectMemoryStore } from "../okf-project-memory-store.js";
+import { ROOT_MEMORY_TOOL_NAME } from "../worker-memory-tools.js";
 import { UserMemoryArchive } from "./user-memory-archive.js";
 /**
  * Confront-before-write (anti append-rot): if `content` is a near-duplicate of an existing
@@ -39,21 +42,58 @@ export function supersedeNearDuplicateLine(existing, content) {
     return lines.join("\n");
 }
 const memorySchema = Type.Object({
-    action: Type.Union([Type.Literal("add"), Type.Literal("replace"), Type.Literal("remove")], {
+    action: Type.Union([Type.Literal("add"), Type.Literal("replace"), Type.Literal("remove"), Type.Literal("list")], {
         description: "Action to perform: add new content, replace existing content, or remove content",
     }),
-    target: Type.Union([Type.Literal("memory"), Type.Literal("user")], {
-        description: "Target file: 'memory' for MEMORY.md, 'user' for USER.md",
+    target: Type.Union([Type.Literal("memory"), Type.Literal("user"), Type.Literal("okf")], {
+        description: "Target: 'memory' for MEMORY.md, 'user' for USER.md, or 'okf' for structured project memory",
     }),
-    content: Type.Optional(Type.String({ description: "Content to write (required for 'add' or 'replace')" })),
+    content: Type.Optional(Type.String({
+        maxLength: OKF_MEMORY_LIMITS.bodyChars,
+        description: "Content to write (required for add/replace)",
+    })),
+    title: Type.Optional(Type.String({
+        minLength: 1,
+        maxLength: OKF_MEMORY_LIMITS.titleChars,
+        description: "Structured OKF title (required when target is 'okf')",
+    })),
     oldContent: Type.Optional(Type.String({ description: "Exact substring to replace or remove (required for 'replace' or 'remove')" })),
+    type: Type.Optional(Type.Union(PI_OKF_TYPES.map((value) => Type.Literal(value)), {
+        description: "Structured OKF type (required when target is 'okf')",
+    })),
+    description: Type.Optional(Type.String({
+        minLength: 1,
+        maxLength: OKF_MEMORY_LIMITS.descriptionChars,
+        description: "Structured OKF summary (required when target is 'okf')",
+    })),
+    scope: Type.Optional(Type.Literal("project", { description: "Structured OKF records are project-scoped" })),
+    tags: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: OKF_MEMORY_LIMITS.tagChars }), {
+        maxItems: OKF_MEMORY_LIMITS.tagCount,
+        uniqueItems: true,
+        description: "Structured OKF tags",
+    })),
+    evidenceRefs: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: OKF_MEMORY_LIMITS.evidenceRefChars }), {
+        minItems: 1,
+        maxItems: OKF_MEMORY_LIMITS.evidenceRefCount,
+        uniqueItems: true,
+        description: "Evidence references for structured OKF",
+    })),
+    expectedDigest: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$", description: "Optional conflict guard for structured removal" })),
 });
-export const FILE_STORE_MEMORY_SYSTEM_NOTE = "[System Note: Below is a snapshot of persistent memory. Proactively record verified reusable project facts and user preferences with the 'memory' tool; never store transient noise.]";
+export const FILE_STORE_MEMORY_SYSTEM_NOTE = "[System Note: Below is a snapshot of persistent memory. Proactively record verified reusable project facts and user preferences with the 'memory' tool. Keep MEMORY.md for compact hot facts, USER.md for preferences, and use target 'okf' for durable project decisions, architecture, rules, findings, and references. Never store transient noise.]";
 function contentDigest(content) {
     return createHash("sha256").update(content, "utf8").digest("hex");
 }
-function isMissingFileError(error) {
-    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+function removeExactHotMemoryItem(existing, sourceText) {
+    if (sourceText.length === 0)
+        return undefined;
+    const memoryLines = existing.split("\n");
+    const sourceLines = sourceText.split("\n");
+    const start = memoryLines.findIndex((_, index) => sourceLines.every((line, offset) => memoryLines[index + offset] === line));
+    if (start === -1)
+        return undefined;
+    memoryLines.splice(start, sourceLines.length);
+    return memoryLines.join("\n");
 }
 function parseManagedMemoryState(raw) {
     let parsed;
@@ -177,6 +217,7 @@ export class FileStoreProvider {
         this.userStatePath = managedMemoryStateFile(ctx.agentDir, "USER.md");
         this.userArchive = new UserMemoryArchive(ctx.agentDir);
         await fs.mkdir(ctx.agentDir, { recursive: true });
+        this.okfStore = new OkfProjectMemoryStore(ctx.agentDir, ctx.cwd);
         [this.lastWrittenMemory, this.lastWrittenUser] = await Promise.all([
             this.initializeManagedFile(this.memoryFilePath, this.memoryStatePath),
             this.initializeManagedFile(this.userFilePath, this.userStatePath),
@@ -212,6 +253,8 @@ export class FileStoreProvider {
         });
     }
     systemPromptBlock(budget) {
+        if (this.ctx?.isChildSession)
+            return "";
         const sanitize = (content) => {
             // Strip hidden/bidi-control chars before injecting memory into the prompt (defence in depth: the
             // write path already blocks them, but a file edited out-of-band could carry them). Strip #31.
@@ -256,33 +299,140 @@ export class FileStoreProvider {
     async shutdown() {
         // no-op
     }
+    async executeMemoryCommand(params, signal) {
+        const tool = this.getToolDefinitions()[0];
+        if (tool === undefined)
+            return { details: { success: false, error: "Memory tool unavailable" } };
+        const result = await tool.execute("reflection-memory", params, signal, undefined, undefined);
+        return result;
+    }
+    async hasExactHotMemoryItem(sourceText) {
+        return withFileLock(this.memoryFilePath, async () => {
+            const current = await fs.readFile(this.memoryFilePath, "utf8");
+            return removeExactHotMemoryItem(current, sourceText) !== undefined;
+        });
+    }
+    async removeExactHotMemoryItem(sourceText) {
+        try {
+            return await withFileLock(this.memoryFilePath, async () => {
+                const currentOnDisk = await fs.readFile(this.memoryFilePath, "utf8");
+                const currentDigest = contentDigest(currentOnDisk);
+                const stateRead = await readManagedMemoryState(this.memoryStatePath);
+                let managedState;
+                if (stateRead.status === "valid") {
+                    const reconciled = reconcileManagedMemoryState(currentDigest, stateRead.state);
+                    if (reconciled.recognized) {
+                        managedState = reconciled.state;
+                        if (reconciled.changed)
+                            await writeManagedMemoryState(this.memoryStatePath, reconciled.state);
+                    }
+                }
+                if (!managedState)
+                    return { success: false, error: "Drift detected" };
+                const newContent = removeExactHotMemoryItem(currentOnDisk, sourceText);
+                if (newContent === undefined)
+                    return { success: false, error: "Exact hot-memory item was not found" };
+                const newDigest = contentDigest(newContent);
+                await writeManagedMemoryState(this.memoryStatePath, {
+                    version: 1,
+                    committedDigest: managedState.committedDigest,
+                    pendingDigest: newDigest,
+                });
+                await writeFileAtomic(this.memoryFilePath, newContent, { mode: 0o600 });
+                await writeManagedMemoryState(this.memoryStatePath, { version: 1, committedDigest: newDigest });
+                this.lastWrittenMemory = newContent;
+                this.options.onDurableMemoryChanged?.();
+                return { success: true };
+            });
+        }
+        catch (error) {
+            return { success: false, error: String(error) };
+        }
+    }
+    /** Reflection-owned structured write. Organization is OKF-first, then exact hot-memory removal. */
+    async applyStructuredReflectionWrite(write, signal) {
+        if (write.kind === "okf_organize" && !(await this.hasExactHotMemoryItem(write.sourceText))) {
+            return {
+                applied: false,
+                created: false,
+                sourceRemoved: false,
+                error: "Exact hot-memory item was not found",
+            };
+        }
+        const added = await this.executeMemoryCommand({
+            action: "add",
+            target: "okf",
+            type: write.type,
+            title: write.title,
+            description: write.description,
+            scope: "project",
+            content: write.text,
+            tags: write.tags,
+            evidenceRefs: write.evidenceRefs,
+        }, signal);
+        if (added.details?.success !== true) {
+            return { applied: false, created: false, error: added.details?.error ?? "OKF write failed" };
+        }
+        const created = added.details.created === true;
+        const storedDigest = added.details.digest;
+        if (write.kind === "okf_add") {
+            return {
+                applied: created,
+                created,
+                ...(storedDigest ? { digest: storedDigest } : {}),
+                ...(!created ? { error: "Exact OKF record already exists" } : {}),
+            };
+        }
+        await this.options.beforeOrganizeHotRemoval?.();
+        const removed = await this.removeExactHotMemoryItem(write.sourceText);
+        const sourceRemoved = removed.success;
+        return {
+            // A newly-created OKF record is a real durable change even if exact hot cleanup was
+            // interrupted. This records a reversible partial apply instead of hiding landed data.
+            applied: created || sourceRemoved,
+            created,
+            ...(storedDigest ? { digest: storedDigest } : {}),
+            sourceRemoved,
+            ...(!sourceRemoved ? { error: removed.error ?? "Hot-memory removal failed" } : {}),
+        };
+    }
+    /** Restore hot memory first, then conditionally remove the exact audited OKF bytes. */
+    async rollbackStructuredReflectionWrite(rollback, signal) {
+        if (rollback.sourceText !== undefined) {
+            const restored = await this.executeMemoryCommand({ action: "add", target: "memory", content: rollback.sourceText }, signal);
+            if (restored.details?.success !== true)
+                return false;
+        }
+        if (!rollback.removeRecord)
+            return true;
+        const removed = await this.executeMemoryCommand({
+            action: "remove",
+            target: "okf",
+            type: rollback.type,
+            title: rollback.title,
+            expectedDigest: rollback.expectedDigest,
+        }, signal);
+        return removed.details?.success === true;
+    }
     getContextMarkers() {
         return [];
     }
     getToolDefinitions() {
+        if (this.ctx?.isChildSession)
+            return [];
         return [
             {
-                name: "memory",
+                name: ROOT_MEMORY_TOOL_NAME,
                 label: "Persistent Memory Manager",
-                description: "Add, replace, or remove durable project facts and user preferences. Proactively store newly verified reusable facts; USER.md overflow is migrated into indexed OKF shards.",
-                promptSnippet: "Persist verified project facts and user preferences.",
+                description: "Add, replace, or remove durable facts and preferences. Use target 'okf' with structured metadata for durable project decisions, architecture, rules, debugging findings, and references; USER.md overflow is migrated into indexed OKF shards.",
+                promptSnippet: "Persist verified facts; route durable project knowledge to structured OKF records.",
                 promptGuidelines: [
-                    "Store verified facts and preferences. Repeatable multi-step procedures become skills via skillify; reflection promotes them when the write is a workflow.",
+                    "OKF=project decisions/rules/findings with type,title,summary,body,evidenceRefs; MEMORY=hot facts; USER=preferences.",
+                    "Workers gather evidence read-only; only the parent or its reflection writes memory. Repeatable procedures become skills via skillify.",
                 ],
                 parameters: memorySchema,
                 execute: async (_toolCallId, params, _signal, _onUpdate, _execCtx) => {
-                    if (this.ctx?.isChildSession) {
-                        return {
-                            content: [
-                                {
-                                    type: "text",
-                                    text: "Error: Writes to persistent memory are not allowed in child sessions (subagents).",
-                                },
-                            ],
-                            details: { success: false, error: "Child session write-gated" },
-                        };
-                    }
-                    const { action, target, content, oldContent } = params;
+                    const { action, target, content, oldContent, title, type, description, scope, tags, evidenceRefs, expectedDigest, } = params;
                     // Strict-scope injection guard on the high-privilege WRITE path (agy #31): a poisoned
                     // memory entry persists across sessions and is injected into every future system prompt,
                     // so block outright rather than strip. Hidden/bidi-control chars have no legitimate place
@@ -312,6 +462,173 @@ export class FileStoreProvider {
                             };
                         }
                     }
+                    if (target === "okf") {
+                        if (action === "list") {
+                            if (this.okfStore === undefined) {
+                                return {
+                                    content: [{ type: "text", text: "Error: Memory provider is not initialized." }],
+                                    details: { success: false },
+                                };
+                            }
+                            const catalog = this.okfStore.list();
+                            return {
+                                content: [{ type: "text", text: catalog || "No structured OKF memory records found." }],
+                                details: { success: true },
+                            };
+                        }
+                        if (action !== "add" && action !== "remove") {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "Error: structured OKF memory only supports action 'add' or 'remove'.",
+                                    },
+                                ],
+                                details: { success: false, error: "Unsupported OKF action" },
+                            };
+                        }
+                        if (action === "remove") {
+                            if (this.okfStore === undefined ||
+                                type === undefined ||
+                                title === undefined ||
+                                !PI_OKF_TYPES.includes(type)) {
+                                return {
+                                    content: [{ type: "text", text: "Error: OKF removal requires a valid type and title." }],
+                                    details: { success: false, error: "Incomplete OKF removal" },
+                                };
+                            }
+                            try {
+                                const removed = await this.okfStore.remove(type, title, expectedDigest);
+                                if (removed.removed)
+                                    this.options.onDurableMemoryChanged?.();
+                                return {
+                                    content: [
+                                        {
+                                            type: "text",
+                                            text: removed.removed
+                                                ? "Successfully removed structured OKF project memory."
+                                                : "Structured OKF project memory was already absent.",
+                                        },
+                                    ],
+                                    details: { success: true, removed: removed.removed },
+                                };
+                            }
+                            catch (err) {
+                                const error = String(err);
+                                return {
+                                    content: [{ type: "text", text: `Error: Failed to remove structured OKF memory: ${error}` }],
+                                    details: { success: false, error: /ENOENT/.test(error) ? "not found" : error },
+                                };
+                            }
+                        }
+                        if (type === undefined ||
+                            title === undefined ||
+                            description === undefined ||
+                            scope !== "project" ||
+                            content === undefined ||
+                            evidenceRefs === undefined ||
+                            evidenceRefs.length === 0) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "Error: structured OKF memory requires type, title, description, scope, content, and evidenceRefs.",
+                                    },
+                                ],
+                                details: { success: false, error: "Incomplete OKF memory" },
+                            };
+                        }
+                        if (!PI_OKF_TYPES.includes(type)) {
+                            return {
+                                content: [{ type: "text", text: `Error: unsupported OKF type '${type}'.` }],
+                                details: { success: false, error: "Unsupported OKF type" },
+                            };
+                        }
+                        const validationErrors = validateOkfMemoryDocumentInput({
+                            type: type,
+                            title,
+                            description,
+                            scope,
+                            body: content,
+                            tags,
+                            evidenceRefs,
+                        }, { projectOnly: true, requireEvidence: true });
+                        if (validationErrors.length > 0) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: `Error: Invalid structured OKF memory: ${validationErrors.join("; ")}`,
+                                    },
+                                ],
+                                details: { success: false, error: "Invalid OKF memory" },
+                            };
+                        }
+                        const okfText = [type, title, description, scope, content, ...(tags ?? []), ...evidenceRefs].join("\n");
+                        if (hasInvisibleUnicode(okfText)) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "Error: OKF write rejected — contains hidden/bidirectional control characters.",
+                                    },
+                                ],
+                                details: { success: false, error: "Invisible unicode in OKF write" },
+                            };
+                        }
+                        const threats = scanContextFileThreats(okfText, "strict");
+                        if (threats.length > 0) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: `Error: OKF write rejected — potential injection/exfiltration detected (${threats.join(", ")}).`,
+                                    },
+                                ],
+                                details: { success: false, error: "Threat in OKF write" },
+                            };
+                        }
+                        try {
+                            if (this.okfStore === undefined)
+                                throw new Error("Memory provider is not initialized.");
+                            const stored = await this.okfStore.put({
+                                type: type,
+                                title,
+                                description,
+                                scope,
+                                body: content,
+                                tags,
+                                evidenceRefs,
+                            });
+                            if (stored.created)
+                                this.options.onDurableMemoryChanged?.();
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: stored.created
+                                            ? "Successfully added structured OKF project memory."
+                                            : "Structured OKF project memory already contained this exact record.",
+                                    },
+                                ],
+                                details: { success: true, created: stored.created, digest: stored.digest },
+                            };
+                        }
+                        catch (err) {
+                            return {
+                                content: [
+                                    { type: "text", text: `Error: Failed to write structured OKF memory: ${String(err)}` },
+                                ],
+                                details: { success: false, error: String(err) },
+                            };
+                        }
+                    }
+                    if (action === "list") {
+                        return {
+                            content: [{ type: "text", text: "Error: action 'list' is only supported for target 'okf'." }],
+                            details: { success: false, error: "Unsupported list target" },
+                        };
+                    }
                     const filePath = target === "memory" ? this.memoryFilePath : this.userFilePath;
                     const statePath = target === "memory" ? this.memoryStatePath : this.userStatePath;
                     const budget = target === "memory" ? FileStoreProvider.BUDGET_MEMORY : FileStoreProvider.BUDGET_USER;