@sigrun/ext-curator 0.0.0-stage → 0.1.0

package/dist/steps/targets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The targets step (`src/steps/targets.ts`, Task B4 — loop 2 step
+ * `targets`, the pass's LAST step): run each maintain-capable curation
+ * target's maintenance hook through `host.curation.maintain`, handing
+ * it the tick's deadline and the REMAINING daily digest runs (the
+ * budget the five model steps did not spend — the brief: "within the
+ * remaining budget").
+ *
+ * The step itself spends nothing — the target's own `run` calls are
+ * budgeted by the `runs` count it receives (one digest run each, per
+ * the P6 contract), and a target that reports `more` keeps the rest for
+ * the next pass. A failing target is logged and never blocks the others.
+ */
+import { type ModelStepDeps } from "./run.js";
+/** The loop-2 targets step: maintain every maintain-capable target. */
+export declare function maintainTargets(deps: ModelStepDeps): Promise<boolean>;

package/dist/steps/targets.js

@@ -0,0 +1,42 @@
+/**
+ * The targets step (`src/steps/targets.ts`, Task B4 — loop 2 step
+ * `targets`, the pass's LAST step): run each maintain-capable curation
+ * target's maintenance hook through `host.curation.maintain`, handing
+ * it the tick's deadline and the REMAINING daily digest runs (the
+ * budget the five model steps did not spend — the brief: "within the
+ * remaining budget").
+ *
+ * The step itself spends nothing — the target's own `run` calls are
+ * budgeted by the `runs` count it receives (one digest run each, per
+ * the P6 contract), and a target that reports `more` keeps the rest for
+ * the next pass. A failing target is logged and never blocks the others.
+ */
+import { stepLog } from "./run.js";
+/** The loop-2 targets step: maintain every maintain-capable target. */
+export async function maintainTargets(deps) {
+    const { host, user } = deps;
+    const log = stepLog(deps);
+    if (deps.budget.left() < 1)
+        return false; // nothing to hand a target: stop
+    const targets = await host.curation.targets(user);
+    for (const target of targets) {
+        if (!target.maintain)
+            continue;
+        if (deps.now().getTime() >= deps.deadlineAt)
+            return false;
+        await host.curation
+            .maintain(user, target.id, {
+            deadline: deps.deadlineAt,
+            runs: deps.budget.left(),
+        })
+            .then((report) => {
+            if (report.more) {
+                log(`loop 2: target ${target.id} stopped early — the next pass continues it`);
+            }
+        })
+            .catch((error) => {
+            log(`loop 2: ${user} maintain of target ${target.id} failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    return true;
+}

package/dist/view.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The curator view (`src/view.ts`, Task B5): the per-user surface the
+ * notice navigates to — learned skills (name, description, last used,
+ * pin toggle, archive/restore), overlays (orphaned flag), the change
+ * feed (newest 50) grouped by review with an **Undo review** action,
+ * and a pause switch.
+ *
+ * Access follows `accessOf` (spec P8: "the user, plus the superuser as
+ * with conversations"): the resource is the caller's OWN curation data,
+ * so a signed-in user is its owner ("write") and an anonymous caller
+ * has no instance at all ("none" — accessOf's ownerless rule would
+ * otherwise widen to household write, so the anonymous case is gated by
+ * hand). Every render and action resolves the CALLING principal's own
+ * stores — bob's instance reads bob's data, never alice's — and the
+ * per-principal `instanceKey` keeps two users' views apart as surface
+ * instances.
+ *
+ * The actions (what an ambient record can never carry — a view's action
+ * routes DO reach the extension). Per-item actions ride the block
+ * set's item-scoped dispatches, which carry `{itemId}` (a card action
+ * button's submit dispatches a `null` payload — it cannot name an
+ * item, `onCheck`/`onActivate` can):
+ *
+ * - `pin` — the skills collection's `checkable`/`onCheck`:
+ *   `{itemId: skill, value}` → the skill store's `pin`;
+ * - `toggleArchive` — the skills collection's `onActivate`
+ *   (`{itemId: skill}`): reads the store's current state and archives
+ *   or restores through `apply` (feed-recorded, undoable);
+ * - `undoReview` — the feed collection's `onActivate`
+ *   (`{itemId: reviewId}`): `host.curation.undoReview`, then
+ *   `host.clearAmbient` on the notice conversation's `curator.notice`
+ *   slot (the notice ledger in `src/notices.ts` remembers it);
+ * - `setPaused` — the page header's pause button (a submit dispatching
+ *   `{}`): toggles the user's `paused` setting, read live by both
+ *   loops — pausing takes effect on the next event, restart-free.
+ *
+ * The tree is data-driven where the block set binds (item templates
+ * over literal rows); the whole tree passes the server's own
+ * `validateTree` (pinned in the tests) because the server runs that
+ * exact walk before serving.
+ */
+import type { CurationFeedEntry, Principal, SigrunHost, SurfaceDef } from "@sigrun/sigrun/extension";
+import type { Access } from "@sigrun/shared/access";
+/** How many feed entries the view lists (the brief: newest 50). */
+export declare const VIEW_FEED_LIMIT = 50;
+/** One grouped review block in the feed (newest first). */
+export interface ReviewGroup {
+    readonly id: string;
+    readonly at: string;
+    readonly entries: readonly {
+        readonly id: string;
+        readonly skill: string;
+        readonly action: string;
+        readonly at: string;
+        readonly reason?: string;
+    }[];
+}
+/** The view's data document (everything the tree binds against). */
+export interface CuratorViewData {
+    readonly user: string;
+    readonly paused: boolean;
+    readonly skills: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly description: string;
+        readonly archived: boolean;
+        readonly pinned: boolean;
+        readonly lastUsedLabel: string;
+    }[];
+    readonly overlays: readonly {
+        readonly id: string;
+        readonly skill: string;
+        readonly root: string;
+        readonly orphaned: boolean;
+    }[];
+    readonly reviews: readonly ReviewGroup[];
+}
+/**
+ * Resolve one principal's access to their per-user view instance (spec
+ * P8: "the user, plus the superuser as with conversations"): the
+ * resource is the principal's OWN curation data, so a signed-in user is
+ * its owner (write) and the service principal the superuser (write);
+ * an anonymous caller has no instance at all — accessOf's ownerless
+ * rule would widen to household write, so anonymous is none BY HAND.
+ */
+export declare function viewAccess(principal: Principal, user: string): Access;
+/** Group a feed by review: entries sharing a reviewId form one group
+ *  (the feed's newest-first order preserved, outside and inside). An
+ *  entry with no reviewId (user pins, direct edits) groups alone. */
+export declare function groupFeed(feed: readonly CurationFeedEntry[]): readonly ReviewGroup[];
+/** The view surface (`SurfaceDef<"view">`), built over the host. */
+export declare function createCuratorView(host: SigrunHost): SurfaceDef<"view">;

package/dist/view.js

@@ -0,0 +1,405 @@
+/**
+ * The curator view (`src/view.ts`, Task B5): the per-user surface the
+ * notice navigates to — learned skills (name, description, last used,
+ * pin toggle, archive/restore), overlays (orphaned flag), the change
+ * feed (newest 50) grouped by review with an **Undo review** action,
+ * and a pause switch.
+ *
+ * Access follows `accessOf` (spec P8: "the user, plus the superuser as
+ * with conversations"): the resource is the caller's OWN curation data,
+ * so a signed-in user is its owner ("write") and an anonymous caller
+ * has no instance at all ("none" — accessOf's ownerless rule would
+ * otherwise widen to household write, so the anonymous case is gated by
+ * hand). Every render and action resolves the CALLING principal's own
+ * stores — bob's instance reads bob's data, never alice's — and the
+ * per-principal `instanceKey` keeps two users' views apart as surface
+ * instances.
+ *
+ * The actions (what an ambient record can never carry — a view's action
+ * routes DO reach the extension). Per-item actions ride the block
+ * set's item-scoped dispatches, which carry `{itemId}` (a card action
+ * button's submit dispatches a `null` payload — it cannot name an
+ * item, `onCheck`/`onActivate` can):
+ *
+ * - `pin` — the skills collection's `checkable`/`onCheck`:
+ *   `{itemId: skill, value}` → the skill store's `pin`;
+ * - `toggleArchive` — the skills collection's `onActivate`
+ *   (`{itemId: skill}`): reads the store's current state and archives
+ *   or restores through `apply` (feed-recorded, undoable);
+ * - `undoReview` — the feed collection's `onActivate`
+ *   (`{itemId: reviewId}`): `host.curation.undoReview`, then
+ *   `host.clearAmbient` on the notice conversation's `curator.notice`
+ *   slot (the notice ledger in `src/notices.ts` remembers it);
+ * - `setPaused` — the page header's pause button (a submit dispatching
+ *   `{}`): toggles the user's `paused` setting, read live by both
+ *   loops — pausing takes effect on the next event, restart-free.
+ *
+ * The tree is data-driven where the block set binds (item templates
+ * over literal rows); the whole tree passes the server's own
+ * `validateTree` (pinned in the tests) because the server runs that
+ * exact walk before serving.
+ */
+import { accessOf } from "@sigrun/shared/access";
+import { readNotices } from "./notices.js";
+import { CURATOR_NOTICE_KIND } from "./notices.js";
+import { parseCuratorSettings } from "./settings.js";
+/** How many feed entries the view lists (the brief: newest 50). */
+export const VIEW_FEED_LIMIT = 50;
+/** The zero-signal context the ambient clear runs under. */
+const CONTEXT = { abortSignal: undefined };
+/**
+ * Resolve one principal's access to their per-user view instance (spec
+ * P8: "the user, plus the superuser as with conversations"): the
+ * resource is the principal's OWN curation data, so a signed-in user is
+ * its owner (write) and the service principal the superuser (write);
+ * an anonymous caller has no instance at all — accessOf's ownerless
+ * rule would widen to household write, so anonymous is none BY HAND.
+ */
+export function viewAccess(principal, user) {
+    if (principal.user === undefined)
+        return "none";
+    return accessOf({ user: principal.user, superuser: principal.service }, { owner: user });
+}
+/** Group a feed by review: entries sharing a reviewId form one group
+ *  (the feed's newest-first order preserved, outside and inside). An
+ *  entry with no reviewId (user pins, direct edits) groups alone. */
+export function groupFeed(feed) {
+    const groups = new Map();
+    for (const entry of feed) {
+        const key = entry.reviewId ?? entry.id;
+        const row = {
+            id: entry.id,
+            skill: entry.skill,
+            action: entry.action,
+            at: entry.at,
+            ...(entry.reason === undefined ? {} : { reason: entry.reason }),
+        };
+        const existing = groups.get(key);
+        if (existing === undefined) {
+            groups.set(key, { id: key, at: entry.at, entries: [row] });
+        }
+        else {
+            groups.set(key, { ...existing, entries: [...existing.entries, row] });
+        }
+    }
+    return [...groups.values()];
+}
+/** A human label for one skill's last-used stamp ("never" or the date). */
+function lastUsedLabel(at) {
+    if (at === undefined)
+        return "never";
+    const date = new Date(at);
+    return Number.isNaN(date.getTime()) ? "never" : date.toISOString().slice(0, 10);
+}
+/** Build the view's data document for one user (the render's model). */
+async function readData(host, user) {
+    const settings = parseCuratorSettings(await host.stores.user(user).settings.get());
+    const usage = await host.curation.usage(user);
+    const skills = await host.curation.skills(user).list();
+    const overlays = await host.curation.overlays(user).list();
+    const feed = await host.curation.skills(user).feed(VIEW_FEED_LIMIT);
+    return {
+        user,
+        paused: settings.paused,
+        skills: [...skills]
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((row) => ({
+            id: row.name,
+            name: row.name,
+            description: row.description,
+            archived: row.archived,
+            pinned: row.pinned,
+            lastUsedLabel: lastUsedLabel(usage[row.name]),
+        })),
+        overlays: [...overlays]
+            .map((row) => ({
+            id: row.key.skill,
+            skill: row.key.skill,
+            root: row.key.root,
+            orphaned: row.orphanedSince !== undefined,
+        }))
+            .sort((a, b) => a.skill.localeCompare(b.skill)),
+        reviews: groupFeed(feed),
+    };
+}
+/** Whether `payload` (an action's JSON argument) is a plain object. */
+function isObject(payload) {
+    return typeof payload === "object" && payload !== null && !Array.isArray(payload);
+}
+/** The `{itemId, value}` dispatch an `onCheck` toggle carries. */
+function itemToggle(payload) {
+    if (!isObject(payload))
+        return undefined;
+    const itemId = payload.itemId;
+    const value = payload.value;
+    if (typeof itemId !== "string" || itemId === "")
+        return undefined;
+    if (typeof value !== "boolean")
+        return undefined;
+    return { itemId, value };
+}
+/** The `{itemId}` dispatch an `onActivate` click carries. */
+function itemIdOf(payload) {
+    if (!isObject(payload))
+        return undefined;
+    const itemId = payload.itemId;
+    return typeof itemId === "string" && itemId !== "" ? itemId : undefined;
+}
+/** The view surface (`SurfaceDef<"view">`), built over the host. */
+export function createCuratorView(host) {
+    /** Reject for a caller with no instance of their own. */
+    const noAccess = () => ({
+        ok: false,
+        error: { message: "sign in to use the curator view" },
+    });
+    /** The caller's user, or a reject when they have no instance. */
+    function callerOf(ctx) {
+        const user = ctx.principal.user;
+        if (user === undefined)
+            return { reject: noAccess() };
+        if (viewAccess(ctx.principal, user) === "none")
+            return { reject: noAccess() };
+        return { user };
+    }
+    return {
+        id: "curator",
+        title: "Curator",
+        icon: "book",
+        placement: "view",
+        // A principal-owned surface (§7.3): the principal folds into the
+        // instance identity so two users' views are two instances.
+        instanceKey: (params, principal) => JSON.stringify([principal.user ?? "", params]),
+        render: async (ctx) => {
+            const who = callerOf(ctx);
+            if ("reject" in who) {
+                return { tree: emptyTree(), data: {}, access: "none" };
+            }
+            const data = await readData(host, who.user);
+            return {
+                tree: viewTree(data),
+                // SAFETY: the data document is a JSON mirror (every field a
+                // literal); the interface lacks the index signature JsonObject
+                // requires, so the cast only restores that erased identity.
+                data: data,
+                access: "write",
+            };
+        },
+        data: async (ctx) => {
+            const who = callerOf(ctx);
+            if ("reject" in who)
+                return { data: {}, access: "none" };
+            return {
+                // SAFETY: same JSON-mirror cast as `render`'s (the comment there).
+                data: (await readData(host, who.user)),
+                access: "write",
+            };
+        },
+        actions: {
+            undoReview: async (ctx, payload) => {
+                const who = callerOf(ctx);
+                if ("reject" in who)
+                    return who.reject;
+                const reviewId = itemIdOf(payload);
+                if (reviewId === undefined) {
+                    return { ok: false, error: { message: "undoReview expects {itemId}" } };
+                }
+                const reverted = await host.curation.undoReview(who.user, reviewId);
+                // Clear the notice this review set, when the ledger remembers
+                // one (a digest review with no notice clears nothing).
+                const notice = (await readNotices(host, who.user)).find((entry) => entry.reviewId === reviewId);
+                if (notice !== undefined) {
+                    // The revert already succeeded — a failing clear only leaves a
+                    // stale notice (replaced by the next review's), so it must
+                    // never turn the undo into a failed action with no toast.
+                    await host.clearAmbient(notice.conversationId, CURATOR_NOTICE_KIND, CONTEXT).catch(() => undefined);
+                }
+                return {
+                    ok: true,
+                    toast: reverted > 0 ? `Undid ${reverted} change(s)` : "Nothing to undo",
+                };
+            },
+            pin: async (ctx, payload) => {
+                const who = callerOf(ctx);
+                if ("reject" in who)
+                    return who.reject;
+                const toggle = itemToggle(payload);
+                if (toggle === undefined) {
+                    return { ok: false, error: { message: "pin expects {itemId, value}" } };
+                }
+                await host.curation.skills(who.user).pin(toggle.itemId, toggle.value);
+                return {
+                    ok: true,
+                    toast: toggle.value ? `Pinned ${toggle.itemId}` : `Unpinned ${toggle.itemId}`,
+                };
+            },
+            toggleArchive: async (ctx, payload) => {
+                const who = callerOf(ctx);
+                if ("reject" in who)
+                    return who.reject;
+                const name = itemIdOf(payload);
+                if (name === undefined) {
+                    return { ok: false, error: { message: "toggleArchive expects {itemId}" } };
+                }
+                // The current store state decides the direction: click an
+                // active skill → archive; click an archived one → restore.
+                const row = (await host.curation.skills(who.user).list()).find((skill) => skill.name === name);
+                if (row === undefined) {
+                    return { ok: false, error: { message: `unknown skill: ${name}` } };
+                }
+                const change = row.archived
+                    ? { kind: "restore" }
+                    : { kind: "archive" };
+                await host.curation
+                    .skills(who.user)
+                    .apply(name, change, { reason: `${change.kind === "archive" ? "archived" : "restored"} from the curator view` });
+                return {
+                    ok: true,
+                    toast: change.kind === "archive" ? `Archived ${name}` : `Restored ${name}`,
+                };
+            },
+            setPaused: async (ctx, payload) => {
+                const who = callerOf(ctx);
+                if ("reject" in who)
+                    return who.reject;
+                // The header button dispatches `{}` (toggle); a form-shaped
+                // `{values: {paused}}` or bare `{paused}` sets explicitly.
+                const explicit = (isObject(payload) && isObject(payload.values)
+                    ? payload.values.paused
+                    : undefined) ??
+                    (isObject(payload) ? payload.paused : undefined);
+                const raw = await host.stores.user(who.user).settings.get();
+                const current = parseCuratorSettings(raw).paused;
+                const paused = typeof explicit === "boolean" ? explicit : !current;
+                if (paused === current) {
+                    return { ok: true, toast: paused ? "Curation paused" : "Curation resumed" };
+                }
+                await host.stores.user(who.user).settings.set({ ...raw, paused });
+                return {
+                    ok: true,
+                    toast: paused ? "Curation paused" : "Curation resumed",
+                };
+            },
+        },
+    };
+}
+/** The signed-out/none-access tree (an empty page; the route 404s it). */
+function emptyTree() {
+    return {
+        v: 1,
+        root: {
+            type: "page",
+            title: "Curator",
+            main: [
+                { type: "markdown", text: "Sign in to see your curator activity." },
+            ],
+        },
+    };
+}
+/** The view tree: header with the pause switch, skills, overlays, feed. */
+function viewTree(data) {
+    return {
+        v: 1,
+        root: {
+            type: "page",
+            id: "curator-root",
+            title: "Curator",
+            subtitle: `Learned activity for ${data.user}${data.paused ? " (paused)" : ""}`,
+            actions: [
+                {
+                    id: "pause-switch",
+                    label: data.paused ? "Resume curation" : "Pause curation",
+                    icon: data.paused ? "sun" : "moon",
+                    action: { type: "submit", name: "setPaused" },
+                },
+            ],
+            main: [
+                {
+                    type: "section",
+                    id: "skills-section",
+                    title: "Learned skills",
+                    children: [
+                        {
+                            type: "markdown",
+                            text: "Toggle the checkbox to pin or unpin. Click a skill to archive it; click an archived one to restore.",
+                        },
+                        {
+                            type: "collection",
+                            id: "skills",
+                            display: "list",
+                            items: data.skills,
+                            checkable: "pinned",
+                            onCheck: "pin",
+                            onActivate: { type: "edit", name: "toggleArchive" },
+                            item: {
+                                title: { $: "./name" },
+                                subtitle: { $: "./description" },
+                                body: { $: "./lastUsedLabel" },
+                                badges: [
+                                    { text: "pinned", tone: "good" },
+                                    { text: "archived", tone: "neutral" },
+                                ],
+                            },
+                        },
+                    ],
+                },
+                {
+                    type: "section",
+                    id: "overlays-section",
+                    title: "Overlays",
+                    children: [
+                        data.overlays.length === 0
+                            ? {
+                                type: "markdown",
+                                text: "No overlays on upstream skills.",
+                            }
+                            : {
+                                type: "collection",
+                                id: "overlays",
+                                display: "list",
+                                items: data.overlays,
+                                item: {
+                                    title: { $: "./skill" },
+                                    subtitle: { $: "./root" },
+                                    badges: [{ text: "orphaned", tone: "warn" }],
+                                },
+                            },
+                    ],
+                },
+                {
+                    type: "section",
+                    id: "feed-section",
+                    title: "Change feed (newest 50, grouped by review)",
+                    children: [
+                        {
+                            type: "markdown",
+                            text: "Click a review to undo every change it made.",
+                        },
+                        data.reviews.length === 0
+                            ? {
+                                type: "markdown",
+                                text: "Nothing learned yet. Use /learn to ask for a review now.",
+                            }
+                            : {
+                                type: "collection",
+                                id: "reviews",
+                                display: "list",
+                                items: data.reviews.map((group) => ({
+                                    id: group.id,
+                                    at: group.at,
+                                    summary: group.entries
+                                        .map((entry) => `${entry.action} ${entry.skill}`)
+                                        .join(", "),
+                                })),
+                                onActivate: { type: "edit", name: "undoReview" },
+                                item: {
+                                    title: { $: "./id" },
+                                    subtitle: { $: "./summary" },
+                                    meta: [{ time: { $: "./at" }, format: "relative" }],
+                                },
+                            },
+                    ],
+                },
+            ],
+        },
+    };
+}

package/package.json

@@ -1,6 +1,56 @@
 {
-  "name": "@sigrun/ext-curator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@sigrun/ext-curator",
+	"version": "0.1.0",
+	"description": "Curator extension for sigrun (pi-durable): the per-user fork review and idle maintenance pass over learned skills and curation targets",
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"test": "node scripts/check-manifest.mjs --expect-name @sigrun/ext-curator && vitest run",
+		"typecheck": "tsc --noEmit",
+		"build": "tsc -p tsconfig.build.json",
+		"prepublishOnly": "npm run build"
+	},
+	"peerDependencies": {
+		"@earendil-works/chord": "1.3.0 || 1.4.0",
+		"@earendil-works/pi-ai": "1.3.0 || 1.4.0",
+		"@earendil-works/pi-durable": "1.3.0 || 1.4.0"
+	},
+	"devDependencies": {
+		"@earendil-works/chord": "1.4.0",
+		"@earendil-works/pi-ai": "1.4.0",
+		"@earendil-works/pi-durable": "1.4.0",
+		"@sigrun/sigrun": "file:../sigrun",
+		"@sigrun/shared": "file:../sigrun/shared",
+		"@types/node": "^26.6.4",
+		"tsx": "^4.23.15",
+		"typescript": "^7.0.2",
+		"vitest": "^5.0.3"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "github",
+		"url": "git+https://github.com/sigrun-ai/sigrun-ext-curator.git"
+	},
+	"bugs": {
+		"url": "https://github.com/sigrun-ai/sigrun-ext-curator/issues"
+	},
+	"homepage": "https://github.com/sigrun-ai/sigrun-ext-curator#readme",
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	}
+}