@sigrun/sigrun 0.4.2 → 0.6.0

package/dist/curation/host.js

@@ -0,0 +1,342 @@
+/**
+ * The curation host (curator P6, A9): `host.curation` — the
+ * extension-facing surface over everything Part A built.
+ *
+ * ONE object per boot, constructed in boot (where the per-user stores,
+ * the curation registry, the jobs records and the harness live) and
+ * exposed three ways: on the `OpenedHarness` (tests and server-side
+ * callers), on the host bridge (`HostBridge.curation` — the
+ * server-owned handle), and on every seam host (`SeamHost.curation`,
+ * delegating to the bridge, the same lazy-bind discipline as
+ * `conversations`).
+ *
+ * Read members (eligibility, authors, modelCallsSince, takeHints,
+ * targets, tools, skills, overlays, upstream, jobSkillRefs, usage) are
+ * thin reads over the A1–A8 primitives. The run producers (forkReview,
+ * digestRun, maintain) delegate to the run driver (runs.ts). The store
+ * subsets (`skills`, `overlays`) are the REAL per-user stores narrowed
+ * to the documented members — never a re-implementation.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { AssistantEntry } from "@earendil-works/pi-durable";
+import { authorsOfEntries } from "./attribution.js";
+import { takeHints } from "./wrap.js";
+import { digestRunRun, forkReviewRun, setChangeTargetResolver } from "./runs.js";
+import { resolveUpstream } from "./overlays.js";
+import { jobSkillRefs } from "../jobs/skills-refs.js";
+import { SessionMetaDoc } from "../server/session-meta.js";
+/** modelCallsSince's entry-page size (cursor-walked, never a cap). */
+const MODEL_CALLS_PAGE = 500;
+/** Scan bound for the cursor walk: a broken cursor loops, a count does not. */
+const MODEL_CALLS_SCAN_LIMIT = 10_000;
+/** Build the one curation host (boot constructs exactly one). */
+export function createCurationHost(deps) {
+    const { harness, registry, curation } = deps;
+    // The change-target resolver: the registry's qualified ids, with the
+    // core skills store owning `skill_manage` (no target declares it).
+    setChangeTargetResolver((tool) => {
+        if (tool === "skill_manage")
+            return "sigrun.skills";
+        return curation.byTool(tool)?.id ?? `tool:${tool}`;
+    });
+    /** The conversation handle (loud when the id is unknown). */
+    const conversationOf = async (id, ctx) => {
+        const conversation = await harness.conversation(id, ctx);
+        if (conversation === undefined) {
+            throw new Error(`conversation ${id} not found`);
+        }
+        return conversation;
+    };
+    /** The per-user store pair (loud when the user is absent). */
+    const storesOf = (user) => {
+        const stores = deps.stores(user);
+        if (stores === undefined) {
+            throw new Error(`unknown user "${user}" — no curation stores`);
+        }
+        return stores;
+    };
+    /**
+     * The digest producer `maintain`'s budget hands the target: one
+     * digest run for the SAME user, bounded to the listed tools, with
+     * the remaining wall clock as the deadline.
+     */
+    const digestFor = async (user, input, tools, deadline) => {
+        const remaining = Math.max(1, deadline - Date.now());
+        return await digestRunRun({ harness, registry }, user, {
+            instruction: input,
+            allow: tools,
+            maxToolCalls: 8,
+            maxOutputTokens: 16_000,
+            deadlineMs: remaining,
+            reviewId: `digest-${Date.now()}-${Math.floor(Math.random() * 1e6)}`,
+            input,
+        }, deps.defaultModel, deps.defaultAgent);
+    };
+    const host = {
+        async eligibility(id) {
+            const meta = await harness.snapshot(SessionMetaDoc, id, BACKGROUND_CONTEXT);
+            const conversation = await conversationOf(id, BACKGROUND_CONTEXT);
+            const page = await conversation.entries({}, 1, undefined, BACKGROUND_CONTEXT);
+            // The same map `authors` serves: eligibility is its aggregate view.
+            const authors = await host.authors(id);
+            let unattributed = 0;
+            let ownerOnly = true;
+            for (const [, author] of authors) {
+                if (author === undefined) {
+                    unattributed += 1;
+                    ownerOnly = false;
+                    continue;
+                }
+                if (author !== meta?.owner)
+                    ownerOnly = false;
+            }
+            return {
+                ...(meta?.owner === undefined ? {} : { owner: meta.owner }),
+                internal: meta?.internal === true,
+                ownerOnly,
+                unattributed,
+                ...(page.items[0]?.id === undefined
+                    ? {}
+                    : { newestEntry: page.items[0].id }),
+            };
+        },
+        async authors(id) {
+            return await authorsOfEntries(harness, id, BACKGROUND_CONTEXT);
+        },
+        async modelCallsSince(id, entryId) {
+            const conversation = await conversationOf(id, BACKGROUND_CONTEXT);
+            // Oldest-first from the anchor: `minEntryId` is an INCLUSIVE
+            // bound, so the anchor itself rides the first page and is
+            // filtered below — the count is the assistant entries STRICTLY
+            // after the anchor (the extension.ts contract). No anchor:
+            // the whole history.
+            const query = entryId === undefined
+                ? { order: "ascending" }
+                : { minEntryId: entryId, order: "ascending" };
+            // Cursor-complete walk (the feedOf pattern): pages until
+            // exhaustion so a long conversation never silently truncates,
+            // bounded so a cursor bug cannot loop forever.
+            let count = 0;
+            let scanned = 0;
+            let cursor;
+            for (;;) {
+                const page = await conversation.entries(query, MODEL_CALLS_PAGE, cursor, BACKGROUND_CONTEXT);
+                for (const entry of page.items) {
+                    scanned += 1;
+                    if (entry.kind !== AssistantEntry.kind)
+                        continue;
+                    if (entryId !== undefined && entry.id === entryId)
+                        continue;
+                    count += 1;
+                }
+                if (page.next === undefined ||
+                    page.items.length === 0 ||
+                    scanned >= MODEL_CALLS_SCAN_LIMIT) {
+                    break;
+                }
+                cursor = page.next;
+            }
+            return count;
+        },
+        async takeHints(id) {
+            const conversation = await conversationOf(id, BACKGROUND_CONTEXT);
+            return await takeHints(conversation, BACKGROUND_CONTEXT);
+        },
+        async targets(user, id) {
+            // The selection filter: a target is served for a conversation
+            // only when EVERY listed tool is model-visible in that
+            // conversation's resolved agent. No id: every target.
+            const visible = id === undefined ? undefined : await modelVisibleTools(id);
+            const result = [];
+            for (const target of curation.targets()) {
+                if (visible !== undefined) {
+                    if (target.tools.some((tool) => !visible.has(tool)))
+                        continue;
+                }
+                const guidance = await target.guidance(user);
+                if (guidance.length === 0)
+                    continue;
+                result.push({
+                    id: target.id,
+                    tools: [...target.tools],
+                    guidance: [...guidance],
+                    maintain: target.maintain !== undefined,
+                });
+            }
+            return result;
+        },
+        async tools(id) {
+            const visible = await modelVisibleTools(id);
+            return [...visible];
+        },
+        async forkReview(id, opts) {
+            return await forkReviewRun({ harness, registry }, id, opts);
+        },
+        async digestRun(user, opts) {
+            return await digestRunRun({ harness, registry }, user, opts, deps.defaultModel, deps.defaultAgent);
+        },
+        async maintain(user, targetId, budget) {
+            const target = curation
+                .targets()
+                .find((one) => one.id === targetId);
+            if (target === undefined) {
+                throw new Error(`unknown curation target "${targetId}"`);
+            }
+            if (target.maintain === undefined) {
+                throw new Error(`curation target "${targetId}" declares no maintain`);
+            }
+            // The budget's run: one digest run for the SAME user, bounded
+            // to the listed tools (the target asks for operations as text
+            // and applies them itself — the P6 contract).
+            const digestBudget = {
+                deadline: budget.deadline,
+                runs: budget.runs,
+                run: (input, tools) => digestFor(user, input, tools, budget.deadline),
+            };
+            const ctx = { abortSignal: undefined };
+            return await target.maintain(user, ctx, digestBudget);
+        },
+        skills(user) {
+            const { store } = storesOf(user);
+            return {
+                list: () => store.list(),
+                view: (name, file) => store.view(name, file),
+                feed: (limit, before) => store.feed(limit, before),
+                pin: (name, pinned) => store.pin(name, pinned),
+                undo: (entryIds) => store.undo(entryIds),
+                apply: (name, change, meta) => store.apply(name, change, {
+                    actor: "curator",
+                    ...(meta.reviewId === undefined
+                        ? {}
+                        : { reviewId: meta.reviewId }),
+                    ...(meta.reason === undefined ? {} : { reason: meta.reason }),
+                }),
+            };
+        },
+        overlays(user) {
+            const { overlays } = storesOf(user);
+            return overlays;
+        },
+        async upstream(user, key) {
+            // The upstream read is user-independent (the skill roots are
+            // the host's); the user gate only proves a real curated user.
+            storesOf(user);
+            return await resolveUpstream(key, undefined, BACKGROUND_CONTEXT, {
+                userDir: deps.skillsOptions.userDir,
+                packageRoots: deps.skillsOptions.packageRoots,
+            });
+        },
+        async jobSkillRefs(user) {
+            return await jobSkillRefs(deps.storage, user, BACKGROUND_CONTEXT);
+        },
+        async undoReview(user, reviewId) {
+            const { store } = storesOf(user);
+            const entries = await feedOf(store, reviewId);
+            // The store undo: entries with a `before` version snapshot are
+            // the revertible ones; the store's own undo takes entry ids
+            // and restores the snapshots (the A4 machinery).
+            // Hand EVERY review feed entry to the store's undo: edit entries
+            // restore their before-snapshot, create entries (before ===
+            // undefined) archive the skill — the no-delete revert the A4
+            // store owns. The store itself ignores ids it cannot revert.
+            let reverted = 0;
+            if (entries.length > 0) {
+                const undone = await store.undo(entries.map((entry) => entry.id));
+                reverted = undone.length;
+            }
+            // The target undos: every change the review's TARGET tools
+            // reported. The feed only carries the core stores' entries;
+            // a target-owned change's id is the `details.curation`
+            // changeId the tool reported, which the caller (the run
+            // result's `changes`) holds — undoReview walks the RUN
+            // conversation's tool results for them.
+            await undoTargetChanges(user, reviewId);
+            return reverted;
+        },
+        async usage(user) {
+            const { usage, store } = storesOf(user);
+            const skills = await store.list();
+            const result = {};
+            for (const skill of skills) {
+                result[skill.name] = usage.lastUsed(skill.name);
+            }
+            return result;
+        },
+    };
+    return host;
+    /** The conversation's model-visible tool names. */
+    async function modelVisibleTools(id) {
+        const conversation = await conversationOf(id, BACKGROUND_CONTEXT);
+        const agent = await conversation.agent(BACKGROUND_CONTEXT);
+        return new Set(agent.tools.map((tool) => tool.name));
+    }
+    /** The feed entries one review caused (newest-first walk). */
+    async function feedOf(store, reviewId) {
+        const found = [];
+        let before;
+        for (;;) {
+            const page = await store.feed(100, before);
+            if (page.length === 0)
+                break;
+            for (const entry of page) {
+                if (entry.reviewId === reviewId)
+                    found.push(entry);
+            }
+            before = page[page.length - 1]?.id;
+            if (page.length < 100)
+                break;
+        }
+        return found;
+    }
+    /**
+     * Undo the target-owned changes one review caused: find the run
+     * conversation by its run doc (`reviewId`), walk its tool results
+     * for `details.curation` changeIds, and hand each to the owning
+     * target's `undo` with the curated user.
+     */
+    async function undoTargetChanges(user, reviewId) {
+        const runId = await runConversationOf(reviewId);
+        if (runId === undefined)
+            return;
+        const conversation = await harness.conversation(runId, BACKGROUND_CONTEXT);
+        if (conversation === undefined)
+            return;
+        const page = await conversation.entries({ order: "ascending" }, 500, undefined, BACKGROUND_CONTEXT);
+        for (const entry of page.items) {
+            if (entry.kind !== "pi.tool-result")
+                continue;
+            for (const message of entry.model ?? []) {
+                if (message.role !== "toolResult")
+                    continue;
+                // SAFETY: the tool-result details carry the A6/A8
+                // `details.curation` shape ({changeId, summary}); the
+                // structural read below only touches those two fields.
+                const details = message.details;
+                const change = details?.curation;
+                if (change === undefined)
+                    continue;
+                const target = curation.byTool(message.toolName);
+                if (target === undefined)
+                    continue;
+                await target.undo(user, change.changeId, { abortSignal: undefined });
+            }
+        }
+    }
+    /** The run conversation carrying one reviewId (or undefined). */
+    async function runConversationOf(reviewId) {
+        const { CurationRunDoc } = await import("./run-doc.js");
+        let cursor;
+        for (;;) {
+            const page = await deps.storage.scanConversations({ order: "descending" }, 50, cursor, BACKGROUND_CONTEXT);
+            for (const record of page.items) {
+                const run = await harness.snapshot(CurationRunDoc, record.id, BACKGROUND_CONTEXT);
+                if (run?.reviewId === reviewId)
+                    return record.id;
+            }
+            if (page.next === undefined)
+                return undefined;
+            cursor = page.next;
+        }
+    }
+}
+;

