dsh-continual-evolve 0.15.4 → 0.15.6

package/lib/index.d.ts

@@ -9,8 +9,10 @@
  *
  * - the session-start section (`memory-section.ts`): a store query rendered
  *   as the injected index, frozen per session for the prompt cache;
- * - the model tools (`memory-tools.ts`): `memory_write` for explicit
- *   "记住/忘掉" instructions, `memory_read` for bodies and search;
+ * - the model tools (`memory-tools.ts`, `skill-tools.ts`): `memory_write`
+ *   for explicit "记住/忘掉" instructions, `memory_read` for bodies and
+ *   search, plus `skill_write` (project-only creation, manual move to
+ *   global) and `skill_read` (project shadowing global);
  * - the extraction scheduler (`extraction.ts`): turn-level, per-session
  *   slots, single-flight per session; proposals land only through the
  *   store's gates;

package/lib/index.js

@@ -9,8 +9,10 @@
  *
  * - the session-start section (`memory-section.ts`): a store query rendered
  *   as the injected index, frozen per session for the prompt cache;
- * - the model tools (`memory-tools.ts`): `memory_write` for explicit
- *   "记住/忘掉" instructions, `memory_read` for bodies and search;
+ * - the model tools (`memory-tools.ts`, `skill-tools.ts`): `memory_write`
+ *   for explicit "记住/忘掉" instructions, `memory_read` for bodies and
+ *   search, plus `skill_write` (project-only creation, manual move to
+ *   global) and `skill_read` (project shadowing global);
  * - the extraction scheduler (`extraction.ts`): turn-level, per-session
  *   slots, single-flight per session; proposals land only through the
  *   store's gates;
@@ -31,6 +33,7 @@ import { mountCardRoutes } from "./card-routes.js";
 import { createExtractionScheduler } from "./extraction.js";
 import { createFrozenMemorySection, cwdOf, DEFAULT_MAX_CHARS, DEFAULT_MEMORY_SECTION_ORDER, MEMORY_SECTION_NAME, memorySectionText, } from "./memory-section.js";
 import { registerMemoryTools } from "./memory-tools.js";
+import { registerSkillTools } from "./skill-tools.js";
 import { importWorkspaceMd } from "./import-md.js";
 import { openMemoryStore } from "./store.js";
 import { newestRegistryPath } from "./workspace-hint.js";
@@ -80,8 +83,10 @@ function mountToolsWhenAvailable(host, store, state) {
             return;
         }
         registerMemoryTools(tools, store);
+        registerSkillTools(tools, store);
         state.toolsAvailable = true;
         host.logger("continual-evolve").info("memory_write and memory_read registered");
