dsh-continual-evolve 0.14.2 → 0.15.0

package/lib/memory-snapshot.js

@@ -1,179 +1,139 @@
 /**
- * Read-only projection of one workspace memory store for the plugin
- * management card. Everything here is computed from disk at call time — the
- * card is a viewer, never a second store: no caching, no writes, no bootstrap
- * (unlike the injection path, a missing store is reported, not created).
+ * Read-only projection of the central memory store for the plugin
+ * management card. Everything here is computed from the database at call
+ * time — the card is a viewer, never a second store: no caching, no writes.
+ * A workspace reads as its `workspace_id` partition; the only filesystem
+ * contact is the existence check behind the workspace list (rows whose
+ * directory vanished stay in the database but are not listed — 失联不阻塞).
  */
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
-import { memoryDirFor } from "./memory-section.js";
-/** The index file name (same store contract as the injection path). */
-export const MEMORY_SNAPSHOT_INDEX_FILE = "MEMORY.md";
+import { existsSync } from "node:fs";
+import { basename } from "node:path";
+import { MEMORY_FILE_PREVIEW_LIMIT } from "./store.js";
+export { MEMORY_FILE_PREVIEW_LIMIT };
 /**
- * Preview size cap for the file content endpoint — files above it answer
- * `too-large` instead of their body (ZCode's memory viewer uses the same 5 MiB).
+ * The read-only snapshot for one workspace partition. A workspace without
+ * rows reports `exists: false` (the card shows the empty state); a failing
+ * query reports `readError` instead of throwing — the card must observe,
+ * never break.
  */