package/dist/curation/internal.js

@@ -0,0 +1,54 @@
+/**
+ * Internal runs (curator P5, spec §6.1): conversations created for curator
+ * work are invisible on every owner-keyed path.
+ *
+ * The marker is the server-owned `SessionMeta.internal: true`, stamped by
+ * {@link markInternal} in the conversation's CREATING commit — alongside
+ * the curated user as `owner`, so the env, the acting user, and the
+ * target tools resolve to them. The flag never changes after creation
+ * (there is no writer besides the creating commit), which every consumer
+ * may rely on for caching.
+ *
+ * Host paths that check it (each hidden from internal conversations):
+ * the HTTP listing, the host bridge's `conversations.list`, the `:id`
+ * route loader (404 for every caller, superuser included), the SSE
+ * per-principal event stream, the notifications surface, the auto-namer,
+ * and the event bus's idle clock, `run.settled` host emit, and extension
+ * `runSettled`/lifecycle delivery.
+ *
+ * Internal conversations are NOT purged: pi-durable 1.4.0 has no
+ * conversation deletion, and a fork reads its parent's history through
+ * ancestry, so each review costs only its own turn's rows. Backup copies
+ * the whole database; nothing per-conversation can be excluded (accepted
+ * per spec §6.1 P5 — the audit record is the change feed).
+ */
+import { SessionMetaDoc } from "../server/session-meta.js";
+/**
+ * Mark one conversation internal and owned by `owner`, in the creating
+ * commit: the P6 fork-review/digest producers call this from
+ * `createConversation`'s `init` (the conversation's first commit, so the
+ * marker predates every observer). Stamps `owner` too — the curated user
+ * the run acts for.
+ */
+export async function markInternal(tx, conversationId, owner) {
+    const meta = await tx.doc(SessionMetaDoc, conversationId);
+    meta.owner = owner;
+    meta.internal = true;
+}
+/**
+ * Whether one conversation is internal, from any `DocumentReader`
+ * (including the narrowed reader an extension handler receives). Absent
+ * doc or absent flag → false: an ordinary conversation is the default,
+ * and a read failure must never hide an ordinary conversation from its
+ * owner (fail open on the LISTING side only; the emit-side gates live in
+ * the event bus, which resolves once per settle group and caches).
+ */
+export async function isInternal(read, conversationId, ctx) {
+    try {
+        const meta = await read.snapshot(SessionMetaDoc, conversationId, ctx);
+        return meta?.internal === true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/curation/names.js

@@ -0,0 +1,5 @@
+const SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+/** Skill names are also their directory names: reject, never normalize. */
+export function validSkillName(name) {
+    return SKILL_NAME.test(name);
+}