+        host.logger("continual-evolve").info("skill_write and skill_read registered");
     });
 }
 /**

package/lib/memory-snapshot.d.ts

@@ -1,4 +1,4 @@
-import { MEMORY_FILE_PREVIEW_LIMIT, type MemoryStore } from "./store.js";
+import { MEMORY_FILE_PREVIEW_LIMIT, type MemoryStore, type ReviewSummary } from "./store.js";
 export { MEMORY_FILE_PREVIEW_LIMIT };
 /** One memory row the card renders. */
 export interface MemoryFileInfo {
@@ -32,6 +32,8 @@ export interface MemorySnapshot {
         orphanFtsRows: number;
         quarantined: number;
     } | null;
+    /** Review-loop audit over the workspace's extraction ledger (zeros when none). */
+    review: ReviewSummary;
 }
 /**
  * The read-only snapshot for one workspace partition. A workspace without
@@ -63,4 +65,60 @@ export declare function listCardWorkspaces(store: MemoryStore): {
     root: string;
     label: string;
 }[];
+/** One skill row the card renders (scope resolved: project shadows global). */
+export interface SkillFileInfo {
+    id: string;
+    title: string;
+    description: string;
+    /** `project` or `global` — which partition the row was read from. */
+    scope: string;
+    /** Row status; quarantined rows render in the patrol section, not here. */
+    status: string;
+    /** Update time in epoch milliseconds (the card's "updated" line). */
+    updatedAt: number;
+    /** Bodies served by id (V2 usage loop); 0 when never consumed. */
+    useCount: number;
+    /** Last consumption in epoch milliseconds, `null` when never consumed. */
+    lastUsedAt: number | null;
+}
+/** The full read-only skill snapshot the card renders for one workspace root. */
+export interface SkillSnapshot {
+    root: string;
+    exists: boolean;
+    /** Set when the store query failed; null otherwise. */
+    readError: string | null;
+    /** Active row count (the number the card's stats line shows). */
+    fileCount: number;
+    /** Active rows, project first (the list the card renders). */
+    files: SkillFileInfo[];
+    /** Rows quarantined by patrol — displayed as 巡检异常, never in the list. */
+    quarantined: {
+        id: string;
+        scope: string;
+        reason: string;
+    }[];
+}
+/**
+ * The read-only skill snapshot for one workspace partition. Mirrors the
+ * memory snapshot's degrade contract: unknown partitions read `exists:
+ * false`, failing queries report `readError` instead of throwing.
+ */
+export declare function skillSnapshot(store: MemoryStore, root: string): SkillSnapshot;
+/** The content endpoint's outcomes for one skill body. */
+export type SkillEntryContent = {
+    ok: true;
+    id: string;
+    scope: string;
+    content: string;
+    updatedAtMs: number;
+} | {
+    ok: false;
+    reason: "absent" | "too-large";
+};
+/**
+ * Read one skill's body for the card's content preview — project shadowing
+ * global, keyed by id, never by file name. Bodies are schema-capped at 64KB,
+ * so `too-large` is dead code kept for the day the preview limit shrinks.
+ */
+export declare function skillEntryContent(store: MemoryStore, root: string, id: string): SkillEntryContent;
 //# sourceMappingURL=memory-snapshot.d.ts.map

package/lib/memory-snapshot.js

@@ -8,7 +8,8 @@
  */
 import { existsSync } from "node:fs";
 import { basename } from "node:path";
-import { MEMORY_FILE_PREVIEW_LIMIT } from "./store.js";
+import { MEMORY_FILE_PREVIEW_LIMIT, zeroReviewSummary } from "./store.js";
+import { skillUsagePartition } from "./skill-rules.js";
 export { MEMORY_FILE_PREVIEW_LIMIT };
 /**
  * The read-only snapshot for one workspace partition. A workspace without
@@ -26,6 +27,7 @@ export function memorySnapshot(store, root) {
         files: [],
         quarantined: [],
         lastPatrol: null,
+        review: zeroReviewSummary(),
     };
     let all;
     try {
@@ -64,8 +66,17 @@ export function memorySnapshot(store, root) {
             .filter((record) => record.status === "quarantined")
             .map((record) => ({ id: record.id, reason: quarantineReasonOf(store, record) })),
         lastPatrol,
+        review: reviewOf(store, workspaceRoot),
     };
 }
+function reviewOf(store, root) {
+    try {
+        return store.reviewSummary(root);
+    }
+    catch {
+        return zeroReviewSummary();
+    }
+}
 function infoOf(record) {
     return {
         id: record.id,
@@ -127,13 +138,123 @@ export function memoryEntryContent(store, root, id) {
 /** The workspace rows the card lists: active partitions whose directory survives. */
 export function listCardWorkspaces(store) {
     try {
-        return store
-            .listWorkspaces()
-            .filter((workspace) => existsSync(workspace.workspaceId))
-            .map((workspace) => ({ root: workspace.workspaceId, label: basename(workspace.workspaceId) }));
+        const seen = new Set();
+        const rows = [];
+        // One fence for every card route: partitions holding memories or
+        // skills. A skills-only workspace lists (its memory snapshot reads
+        // empty); global skills ride along with whichever workspace is open.
+        for (const workspace of [...store.listWorkspaces(), ...store.listSkillWorkspaces()]) {
+            if (workspace.workspaceId === "" || seen.has(workspace.workspaceId)) {
+                continue;
+            }
+            seen.add(workspace.workspaceId);
+            if (!existsSync(workspace.workspaceId)) {
+                continue;
+            }
+            rows.push({ root: workspace.workspaceId, label: basename(workspace.workspaceId) });
+        }
+        return rows;
     }
     catch {
         return [];
     }
 }
