@sigrun/sigrun 0.4.2 → 0.5.0

package/dist/curation/overlays.js

@@ -0,0 +1,325 @@
+/**
+ * Overlays (curator P2 part 2, spec §6.2): a per-user addendum attached
+ * to a skill the user does NOT own — a workspace, user-dir or package
+ * skill. The upstream keeps flowing (updates, reinstalls); the overlay
+ * rides on top: `load_skill` and `/skill:name` serve the upstream body
+ * followed by the overlay text under {@link OVERLAY_HEADING}, and the
+ * skills section lists the skill once, unchanged.
+ *
+ * Keying: root kind + skill name, plus the canonical workspace path for
+ * workspace skills (two workspaces can each own a skill of the same
+ * name). An overlay NEVER applies to a learned skill — the user owns
+ * that copy outright, so the store is the right tool (put throws).
+ *
+ * Storage: `curationDir/overlays/<root>/<sha256-of-key>.json`, one file
+ * per overlay (`Overlay` verbatim). A vanished upstream stops serving
+ * but the overlay is KEPT, marked `orphanedSince` by
+ * {@link OverlayStore.markOrphans} (present again clears the mark), and
+ * removable.
+ *
+ * Every overlay change is recorded in the SAME per-user change feed the
+ * {@link SkillStore} owns (A4): an entry with action `"overlay"` (the
+ * union member exists for exactly this), appended through the store's
+ * feed seam so retention and the per-user lock hold. The feed is the
+ * audit record and the P8 view's data; `OverlayStore` owns the files.
+ */
+import { randomUUID, createHash } from "node:crypto";
+import { lstat, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { curationDir, learnedSkillsDir } from "./paths.js";
+import { validSkillName } from "./names.js";
+/**
+ * The heading the served overlay follows: upstream body, then this
+ * heading, then the overlay text (one blank line each side of the
+ * heading).
+ */
+export const OVERLAY_HEADING = "## Your notes for this skill";
+/** Directory label per root kind (no spaces in path segments). */
+const ROOT_DIR = {
+    "workspace": "workspace",
+    "user dir": "user-dir",
+    "package": "package",
+};
+const ROOT_ORDER = ["workspace", "user dir", "package"];
+/**
+ * The canonical key encoding: stable field order, `workspace` omitted
+ * for non-workspace keys. This is the input hashed into the file name —
+ * never change it silently (a change orphans every stored overlay).
+ */
+function keyString(key) {
+    return JSON.stringify({
+        root: key.root,
+        skill: key.skill,
+        ...(key.workspace === undefined ? {} : { workspace: key.workspace }),
+    });
+}
+/** sha256 hex of the key encoding — the overlay's file name stem. */
+function keyHash(key) {
+    return createHash("sha256").update(keyString(key)).digest("hex");
+}
+/** Validate a key on every store operation: a valid name, and a workspace path exactly for workspace keys. */
+function checkKey(key) {
+    if (!validSkillName(key.skill))
+        throw new Error(`invalid skill name: ${key.skill}`);
+    if (key.root === "workspace" && (key.workspace === undefined || key.workspace === "")) {
+        throw new Error("a workspace overlay requires the workspace path");
+    }
+    if (key.root !== "workspace" && key.workspace !== undefined) {
+        throw new Error("the workspace path is only valid for a workspace overlay");
+    }
+}
+/** sha256 hex of the upstream SKILL.md bytes. */
+export function hashSkill(body) {
+    return createHash("sha256").update(body, "utf8").digest("hex");
+}
+/**
+ * The served shape: the upstream body, then {@link OVERLAY_HEADING},
+ * then the overlay text — one blank line each side of the heading.
+ */
+export function withOverlay(body, text) {
+    return `${body}\n${OVERLAY_HEADING}\n\n${text}`;
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function writeFileAtomic(path, text) {
+    await mkdir(join(path, ".."), { recursive: true });
+    const temp = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temp, text);
+    await rename(temp, path);
+}
+/**
+ * The per-user overlay store: files under
+ * `curationDir/overlays/<root>/<sha256-of-key>.json`, every change
+ * recorded in the skill store's feed as an `"overlay"` entry.
+ */
+export class OverlayStore {
+    options;
+    root;
+    constructor(options) {
+        this.options = options;
+        this.root = curationDir(options.userArea);
+    }
+    /** The one overlay for a key, `undefined` when none is stored. */
+    async get(key) {
+        this.requireUser();
+        checkKey(key);
+        return this.read(this.fileOf(key));
+    }
+    /**
+     * Create or replace the overlay for a key (the upstream hash pins
+     * what the text was written against; drift detection is the caller's
+     * job — `resolveUpstream` + `markOrphans`). Throws for a learned
+     * skill: the user owns that copy, so the store is the right tool.
+     * Returns the feed entry the change recorded.
+     */
+    async put(key, text, upstreamHash, meta) {
+        this.requireUser();
+        checkKey(key);
+        if (await exists(join(learnedSkillsDir(this.options.userArea), key.skill))) {
+            throw new Error(`an overlay never applies to a learned skill: ${key.skill}`);
+        }
+        const overlay = { key, text, upstreamHash };
+        await writeFileAtomic(this.fileOf(key), `${JSON.stringify(overlay, null, 2)}\n`);
+        return this.appendFeed(key, meta, meta.reason ?? "overlay written");
+    }
+    /** Remove the overlay for a key; returns the feed entry. Throws when none is stored. */
+    async remove(key, meta) {
+        this.requireUser();
+        checkKey(key);
+        const file = this.fileOf(key);
+        if (!(await exists(file)))
+            throw new Error(`unknown overlay: ${keyString(key)}`);
+        await rm(file);
+        return this.appendFeed(key, meta, meta.reason ?? "overlay removed");
+    }
+    /** Every stored overlay (present upstreams and orphans alike), sorted by root then name. */
+    async list() {
+        this.requireUser();
+        const result = [];
+        for (const root of ROOT_ORDER) {
+            const dir = join(this.root, "overlays", ROOT_DIR[root]);
+            let entries = [];
+            try {
+                entries = (await readdir(dir)).filter((entry) => entry.endsWith(".json"));
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+            for (const entry of entries.sort()) {
+                const overlay = await this.read(join(dir, entry));
+                if (overlay !== undefined)
+                    result.push(overlay);
+            }
+        }
+        return result;
+    }
+    /**
+     * Mark every overlay whose upstream is absent (per `present`) with
+     * `orphanedSince: now`, and CLEAR the mark when the upstream is back
+     * (the overlay resumes serving). `present` receives each stored key.
+     */
+    async markOrphans(present, now) {
+        this.requireUser();
+        for (const overlay of await this.list()) {
+            const here = present(overlay.key);
+            if (here && overlay.orphanedSince === undefined)
+                continue;
+            if (!here && overlay.orphanedSince !== undefined)
+                continue;
+            const next = here
+                ? { key: overlay.key, text: overlay.text, upstreamHash: overlay.upstreamHash }
+                : { key: overlay.key, text: overlay.text, upstreamHash: overlay.upstreamHash, orphanedSince: overlay.orphanedSince ?? now };
+            await writeFileAtomic(this.fileOf(overlay.key), `${JSON.stringify(next, null, 2)}\n`);
+        }
+    }
+    requireUser() {
+        if (!this.options.userExists())
+            throw new Error("user removed");
+    }
+    fileOf(key) {
+        return join(this.root, "overlays", ROOT_DIR[key.root], `${keyHash(key)}.json`);
+    }
+    /** Read one overlay file; `undefined` on ENOENT (none stored). */
+    async read(path) {
+        let text;
+        try {
+            text = await readFile(path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+        const value = JSON.parse(text);
+        if (typeof value.key?.root !== "string" ||
+            typeof value.key.skill !== "string" ||
+            typeof value.text !== "string" ||
+            typeof value.upstreamHash !== "string") {
+            throw new Error(`corrupt overlay file: ${path}`);
+        }
+        return {
+            key: value.key,
+            text: value.text,
+            upstreamHash: value.upstreamHash,
+            ...(typeof value.orphanedSince === "string" ? { orphanedSince: value.orphanedSince } : {}),
+        };
+    }
+    /** Record one overlay change in the skill store's feed (the `"overlay"` action). */
+    async appendFeed(key, meta, summary) {
+        const entry = {
+            id: randomUUID(),
+            at: new Date().toISOString(),
+            actor: meta.actor,
+            action: "overlay",
+            skill: key.skill,
+            reason: summary,
+            ...(meta.reviewId === undefined ? {} : { reviewId: meta.reviewId }),
+            ...(meta.conversationId === undefined ? {} : { conversationId: meta.conversationId }),
+        };
+        await this.options.feed.appendFeedEntry(entry);
+        return entry;
+    }
+}
+/**
+ * The CURRENT upstream SKILL.md for a key, read from its own root —
+ * core-side discovery: the workspace root through the conversation env
+ * (or the key's workspace path from the host filesystem), the user dir
+ * and the package roots through `opts`. `undefined` when the upstream
+ * is absent (vanished — the caller marks orphans).
+ *
+ * `opts` defaults to an empty user dir and no package roots: a
+ * workspace key needs only the env; a user-dir or package key needs the
+ * caller to hand the roots it discovered under (boot's skills options).
+ */
+export async function resolveUpstream(key, env, ctx, opts) {
+    checkKey(key);
+    const fromText = (text) => ({
+        body: text,
+        hash: hashSkill(text),
+    });
+    if (key.root === "workspace") {
+        // The conversation env sees the workspace the skill was discovered
+        // under; the key's canonical path is the host-side fallback (and
+        // the only route without an env).
+        if (env !== undefined) {
+            const joined = await env.joinPath(["skills", key.skill, "SKILL.md"], ctx);
+            if (joined.ok) {
+                const read = await env.readTextFile(joined.value, ctx);
+                if (read.ok)
+                    return fromText(read.value);
+            }
+        }
+        if (key.workspace !== undefined) {
+            const text = await readHost(join(key.workspace, "skills", key.skill, "SKILL.md"));
+            if (text !== undefined)
+                return fromText(text);
+        }
+        return undefined;
+    }
+    if (key.root === "user dir") {
+        const userDir = opts?.userDir;
+        if (userDir === undefined)
+            return undefined;
+        const text = await readHost(join(userDir, key.skill, "SKILL.md"));
+        return text === undefined ? undefined : fromText(text);
+    }
+    for (const root of opts?.packageRoots?.() ?? []) {
+        const text = await readHost(join(root.dir, key.skill, "SKILL.md"));
+        if (text !== undefined)
+            return fromText(text);
+    }
+    return undefined;
+}
+/** Read one host-local SKILL.md; `undefined` on ENOENT. */
+async function readHost(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * The overlay text to serve for one discovered skill, if any: looks the
+ * skill up in the owner's overlay store and skips orphans. A learned
+ * skill never has one (the store refuses those keys). Exported for the
+ * `/skill:name` expansion, which serves the same shape `load_skill`
+ * does.
+ */
+export async function overlayForSkill(opts, owner, skill, env) {
+    if (skill.root === "learned")
+        return undefined;
+    const store = opts.overlays?.(owner);
+    if (store === undefined)
+        return undefined;
+    // The canonical workspace key (curator A9): the ROOT path, never
+    // `env.cwd` — a conversation whose `pi.agent.cwd` points at a
+    // subdirectory must still see the overlay written against the
+    // workspace root. The root accessor wins when present; the env's
+    // cwd is the pre-A9 fallback (the hermetic single-user boot shape).
+    const workspace = skill.root === "workspace"
+        ? (opts.workspaceRoot?.() ?? env?.cwd)
+        : undefined;
+    const key = {
+        root: skill.root,
+        skill: skill.name,
+        ...(workspace === undefined ? {} : { workspace }),
+    };
+    const overlay = await store.get(key);
+    if (overlay === undefined || overlay.orphanedSince !== undefined)
+        return undefined;
+    return overlay.text;
+}

package/dist/curation/paths.js

@@ -0,0 +1,17 @@
+/**
+ * Curator path helpers (P2): the per-user learned skills root and the
+ * per-user curation state directory, both derived from the managed user
+ * area (`<dataDir>/users/<user>` — `ManagedPaths.userAreas`).
+ *
+ * Pure derivations: no filesystem access, no validation — the sandbox
+ * policy owns creation and the grant validators own admission.
+ */
+import { join } from "node:path";
+/** The owner's learned skills root: `<userArea>/skills`. */
+export function learnedSkillsDir(userArea) {
+    return join(userArea, "skills");
+}
+/** The owner's curation state directory: `<userArea>/curation`. */
+export function curationDir(userArea) {
+    return join(userArea, "curation");
+}

package/dist/curation/run-doc.js

@@ -0,0 +1,64 @@
+/**
+ * The curator run doc (P3/P4, spec §6.3): one conversation-scoped
+ * record identifying an INTERNAL curator run — the conversation A9's
+ * producer creates for a fork review or digest, whose tool calls the
+ * `skill_manage` tool (A6) executes mutating actions under.
+ *
+ * Shape (the A9 producer writes it in the conversation's CREATING
+ * commit, so it predates every observer):
+ *
+ * - `user` — the curated user the run acts FOR. The store user on every
+ *   mutating `skill_manage` action is THIS value, never the calling
+ *   principal (the run's parent may be shared by another user entirely).
+ * - `reviewId` — the review (or digest) the run belongs to.
+ * - `allow` — the action set the run may perform (P6's producer fills
+ *   it; A6 reads it but does not enforce it — A8's wrapper owns the
+ *   tool-level gate).
+ * - `parent` — the reviewed conversation (a fork review's source).
+ * - `viewed` — the read-before-write ledger: skill names the run has
+ *   VIEWED through the tool. `markViewed` appends here through the tool
+ *   call's own `api.commit` (memos are per tool task and die with the
+ *   call, so the ledger must be a durable doc).
+ */
+import { defineDoc } from "@earendil-works/pi-durable";
+/** The `sigrun.curation.run` doc (latest-only singleton per conversation). */
+export const CurationRunDoc = defineDoc({
+    kind: "sigrun.curation.run",
+    version: 1,
+    scope: "conversation",
+    checkpointWhen: () => false,
+    history: "latest",
+    fork: "current",
+    initial: () => ({ user: "", reviewId: "", allow: [], viewed: [] }),
+});
+/**
+ * The run doc of one conversation, from any `DocumentReader` (a tool's
+ * `ToolExecutionApi` carries one). `undefined` when the conversation
+ * carries no run doc — an ordinary conversation, or a run conversation
+ * before the creating commit. Fail closed: a read failure also reads
+ * `undefined` (a mutating action then refuses, never guesses).
+ */
+export async function curationRun(read, conversationId, ctx) {
+    try {
+        return await read.snapshot(CurationRunDoc, conversationId, ctx);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Append one skill name to the run doc's `viewed` ledger, through the
+ * tool call's own `api.commit` — the read-before-write record the
+ * mutating actions check. Idempotent per name; a no-op when the
+ * conversation carries no run doc (nothing to record — `view` outside a
+ * run has no ledger to feed).
+ */
+export async function markViewed(api, name, ctx) {
+    await api.commit(async (tx) => {
+        const doc = await tx.doc(CurationRunDoc, api.conversationId);
+        if (doc.user === "")
+            return;
+        if (!doc.viewed.includes(name))
+            doc.viewed = [...doc.viewed, name];
+    }, ctx);
+}