-export const MEMORY_FILE_PREVIEW_LIMIT = 5 * 1024 * 1024;
-/**
- * Parse `- [title](file.md) …` rows out of an index text. Anything else
- * (headings, the bootstrap hint comment, blank lines) is ignored.
- */
-export function parseMemoryIndexRows(indexText) {
-    const rows = [];
-    for (const line of indexText.split("\n")) {
-        const match = /^-\s+\[(.+?)\]\(([^()\s]+\.md)\)/.exec(line.trim());
-        if (match?.[1] !== undefined && match?.[2] !== undefined) {
-            rows.push({ title: match[1], file: match[2] });
-        }
-    }
-    return rows;
-}
-/**
- * Read the card-relevant frontmatter fields (`name`, `description`, `type`)
- * from a leading `---` block. A missing or malformed block yields "" fields —
- * the body text remains the source of truth the user opens in the editor.
- */
-export function parseMemoryFrontmatter(text) {
-    const fields = { name: "", description: "", type: "" };
-    if (!text.startsWith("---")) {
-        return fields;
-    }
-    const blockEnd = text.indexOf("\n---", 3);
-    if (blockEnd < 0) {
-        return fields;
-    }
-    for (const line of text.slice(3, blockEnd).split("\n")) {
-        const match = /^(name|description|type):\s*(.*)$/.exec(line.trim());
-        if (match?.[1] === undefined || match?.[2] === undefined) {
-            continue;
-        }
-        const value = match[2].trim().replace(/^["']|["']$/g, "");
-        if (match[1] === "name") {
-            fields.name = value;
-        }
-        else if (match[1] === "description") {
-            fields.description = value;
-        }
-        else {
-            fields.type = value;
-        }
-    }
-    return fields;
-}
-/** Store files the card inspects: every .md except the index, sorted. */
-function listStoreFiles(memoryDir) {
-    return readdirSync(memoryDir)
-        .filter((file) => file.endsWith(".md") && file !== MEMORY_SNAPSHOT_INDEX_FILE)
-        .sort();
-}
-/** Single read pass over the store; throws on any filesystem failure. */
-function readStoreState(memoryDir) {
-    const indexText = readFileSync(join(memoryDir, MEMORY_SNAPSHOT_INDEX_FILE), "utf8");
-    const diskFiles = listStoreFiles(memoryDir);
-    const files = diskFiles.map((file) => {
-        const frontmatter = parseMemoryFrontmatter(readFileSync(join(memoryDir, file), "utf8"));
-        const updatedAt = statSync(join(memoryDir, file)).mtimeMs;
-        return { file, name: frontmatter.name, description: frontmatter.description, type: frontmatter.type, updatedAt };
-    });
-    return { indexRows: parseMemoryIndexRows(indexText), diskFiles, files };
-}
-/**
- * The read-only memory snapshot for one workspace root. A missing store
- * reports `exists: false` (the card shows the empty state); a store that
- * exists but fails to read reports `readError` instead of throwing — the
- * card must observe, never break.
- */
-export function memorySnapshot(root) {
-    const workspaceRoot = resolve(root);
-    const memoryDir = memoryDirFor(workspaceRoot);
+export function memorySnapshot(store, root) {
+    const workspaceRoot = root;
     const absent = {
         root: workspaceRoot,
-        memoryDir,
         exists: false,
+        readError: null,
         fileCount: 0,
-        indexEntryCount: 0,
         files: [],
-        missingFiles: [],
-        unindexedFiles: [],
-        readError: null,
+        quarantined: [],
+        lastPatrol: null,
     };
-    if (!existsSync(memoryDir)) {
-        return absent;
-    }
-    let state;
+    let all;
     try {
-        state = readStoreState(memoryDir);
+        all = store.listAll(workspaceRoot);
+        if (all.length === 0) {
+            return absent;
+        }
     }
     catch (error) {
-        // Filesystem read failure degrades to an error field: the card shows
-        // what went wrong instead of taking the host down with it.
-        return {
-            ...absent,
-            exists: true,
-            readError: error instanceof Error ? error.message : String(error),
-        };
+        return { ...absent, exists: true, readError: error instanceof Error ? error.message : String(error) };
+    }
+    const lastPatrolRaw = store.state("", "patrol:last");
+    let lastPatrol = null;
+    if (typeof lastPatrolRaw === "string") {
+        try {
+            const parsed = JSON.parse(lastPatrolRaw);
+            if (typeof parsed.ts === "string") {
+                lastPatrol = {
+                    ts: parsed.ts,
+                    orphanFtsRows: typeof parsed.orphanFtsRows === "number" ? parsed.orphanFtsRows : 0,
+                    quarantined: Array.isArray(parsed.quarantined) ? parsed.quarantined.length : 0,
+                };
+            }
+        }
+        catch {
+            lastPatrol = null;
+        }
     }
-    const referenced = new Set(state.indexRows.map((row) => row.file));
     return {
         root: workspaceRoot,
-        memoryDir,
         exists: true,
-        fileCount: state.diskFiles.length,
-        indexEntryCount: state.indexRows.length,
-        files: state.files,
-        missingFiles: state.indexRows
-            .map((row) => row.file)
-            .filter((file) => !state.diskFiles.includes(file)),
-        unindexedFiles: state.diskFiles.filter((file) => !referenced.has(file)),
         readError: null,
+        fileCount: all.filter((record) => record.status === "active").length,
+        files: all.filter((record) => record.status === "active").map(infoOf),
+        quarantined: all
+            .filter((record) => record.status === "quarantined")
+            .map((record) => ({ id: record.id, reason: quarantineReasonOf(store, record) })),
+        lastPatrol,
+    };
+}
+function infoOf(record) {
+    return {
+        id: record.id,
+        title: record.title,
+        description: record.description,
+        type: record.type,
+        status: record.status,
+        updatedAt: Date.parse(record.updatedAt) || 0,
     };
 }
+/** The patrol reason recorded for a quarantined row, from the last patrol result. */
+function quarantineReasonOf(store, record) {
+    const raw = store.state("", "patrol:last");
+    if (typeof raw === "string") {
+        try {
+            const parsed = JSON.parse(raw);
+            const hit = Array.isArray(parsed.quarantined)
+                ? parsed.quarantined.find((entry) => entry?.id === record.id)
+                : undefined;
+            if (hit !== undefined && typeof hit.reason === "string") {
+                return hit.reason;
+            }
+        }
+        catch {
+            // fall through to the generic reason
+        }
+    }
+    return "巡检异常（疑似密钥泄漏），条目已隔离";
+}
 /**
- * Read one memory file's body for the card's content preview — the viewer
- * side of the same read-only fence as `memorySnapshot`. The requested file
- * name must be a plain entry of the workspace's memory directory (no path
- * separators, no traversal, resolved location stays inside the directory);
- * anything else answers `outside` without touching the filesystem, so the
- * endpoint cannot become a path oracle. Oversized files answer `too-large`
- * with the body unread.
+ * Read one memory record's body for the card's content preview — keyed by
+ * id, never by file name (the store is a database; there are no files to
+ * path-check). An unknown id answers `absent`; bodies are capped at 64KB by
+ * the schema, so `too-large` can only fire if the preview limit were ever
+ * lowered below that.
  */
-export function memoryFileContent(root, file) {
-    const memoryDir = memoryDirFor(resolve(root));
-    if (file.length === 0 ||
-        !file.endsWith(".md") ||
-        file.includes("/") ||
-        file.includes("\\") ||
-        basename(file) !== file) {
-        return { ok: false, reason: "outside" };
-    }
-    const target = resolve(memoryDir, file);
-    if (!target.startsWith(memoryDir + "/") && target !== memoryDir) {
-        return { ok: false, reason: "outside" };
+export function memoryEntryContent(store, root, id) {
+    if (id.length === 0) {
+        return { ok: false, reason: "absent" };
     }
-    let before;
+    let record;
     try {
-        before = statSync(target);
+        record = store.get(root, id);
     }
     catch {
         return { ok: false, reason: "absent" };
     }
-    if (!before.isFile()) {
+    if (record === undefined) {
         return { ok: false, reason: "absent" };
     }
-    if (before.size > MEMORY_FILE_PREVIEW_LIMIT) {
+    // Unreachable today: bodies are schema-capped at 64KB, far below the 5 MiB
+    // preview limit — kept so the day the limit shrinks, the endpoint stays honest.
+    /* v8 ignore next 3 */
+    if (record.body.length > MEMORY_FILE_PREVIEW_LIMIT) {
         return { ok: false, reason: "too-large" };
     }
-    let content;
+    return { ok: true, id: record.id, content: record.body, updatedAtMs: Date.parse(record.updatedAt) || 0 };
+}
+/** The workspace rows the card lists: active partitions whose directory survives. */
+export function listCardWorkspaces(store) {
     try {
-        content = readFileSync(target, "utf8");
+        return store
+            .listWorkspaces()
+            .filter((workspace) => existsSync(workspace.workspaceId))
+            .map((workspace) => ({ root: workspace.workspaceId, label: basename(workspace.workspaceId) }));
     }
     catch {
-        return { ok: false, reason: "absent" };
+        return [];
     }
-    // The file may have been rewritten between stat and read — surface that
-    // instead of silently showing stale bytes (same guard shape as ZCode's
-    // memory viewer's "changed during read" state).
-    const after = statSync(target);
-    return { ok: true, file, content, mtimeMs: after.mtimeMs, changed: after.mtimeMs !== before.mtimeMs };
 }
 //# sourceMappingURL=memory-snapshot.js.map

package/lib/memory-tools.d.ts

@@ -0,0 +1,34 @@
+import type { MemoryStore } from "./store.js";
+/** Minimal slice of the host tools service. */
+export interface ToolsService {
+    register(definition: unknown): unknown;
+}
+/** Minimal tool execution context (duck-typed host surface). */
+interface ToolExec {
+    agent?: unknown;
+}
+/** A registered tool definition, exactly as the host's `defineTool` emits. */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    output: {
+        schema: Record<string, unknown>;
+        render(args: unknown, value: {
+            text?: string;
+        }): {
+            type: string;
+            text: string;
+        }[];
+    };
+    execute(args: Record<string, unknown>, exec: ToolExec): Promise<{
+        text: string;
+    }>;
+}
+/**
+ * Register the memory tools and return a disposer that removes them (the
+ * host may return one; call only the functions among whatever comes back).
+ */
+export declare function registerMemoryTools(tools: ToolsService, store: MemoryStore): () => void;
+export {};
+//# sourceMappingURL=memory-tools.d.ts.map

package/lib/memory-tools.js

@@ -0,0 +1,142 @@
+/**
+ * The model-facing memory tools: `memory_write` (the explicit write path
+ * through the store's gates) and `memory_read` (bodies and search — the
+ * injected index carries hooks only).
+ *
+ * The definitions are hand-built to the shape `ctx.tools.register` consumes
+ * (the same object the host's `defineTool` would emit): standard JSON Schema
+ * with a root-level `required` array — the raw-register path forwards
+ * `parameters` to the API verbatim, where property-level `required: true`
+ * is invalid (docs/FAQ.md #2). Host API shapes are declared locally, per the
+ * architecture standard; the plugin imports nothing from DSH at runtime.
+ */
+import { cwdOf } from "./memory-section.js";
+function textTool(name, description, parameters, execute) {
+    return {
+        name,
+        description,
+        parameters,
+        output: {
+            schema: {
+                type: "object",
+                properties: { text: { type: "string", description: "结果说明" } },
+                required: ["text"],
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
+        },
+        execute: async (args, exec) => ({ text: await execute(args, exec) }),
+    };
+}
+/** The calling agent's session id (provenance for the ledger). */
+function sessionIdOf(exec) {
+    const id = exec?.agent?.id;
+    return typeof id === "string" && id.length > 0 ? id : undefined;
+}
+const MEMORY_WRITE_PARAMETERS = {
+    type: "object",
+    properties: {
+        action: {
+            type: "string",
+            enum: ["create", "update", "delete"],
+            description: "create 新建记忆；update 更新已有条目（只给要改的字段）；delete 删除条目。",
+        },
+        id: {
+            type: "string",
+            description: "短横线小写标识（kebab slug）。update/delete 必填；create 可省略（从 title 推导，中文标题会得到哈希后缀）。",
+        },
+        type: {
+            type: "string",
+            enum: ["user", "feedback", "reference"],
+            description: "记忆类型：user 用户画像与环境事实；feedback 用户纠正/确认的做法规则（正文必带 **Why:** 与 **How to apply:** 两行）；reference 未来会用的资源指针。",
+        },
+        title: { type: "string", description: "短标题（create 必填）。" },
+        description: {
+            type: "string",
+            description: "一句话相关性钩子——决定未来会话会不会想起这条记忆（create 必填）。",
+        },
+        body: { type: "string", description: "正文（create 必填；update 时传新正文整体替换）。" },
+    },
+    required: ["action"],
+    additionalProperties: false,
+};
+const MEMORY_READ_PARAMETERS = {
+    type: "object",
+    properties: {
+        id: { type: "string", description: "按 id 直取一条记忆的完整内容。" },
+        query: { type: "string", description: "关键词检索（不传 id 时生效；不传 query 则列出最近记忆）。" },
+        limit: { type: "number", description: "检索/列出的最大条数，默认 3，上限 10。" },
+    },
+    additionalProperties: false,
+};
+/**
+ * Register the memory tools and return a disposer that removes them (the
+ * host may return one; call only the functions among whatever comes back).
+ */
+export function registerMemoryTools(tools, store) {
+    const disposers = [];
+    disposers.push(tools.register(textTool("memory_write", "写入持久记忆（create 新建 / update 更新 / delete 删除）。用户明确要求记住或忘记时使用；记忆按当前工作区分区存储，由插件代码校验后落库。", MEMORY_WRITE_PARAMETERS, async (args, exec) => {
+        const cwd = cwdOf(exec.agent);
+        if (cwd === undefined) {
+            return "错误：当前会话没有可用的工作区路径，无法写入记忆。";
+        }
+        const [outcome] = store.applyProposals({ workspaceId: cwd, trigger: "explicit", sessionId: sessionIdOf(exec) }, [
+            {
+                action: args.action,
+                id: typeof args.id === "string" ? args.id : undefined,
+                type: typeof args.type === "string" ? args.type : undefined,
+                title: typeof args.title === "string" ? args.title : undefined,
+                description: typeof args.description === "string" ? args.description : undefined,
+                body: typeof args.body === "string" ? args.body : undefined,
+            },
+        ]);
+        if (outcome === undefined || !outcome.ok) {
+            return `写入被门禁拒绝，记忆未落盘：${outcome?.reason ?? "未知原因"}`;
+        }
+        if (outcome.action === "delete") {
+            return `已删除记忆 \`${outcome.id}\`。旧内容保留在审计账本中，可由用户恢复。`;
+        }
+        return `已${outcome.action === "create" ? "写入" : "更新"}记忆 \`${outcome.id}\`（本工作区）。下次会话的注入索引会包含它。`;
+    })));
+    disposers.push(tools.register(textTool("memory_read", "读取持久记忆：按 id 取一条的完整正文，或按关键词检索本工作区的记忆（注入的索引只有钩子，需要正文时用它）。", MEMORY_READ_PARAMETERS, async (args, exec) => {
+        const cwd = cwdOf(exec.agent);
+        if (cwd === undefined) {
+            return "错误：当前会话没有可用的工作区路径，无法读取记忆。";
+        }
+        const limit = clampLimit(args.limit);
+        if (typeof args.id === "string" && args.id.length > 0) {
+            const record = store.get(cwd, args.id);
+            return record === undefined ? `没有找到 id 为 "${args.id}" 的记忆。` : formatRecord(record);
+        }
+        const query = typeof args.query === "string" ? args.query : "";
+        const records = query.length > 0 ? store.search(cwd, query, limit) : store.list(cwd).slice(0, limit);
+        if (records.length === 0) {
+            return query.length > 0 ? `没有匹配 "${query}" 的记忆。` : "本工作区还没有记忆。";
+        }
+        return records.map(formatRecord).join("\n\n---\n\n");
+    })));
+    return () => {
+        for (const disposer of disposers) {
+            if (typeof disposer === "function") {
+                disposer();
+            }
+        }
+    };
+}
+function clampLimit(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return 3;
+    }
+    return Math.min(10, Math.max(1, Math.floor(value)));
+}
+/** Full record text: header line, then the body the index omitted. */
+function formatRecord(record) {
+    return [
+        `# ${record.title}`,
+        `id: ${record.id} ｜ 类型: ${record.type} ｜ 状态: ${record.status} ｜ 更新: ${record.updatedAt}`,
+        `钩子: ${record.description}`,
+        "",
+        record.body,
+    ].join("\n");
+}
+//# sourceMappingURL=memory-tools.js.map

package/lib/store-apply.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The transactional heart of the sole write path: validate every proposal,
+ * apply all of them inside one transaction, ledger each mutation with its
+ * before/after snapshot, and roll the whole batch back when any proposal
+ * fails. Explicit tool writes and extraction runs land through this same
+ * gate — there is no other writer.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import { type MemoryProposal } from "./memory-rules.js";
+import type { LedgerEntry } from "./store.js";
+/** What a single proposal produced. */
+export interface ProposalOutcome {
+    id: string;
+    action: MemoryProposal["action"];
+    ok: boolean;
+    /** Blocking reason when `ok` is false. */
+    reason?: string;
+}
+/** The write context every proposal batch carries (provenance + accounting). */
+export interface ProposalContext {
+    workspaceId: string;
+    trigger: LedgerEntry["trigger"];
+    /** Origin session (stored on created rows and ledger rows). */
+    sessionId?: string | undefined;
+    /** Extraction run id; tool writes default to `'explicit'`. */
+    runId?: string | undefined;
+    model?: string | undefined;
+    usage?: unknown;
+    /** One-line model decision summary for the ledger. */
+    decision?: string | undefined;
+}
+/** Minimal database face `applyProposals` needs (store.ts hands the real one). */
+export interface ApplyDatabase {
+    database: DatabaseSync;
+    now(): string;
+}
+/**
+ * Validate and apply the whole batch atomically. A batch with any invalid
+ * proposal mutates nothing and still lands a `rejected` ledger row; an
+ * applied batch lands an `applied` row with full before/after snapshots.
+ */
+export declare function applyProposals(db: ApplyDatabase, ctx: ProposalContext, proposals: readonly MemoryProposal[]): {
+    outcomes: ProposalOutcome[];
+    applied: boolean;
+};
+//# sourceMappingURL=store-apply.d.ts.map