+/** Project-first merge of one partition's skills with the global scope. */
+function scopedSkills(store, root) {
+    const seen = new Set();
+    const merged = [];
+    for (const record of store.listAllSkills(root)) {
+        if (seen.has(record.id)) {
+            continue;
+        }
+        seen.add(record.id);
+        merged.push({ record, scope: "project" });
+    }
+    for (const record of store.listAllSkills("")) {
+        if (seen.has(record.id)) {
+            continue;
+        }
+        seen.add(record.id);
+        merged.push({ record, scope: "global" });
+    }
+    return merged;
+}
+function skillInfoOf(store, entry) {
+    let useCount = 0;
+    let lastUsedAt = null;
+    try {
+        const use = store.getSkillUse(skillUsagePartition(entry.scope, entry.record.workspaceId), entry.record.id, entry.scope);
+        if (use !== undefined) {
+            useCount = use.useCount;
+            lastUsedAt = use.lastUsedAt === null ? null : Date.parse(use.lastUsedAt) || 0;
+        }
+    }
+    catch {
+        // Usage is decoration: the snapshot degrades to zeros, never throws.
+    }
+    return {
+        id: entry.record.id,
+        title: entry.record.title,
+        description: entry.record.description,
+        scope: entry.scope,
+        status: entry.record.status,
+        updatedAt: Date.parse(entry.record.updatedAt) || 0,
+        useCount,
+        lastUsedAt,
+    };
+}
+/**
+ * The read-only skill snapshot for one workspace partition. Mirrors the
+ * memory snapshot's degrade contract: unknown partitions read `exists:
+ * false`, failing queries report `readError` instead of throwing.
+ */
+export function skillSnapshot(store, root) {
+    const absent = { root, exists: false, readError: null, fileCount: 0, files: [], quarantined: [] };
+    let entries;
+    try {
+        entries = scopedSkills(store, root);
+        if (entries.length === 0) {
+            return absent;
+        }
+    }
+    catch (error) {
+        return { ...absent, exists: true, readError: error instanceof Error ? error.message : String(error) };
+    }
+    return {
+        root,
+        exists: true,
+        readError: null,
+        fileCount: entries.filter((entry) => entry.record.status === "active").length,
+        files: entries.filter((entry) => entry.record.status === "active").map((entry) => skillInfoOf(store, entry)),
+        quarantined: entries
+            .filter((entry) => entry.record.status === "quarantined")
+            .map((entry) => ({ id: entry.record.id, scope: entry.scope, reason: quarantineReasonOf(store, entry.record) })),
+    };
+}
+/**
+ * Read one skill's body for the card's content preview — project shadowing
+ * global, keyed by id, never by file name. Bodies are schema-capped at 64KB,
+ * so `too-large` is dead code kept for the day the preview limit shrinks.
+ */
+export function skillEntryContent(store, root, id) {
+    if (id.length === 0) {
+        return { ok: false, reason: "absent" };
+    }
+    let entries;
+    try {
+        entries = scopedSkills(store, root);
+    }
+    catch {
+        return { ok: false, reason: "absent" };
+    }
+    const hit = entries.find((entry) => entry.record.id === id);
+    if (hit === undefined) {
+        return { ok: false, reason: "absent" };
+    }
+    /* v8 ignore next 3 */
+    if (hit.record.body.length > MEMORY_FILE_PREVIEW_LIMIT) {
+        return { ok: false, reason: "too-large" };
+    }
+    return { ok: true, id: hit.record.id, scope: hit.scope, content: hit.record.body, updatedAtMs: Date.parse(hit.record.updatedAt) || 0 };
+}
 //# sourceMappingURL=memory-snapshot.js.map

package/lib/skill-rules.d.ts

@@ -0,0 +1,79 @@
+import { isValidMemoryId, slugifyId } from "./memory-rules.js";
+export { isValidMemoryId as isValidSkillId, slugifyId as slugifySkillId };
+/** Skill scopes: project rows live in their workspace partition, global rows in `""`. */
+export declare const SKILL_SCOPES: readonly ["project", "global"];
+export type SkillScope = (typeof SKILL_SCOPES)[number];
+/** The global partition id (shared with the memory store's global state rows). */
+export declare const SKILL_GLOBAL_WORKSPACE = "";
+/** Max rendered frontmatter description length (loaders truncate anyway). */
+export declare const MAX_SKILL_DESCRIPTION_LENGTH = 240;
+/**
+ * Marker carried by every materialized file, right after the frontmatter.
+ * Patrol only touches files carrying it — hand-written skills in the same
+ * directories are never rewritten or removed.
+ */
+export declare const SKILL_GENERATED_MARKER = "<!-- generated by dsh-continual-evolve \u2014 the central store is the source of truth; edit via skill_write, manual edits are reverted by patrol -->";
+/** One proposed skill mutation — the closed shape the write paths speak. */
+export interface SkillProposal {
+    action: "create" | "update" | "delete" | "move-to-global";
+    /** Required for update/delete/move-to-global; optional for create (derived from title). */
+    id?: string | undefined;
+    /** Which partition update/delete targets. Create always lands in the project. */
+    scope?: string | undefined;
+    title?: string | undefined;
+    description?: string | undefined;
+    body?: string | undefined;
+    /** Trajectory provenance ("820-831"), kept for parity with memory proposals. */
+    sourceSeqs?: string | undefined;
+}
+/** The merged field values a create/update would write (delete checks none). */
+export interface SkillFields {
+    title: string;
+    description: string;
+    body: string;
+}
+/**
+ * Gates that depend only on the merged field values (not on store state).
+ * Runs the secret screen over the full visible text so a secret smuggled
+ * into any field blocks the write.
+ */
+export declare function skillFieldGateReasons(fields: SkillFields): string[];
+/**
+ * Render a skill as a discoverable SKILL.md document. The frontmatter
+ * description carries a routing hint — title plus the first meaningful body
+ * line — instead of the bare title: the skill catalog matches on
+ * description, and a title-only description gives loaders nothing to route
+ * on.
+ */
+export declare function renderSkillMarkdown(skill: {
+    id: string;
+    title: string;
+    description: string;
+    body: string;
+}): string;
+/**
+ * Mechanical problems that would make the platform's skill loader ignore the
+ * rendered file. The file is still written, but the caller surfaces these:
+ * a silently ignored skill is worse than a noisy one.
+ */
+export declare function validateRenderedSkill(skill: {
+    id: string;
+    description: string;
+}): string[];
+/** Where project skills materialize: the workspace's own discovered skill directory. */
+export declare function projectSkillsDir(workspaceId: string): string;
+/** Where global skills materialize: the host-wide discovered skill directory. */
+export declare function globalSkillsDir(): string;
+/**
+ * The store partition a skill scope reads and writes usage in: the global
+ * partition for global rows, the workspace itself otherwise. One function
+ * so the tool, card, and snapshot paths cannot drift apart.
+ */
+export declare function skillUsagePartition(scope: string, cwd: string): string;
+/**
+ * Resolve and defend the materialized directory for a skill id. Ids are
+ * kebab slugs by gate, but the containment check stays: a caller bug must
+ * never turn a skill write into a write elsewhere.
+ */
+export declare function skillDir(root: string, id: string): string;
+//# sourceMappingURL=skill-rules.d.ts.map

package/lib/skill-rules.js

@@ -0,0 +1,166 @@
+/**
+ * The mechanical write gates every skill passes before the store accepts it
+ * — the same "模型提议，代码保证" boundary as memories, minus the
+ * taxonomy: skills carry no type enum and no feedback body contract. Both
+ * entry points (the explicit `skill_write` tool and the manual move to the
+ * global scope) funnel through these checks; nothing reaches the database or
+ * the materialized files without them.
+ *
+ * File rendering follows the previously validated shape (pre-teardown
+ * `skill-render.ts`, itself checked against the platform loader): YAML-ish
+ * frontmatter (`name` + `description` carrying a routing hint) over the body.
+ * The official skill-creator template is no longer shipped locally, so the
+ * live host preset skills (same frontmatter contract) are the format anchor.
+ */
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { isValidMemoryId, MEMORY_BODY_LIMIT, MEMORY_DESCRIPTION_LIMIT, MEMORY_TITLE_LIMIT, secretLeakReason, slugifyId, } from "./memory-rules.js";
+export { isValidMemoryId as isValidSkillId, slugifyId as slugifySkillId };
+/** Skill scopes: project rows live in their workspace partition, global rows in `""`. */
+export const SKILL_SCOPES = ["project", "global"];
+/** The global partition id (shared with the memory store's global state rows). */
+export const SKILL_GLOBAL_WORKSPACE = "";
+/** Max rendered frontmatter description length (loaders truncate anyway). */
+export const MAX_SKILL_DESCRIPTION_LENGTH = 240;
+/**
+ * Marker carried by every materialized file, right after the frontmatter.
+ * Patrol only touches files carrying it — hand-written skills in the same
+ * directories are never rewritten or removed.
+ */
+export const SKILL_GENERATED_MARKER = "<!-- generated by dsh-continual-evolve — the central store is the source of truth; edit via skill_write, manual edits are reverted by patrol -->";
+/**
+ * Gates that depend only on the merged field values (not on store state).
+ * Runs the secret screen over the full visible text so a secret smuggled
+ * into any field blocks the write.
+ */
+export function skillFieldGateReasons(fields) {
+    const reasons = [];
+    if (fields.title.trim().length === 0) {
+        reasons.push("title must not be empty");
+    }
+    else if (fields.title.length > MEMORY_TITLE_LIMIT) {
+        reasons.push(`title exceeds ${MEMORY_TITLE_LIMIT} characters`);
+    }
+    if (fields.description.trim().length === 0) {
+        reasons.push("description must not be empty — it is the skill trigger");
+    }
+    else if (fields.description.length > MEMORY_DESCRIPTION_LIMIT) {
+        reasons.push(`description exceeds ${MEMORY_DESCRIPTION_LIMIT} characters`);
+    }
+    if (fields.body.trim().length === 0) {
+        reasons.push("body must not be empty");
+    }
+    else if (fields.body.length > MEMORY_BODY_LIMIT) {
+        reasons.push(`body exceeds the ${MEMORY_BODY_LIMIT}-character cap`);
+    }
+    const leak = secretLeakReason(`${fields.title}\n${fields.description}\n${fields.body}`);
+    if (leak !== undefined) {
+        reasons.push(leak);
+    }
+    return reasons;
+}
+/** Collapse prose to one line for the frontmatter description. */
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/**
+ * First content line usable as a routing hint: non-empty, not a Markdown
+ * heading, not a list marker, not frontmatter. Undefined when the body is
+ * effectively empty.
+ */
+function routingHint(body) {
+    for (const rawLine of body.split("\n")) {
+        const line = rawLine.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith("#") || line.startsWith("---") || line.startsWith("-") || line.startsWith("*"))
+            continue;
+        return oneLine(line);
+    }
+    return undefined;
+}
+/**
+ * Render a skill as a discoverable SKILL.md document. The frontmatter
+ * description carries a routing hint — title plus the first meaningful body
+ * line — instead of the bare title: the skill catalog matches on
+ * description, and a title-only description gives loaders nothing to route
+ * on.
+ */
+export function renderSkillMarkdown(skill) {
+    const hint = routingHint(skill.body);
+    const stated = oneLine(skill.description);
+    const base = oneLine(skill.title);
+    // Prefer the author's own description; fall back to title + hint exactly
+    // like the pre-teardown renderer so re-materialized rows stay byte-stable.
+    let description;
+    if (stated.length > 0) {
+        description = stated;
+    }
+    else if (base.length === 0) {
+        description = (hint ?? "").slice(0, MAX_SKILL_DESCRIPTION_LENGTH);
+    }
+    else if (hint !== undefined && !base.toLowerCase().includes(hint.toLowerCase())) {
+        description = `${base} — use when: ${hint}`.slice(0, MAX_SKILL_DESCRIPTION_LENGTH);
+    }
+    else {
+        description = base.slice(0, MAX_SKILL_DESCRIPTION_LENGTH);
+    }
+    return ["---", `name: ${skill.id}`, `description: ${description}`, "---", "", SKILL_GENERATED_MARKER, "", skill.body.trim(), ""].join("\n");
+}
+/**
+ * Mechanical problems that would make the platform's skill loader ignore the
+ * rendered file. The file is still written, but the caller surfaces these:
+ * a silently ignored skill is worse than a noisy one.
+ */
+export function validateRenderedSkill(skill) {
+    const problems = [];
+    if (!isValidMemoryId(skill.id)) {
+        problems.push(`name "${skill.id}" is not kebab-case — the platform ignores the file`);
+    }
+    const description = oneLine(skill.description);
+    if (description.length === 0) {
+        problems.push("empty description — the catalog has nothing to route on");
+    }
+    else if (description.length > MAX_SKILL_DESCRIPTION_LENGTH) {
+        problems.push(`description exceeds ${MAX_SKILL_DESCRIPTION_LENGTH} characters — loaders truncate it`);
+    }
+    if (/[\r\n]/.test(skill.description)) {
+        problems.push("description spans lines — frontmatter must stay one line");
+    }
+    return problems;
+}
+/** The DSH home the global skills directory lives under (same rule as the store path). */
+function dshHome() {
+    const home = process.env.DSH_HOME?.trim();
+    return home !== undefined && home.length > 0 ? home : join(homedir(), ".dsh");
+}
+/** Where project skills materialize: the workspace's own discovered skill directory. */
+export function projectSkillsDir(workspaceId) {
+    return join(workspaceId, ".agents", "skills");
+}
+/** Where global skills materialize: the host-wide discovered skill directory. */
+export function globalSkillsDir() {
+    return join(dshHome(), "skills");
+}
+/**
+ * The store partition a skill scope reads and writes usage in: the global
+ * partition for global rows, the workspace itself otherwise. One function
+ * so the tool, card, and snapshot paths cannot drift apart.
+ */
+export function skillUsagePartition(scope, cwd) {
+    return scope === "global" ? SKILL_GLOBAL_WORKSPACE : cwd;
+}
+/**
+ * Resolve and defend the materialized directory for a skill id. Ids are
+ * kebab slugs by gate, but the containment check stays: a caller bug must
+ * never turn a skill write into a write elsewhere.
+ */
+export function skillDir(root, id) {
+    const base = resolve(root);
+    const dir = resolve(join(base, id));
+    if (dir !== base && !dir.startsWith(`${base}/`) && !dir.startsWith(`${base}${sep}`)) {
+        throw new Error(`skill path escapes skills root: ${dir}`);
+    }
+    return dir;
+}
+//# sourceMappingURL=skill-rules.js.map

package/lib/skill-tools.d.ts

@@ -0,0 +1,9 @@
+import type { MemoryStore } from "./store.js";
+import type { ToolsService, ToolDefinition } from "./memory-tools.js";
+export type { ToolsService, ToolDefinition };
+/**
+ * Register the skill tools and return a disposer that removes them (the
+ * host may return one; call only the functions among whatever comes back).
+ */
+export declare function registerSkillTools(tools: ToolsService, store: MemoryStore): () => void;
+//# sourceMappingURL=skill-tools.d.ts.map