@sigrun/sigrun 0.4.2 → 0.5.0

package/dist/curation/wrap.js

@@ -0,0 +1,212 @@
+/**
+ * Hints by wrapping (curator P9, spec §6.6): the interception that turns
+ * a curation-tool call outside a curator run into a review hint instead
+ * of a write.
+ *
+ * WHY WRAPPING, NOT A HOOK: a `beforeTool` hook gets a read-only
+ * `HookApi` and cannot commit a hint, and a hook only runs where its
+ * extension is selected. Core instead rewrites the registration of every
+ * curation tool at load, so the interception travels with the tool into
+ * every conversation, whatever its selection, and runs inside
+ * `execute` where `api.commit` exists.
+ *
+ * The wrap oracle is the FEED (`createCurationToolFeed`): a mutable set
+ * of curation tool names that starts with the core set (`skill_manage`)
+ * and grows as the loader validates each extension's `curationTargets`.
+ * Boot wraps the skills extension's tools at its install (the feed's
+ * core entries cover `skill_manage`); the loader wraps any of an
+ * extension's tools whose names are in the feed right before
+ * `registry.install`. The read-side API stays
+ * `CurationRegistry.isCurationTool` (A7) — the feed is only the
+ * write-side wrap oracle, not the registry.
+ *
+ * Wrap semantics (`wrapCurationTool`):
+ *
+ * 1. inside a curator run (`sigrun.curation.run` present) → delegate to
+ *    the original, untouched (the gate — `sigrun.curation-gate` — owns
+ *    the allow enforcement there);
+ * 2. otherwise a MUTATING call never executes. `skill_manage`'s read
+ *    actions (`list`/`view`) pass through — they are safe anywhere. The
+ *    current run's input submissions (LiveDoc's `run.inputs`) are each
+ *    resolved with `authorOfSubmission` and matched against the
+ *    conversation owner: owner present AND every input authored by the
+ *    owner → append to the `sigrun.curation.hints` doc and answer
+ *    "Noted. The curator will review this after your reply."; ANYTHING
+ *    else (a non-owner or unattributed input, an ownerless or runless
+ *    conversation) → "Not recorded: this is only learned from the
+ *    owner's own messages." Neither case executes the original.
+ */
+import { randomUUID } from "node:crypto";
+import { copyJson } from "@earendil-works/chord";
+import { defineDoc, LiveDoc } from "@earendil-works/pi-durable";
+import { authorOfSubmission } from "./attribution.js";
+import { curationRun } from "./run-doc.js";
+import { CORE_CURATION_TOOLS } from "./targets.js";
+import { SessionMetaDoc } from "../server/session-meta.js";
+/** The answer an owner-authored call receives (contract text). */
+export const HINT_NOTED_TEXT = "Noted. The curator will review this after your reply.";
+/** The answer every other call receives (contract text). */
+export const HINT_NOT_RECORDED_TEXT = "Not recorded: this is only learned from the owner's own messages.";
+/**
+ * The `sigrun.curation.hints` doc (latest-only singleton per
+ * conversation): the pending hints the next review of THIS conversation
+ * consumes. `fork: "current"` (the session-meta/authors pattern) — a
+ * fork review (P6) inherits the parent's pending hints, exactly the
+ * transcript it reviews.
+ */
+export const HintsDoc = defineDoc({
+    kind: "sigrun.curation.hints",
+    version: 1,
+    scope: "conversation",
+    checkpointWhen: () => false,
+    history: "latest",
+    fork: "current",
+    initial: () => ({ hints: [] }),
+});
+/** `skill_manage`'s read actions — safe anywhere, never intercepted. */
+const SKILL_MANAGE_READ_ACTIONS = new Set([
+    "list",
+    "view",
+]);
+/**
+ * Whether one call passes through to the original outside a curator
+ * run: only `skill_manage`'s read actions. Every other curation-tool
+ * call is a write intent — the target's listed tools ARE its write
+ * surface, so the action set needs no per-target spelling.
+ */
+function passesThrough(tool, args) {
+    if (tool !== "skill_manage")
+        return false;
+    const action = args?.action;
+    return typeof action === "string" && SKILL_MANAGE_READ_ACTIONS.has(action);
+}
+/** The conversation owner through any document reader (fail-closed). */
+async function ownerOf(api, ctx) {
+    try {
+        return (await api.snapshot(SessionMetaDoc, api.conversationId, ctx))?.owner;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The current run's input submission ids (fail-closed to none). */
+async function liveInputsOf(api, ctx) {
+    try {
+        return (await api.snapshot(LiveDoc, api.conversationId, ctx))?.run?.inputs ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Whether `owner` authored EVERY one of the inputs. An input with no
+ * author record (the pre-write window, or a caller that records none)
+ * resolves `undefined` and fails the check — never a guess. A read
+ * failure also fails (fail closed).
+ */
+async function everyInputOwnerAuthored(api, inputs, owner, ctx) {
+    for (const input of inputs) {
+        let author;
+        try {
+            author = await authorOfSubmission(api, api.conversationId, input, ctx);
+        }
+        catch {
+            author = undefined;
+        }
+        if (author !== owner)
+            return false;
+    }
+    return true;
+}
+/** One text tool result. */
+function text(text) {
+    return { output: [{ type: "text", text }] };
+}
+/**
+ * Wrap one curation tool's registration: byte-identical name, schema,
+ * description and every other field (the spread keeps each reference) —
+ * only `execute` is rewritten, per the wrap semantics in the module
+ * doc. Generic so a typed registration comes back typed.
+ */
+export function wrapCurationTool(tool) {
+    const original = tool.execute;
+    const wrapped = {
+        ...tool,
+        async execute(args, api, context) {
+            // 1. Inside a curator run the original runs untouched (the gate
+            //    owns the allow enforcement; the store user is the run's).
+            const run = await curationRun(api, api.conversationId, context);
+            if (run !== undefined) {
+                return original.call(tool, args, api, context);
+            }
+            // 2. Outside a run: the read actions of `skill_manage` pass
+            //    through; every other call is a write intent that never
+            //    executes.
+            if (passesThrough(tool.name, args)) {
+                return original.call(tool, args, api, context);
+            }
+            const owner = await ownerOf(api, context);
+            // No live run means no owner-authored evidence — the hint needs
+            // inputs, and every one of them authored by the owner.
+            const inputs = await liveInputsOf(api, context);
+            const ownerAuthored = owner !== undefined &&
+                inputs.length > 0 &&
+                (await everyInputOwnerAuthored(api, inputs, owner, context));
+            if (ownerAuthored) {
+                const hint = {
+                    id: randomUUID(),
+                    tool: tool.name,
+                    args: args,
+                    at: new Date().toISOString(),
+                };
+                await api.commit(async (tx) => {
+                    const doc = await tx.doc(HintsDoc, api.conversationId);
+                    doc.hints = [...doc.hints, hint];
+                }, context);
+                return text(HINT_NOTED_TEXT);
+            }
+            return text(HINT_NOT_RECORDED_TEXT);
+        },
+    };
+    return wrapped;
+}
+/**
+ * The wrap feed: the mutable set of curation tool names — the core set
+ * (`skill_manage`) plus every listed target tool the loader validates.
+ * Boot creates the ONE feed and threads it into the loader; the built
+ * `CurationRegistry` (A7) is the read-side view, never this set.
+ */
+export function createCurationToolFeed() {
+    return new Set(CORE_CURATION_TOOLS);
+}
+/**
+ * Wrap every curation-tool registration of one extension in place of
+ * its install. Identity when the feed is absent or names none of the
+ * extension's tools — the untouched object, not a copy, so nothing
+ * downstream observes a swap.
+ */
+export function wrapExtensionCurationTools(extension, feed) {
+    if (feed === undefined)
+        return extension;
+    if (!extension.tools?.some((tool) => feed.has(tool.name)))
+        return extension;
+    return {
+        ...extension,
+        tools: extension.tools.map((tool) => feed.has(tool.name) ? wrapCurationTool(tool) : tool),
+    };
+}
+/**
+ * Read and clear a conversation's hints in ONE commit (the host-side
+ * drain): the hints come out exactly once — the review that takes them
+ * owns them, and a second take reads empty.
+ */
+export async function takeHints(conversation, ctx) {
+    return conversation.commit(async (tx) => {
+        const doc = await tx.doc(HintsDoc, conversation.id);
+        // copyJson INSIDE the callback: the draft's values are tracker
+        // overlays that die with the commit — the caller reads plain JSON.
+        const taken = copyJson(doc.hints);
+        doc.hints = [];
+        return taken;
+    }, ctx);
+}

package/dist/extension.d.ts

@@ -211,6 +211,273 @@ export interface ExtensionWorker {
     /** The work; rejects (or overruns the worker deadline) to fail the run. */
     run(context: HandlerContext, wake?: WorkerWake): Promise<void>;
 }
+/**
+ * The outcome of one curator-run driven call (a fork review or a digest
+ * run): the final text (so a target can ask for operations as text and
+ * apply them itself), the changes its tools reported, and how it ended.
+ */
+export type CurationRunResult = {
+    /** How the run ended: answered, human-cancelled, failed, or deadlined. */
+    readonly status: "completed" | "cancelled" | "failed" | "deadline";
+    /** The run's final assistant text ("" when it produced none). */
+    readonly text: string;
+    /** Changes the run's tools reported, in tool-result order. */
+    readonly changes: readonly {
+        readonly changeId: string;
+        readonly summary: string;
+        /** The qualified target id the change belongs to. */
+        readonly target: string;
+    }[];
+    /** Why a non-completed run ended (the failure/cancellation reason). */
+    readonly error?: string;
+};
+/**
+ * The budget one `maintain` call runs under: a wall-clock deadline, a
+ * digest-run allowance, and the `run` entry point that starts one
+ * bounded internal digest run on the user's curator model and RETURNS
+ * its result (including the final text) — so the target can ask for
+ * operations as text and apply them itself.
+ */
+export interface MaintenanceBudget {
+    /** Wall-clock deadline (epoch ms); work past it is abandoned. */
+    readonly deadline: number;
+    /** Internal runs the target may start (P6 digest runs). */
+    readonly runs: number;
+    /**
+     * Start one internal digest run on the user's curator model, bounded
+     * to the listed tools; resolves with the run's result.
+     */
+    run(input: string, tools: readonly string[]): Promise<CurationRunResult>;
+}
+/** One change a maintenance pass reports, undoable through `undo`. */
+export type MaintenanceReport = {
+    /** Changes made, each undoable through the target's `undo`. */
+    readonly changes: readonly {
+        readonly changeId: string;
+        readonly summary: string;
+    }[];
+    /** True when the target stopped early and wants the next pass. */
+    readonly more?: boolean;
+};
+/**
+ * One curation target (the curator contract, spec P7): an extension's
+ * writable per-user surface the curator learns into. The `tools` list is
+ * the interception surface — every LISTED tool call outside a curator
+ * run becomes a review hint (A8's wrapping), while an unlisted direct
+ * write tool stays the extension's own. `undo` is REQUIRED: a target
+ * without it fails the load (no undo, no magic).
+ */
+export interface CurationTarget {
+    /** Unique within the extension; core qualifies it as `<slug>:<name>`. */
+    readonly name: string;
+    /** Tools the review may call to write this target; registered by this extension. */
+    readonly tools: readonly string[];
+    /** Routing guidance for one user; `[]` = unavailable for this user. */
+    guidance(user: string): readonly string[] | Promise<readonly string[]>;
+    /** Revert one change this target reported. Required. */
+    undo(user: string, changeId: string, ctx: HandlerContext): Promise<void>;
+    /** Optional idle maintenance, called by the curator's idle pass. */
+    maintain?(user: string, ctx: HandlerContext, budget: MaintenanceBudget): Promise<MaintenanceReport>;
+}
+/**
+ * The `details.curation` shape every target tool's mutating result
+ * carries: the change id for the undo surface and a one-line summary
+ * for the UI. A type alias (not an interface): the structural JSON
+ * mirror of the tool-result details field.
+ */
+export type CurationChangeDetails = {
+    readonly changeId: string;
+    readonly summary: string;
+};
+/**
+ * One recorded review hint (P9): an owner-authored call to a curation
+ * tool outside a curator run, captured by A8's wrapper for the next
+ * review. `args` is the verbatim tool arguments; `at` is the capture
+ * instant (ISO).
+ */
+export type CurationHint = {
+    readonly id: string;
+    readonly tool: string;
+    readonly args: JsonObject;
+    readonly at: string;
+};
+/**
+ * One change to a learned skill (the `skill_manage` mutating union,
+ * structural mirror of the store's `SkillChange`). A type alias (not
+ * an interface): the implicit index signature the JSON doc shapes need.
+ */
+export type CurationSkillChange = {
+    readonly kind: "create";
+    readonly content: string;
+} | {
+    readonly kind: "patch";
+    readonly old: string;
+    readonly new: string;
+    readonly file?: string;
+} | {
+    readonly kind: "write_file";
+    readonly file: string;
+    readonly content: string;
+} | {
+    readonly kind: "remove_file";
+    readonly file: string;
+} | {
+    readonly kind: "archive";
+    readonly absorbedInto?: string;
+} | {
+    readonly kind: "restore";
+    readonly version?: string;
+};
+/**
+ * One change-feed entry (structural mirror of the store's `FeedEntry`).
+ * The undo-relevant fields (`before`, `after`) are opaque version ids.
+ */
+export type CurationFeedEntry = {
+    readonly id: string;
+    readonly at: string;
+    readonly actor: "curator" | "agent" | "user";
+    readonly action: string;
+    readonly skill: string;
+    readonly reason?: string;
+    readonly reviewId?: string;
+    readonly conversationId?: number;
+    readonly before?: string;
+    readonly after?: string;
+};
+/** One learned skill's listing row (structural mirror). */
+export type CurationSkillInfo = {
+    readonly name: string;
+    readonly description: string;
+    readonly archived: boolean;
+    readonly pinned: boolean;
+    readonly bytes: number;
+    readonly createdAt: string;
+};
+/** Identifies one upstream skill an overlay attaches to (structural mirror). */
+export type CurationOverlayKey = {
+    readonly root: "workspace" | "user dir" | "package";
+    readonly skill: string;
+    /** The canonical workspace root path; required for workspace keys only. */
+    readonly workspace?: string;
+};
+/** One stored overlay (structural mirror). */
+export type CurationOverlay = {
+    readonly key: CurationOverlayKey;
+    readonly text: string;
+    readonly upstreamHash: string;
+    readonly orphanedSince?: string;
+};
+/** The actor-side metadata an overlay change records in the feed. */
+export type CurationOverlayMeta = {
+    readonly actor: "curator" | "agent" | "user";
+    readonly reason?: string;
+    readonly reviewId?: string;
+    readonly conversationId?: number;
+};
+/** The bounds and identity one curator run drives under. */
+export type CurationRunOpts = {
+    /** The instruction the run submits as its only input. */
+    readonly instruction: string;
+    /** The tools the run's gate allows (non-empty — the gate's message names them). */
+    readonly allow: readonly string[];
+    /** The tool-result budget: the run aborts at this many tool results. */
+    readonly maxToolCalls: number;
+    /** The output-token budget (advisory; see the run-driver docs). */
+    readonly maxOutputTokens: number;
+    /** The wall-clock budget in milliseconds. */
+    readonly deadlineMs: number;
+    /** The review (or digest) identity stamped on every feed entry. */
+    readonly reviewId: string;
+    /** Caller cancellation: fires → the run aborts as cancelled. */
+    readonly signal?: AbortSignal;
+};
+/** What a review's `eligibility` read answers. */
+export type CurationEligibility = {
+    readonly owner?: string;
+    readonly internal: boolean;
+    /** Every user entry attributed to the owner. */
+    readonly ownerOnly: boolean;
+    /** Unattributed user entries. */
+    readonly unattributed: number;
+    readonly newestEntry?: EntryId;
+};
+/** One served curation target, projected for the caller. */
+export type CurationTargetInfo = {
+    readonly id: string;
+    readonly tools: readonly string[];
+    readonly guidance: readonly string[];
+    readonly maintain: boolean;
+};
+/** The per-user skill-store subset the curation host serves. */
+export type CurationSkillStore = {
+    list(): Promise<readonly CurationSkillInfo[]>;
+    view(name: string, file?: string): Promise<string>;
+    feed(limit: number, before?: string): Promise<readonly CurationFeedEntry[]>;
+    pin(name: string, pinned: boolean): Promise<void>;
+    undo(entryIds: readonly string[]): Promise<readonly CurationFeedEntry[]>;
+    /** Apply one change as the curator (actor "curator"). */
+    apply(name: string, change: CurationSkillChange, meta: {
+        readonly reviewId?: string;
+        readonly reason?: string;
+    }): Promise<CurationFeedEntry>;
+};
+/** The per-user overlay-store subset the curation host serves. */
+export type CurationOverlayStore = {
+    list(): Promise<readonly CurationOverlay[]>;
+    get(key: CurationOverlayKey): Promise<CurationOverlay | undefined>;
+    put(key: CurationOverlayKey, text: string, upstreamHash: string, meta: CurationOverlayMeta): Promise<CurationFeedEntry>;
+    remove(key: CurationOverlayKey, meta: CurationOverlayMeta): Promise<CurationFeedEntry>;
+    markOrphans(present: (key: CurationOverlayKey) => boolean, now: string): Promise<void>;
+};
+/**
+ * The curation surface (curator P6, A9): the curator's read APIs and
+ * run producers over the curated user's per-user stores. The host
+ * owns the internals; this is the extension-facing projection — the
+ * run driver, the stores and the registry stay server-side.
+ */
+export type SigrunCurationHost = {
+    eligibility(id: ConversationId): Promise<CurationEligibility>;
+    /**
+     * Every user-input entry in the ACTIVE context mapped to its author
+     * (P1). An entry admitted before attribution existed, or by an
+     * unidentified caller, is present with `undefined` — unattributed,
+     * never guessed (fail closed: unattributed entries are never curation
+     * input).
+     */
+    authors(id: ConversationId): Promise<ReadonlyMap<EntryId, string | undefined>>;
+    /** Count the conversation's assistant entries after (or all without) an anchor entry. */
+    modelCallsSince(id: ConversationId, entryId?: EntryId): Promise<number>;
+    /** Read and clear the conversation's pending review hints (A8's doc). */
+    takeHints(id: ConversationId): Promise<readonly CurationHint[]>;
+    /** Targets whose tools are all in the conversation's selection (no id: all). */
+    targets(user: string, id?: ConversationId): Promise<readonly CurationTargetInfo[]>;
+    /** The conversation's model-visible tool names (for the allow-list). */
+    tools(id: ConversationId): Promise<readonly string[]>;
+    /** Fork the conversation at its newest entry and drive the review run. */
+    forkReview(id: ConversationId, opts: CurationRunOpts): Promise<CurationRunResult>;
+    /** A fresh internal digest conversation for `user`, driven the same way. */
+    digestRun(user: string, opts: CurationRunOpts & {
+        readonly input: string;
+        readonly model?: string;
+    }): Promise<CurationRunResult>;
+    /** Run one target's maintenance pass with a digest-run budget. */
+    maintain(user: string, targetId: string, budget: Omit<MaintenanceBudget, "run">): Promise<MaintenanceReport>;
+    /** The curated user's skill store (apply = actor "curator"). */
+    skills(user: string): CurationSkillStore;
+    /** The curated user's overlay store. */
+    overlays(user: string): CurationOverlayStore;
+    /** The current upstream body + hash for one overlay key. */
+    upstream(user: string, key: CurationOverlayKey): Promise<{
+        readonly body: string;
+        readonly hash: string;
+    } | undefined>;
+    /** Skill names in the user's job prompts, paused jobs included. */
+    jobSkillRefs(user: string): Promise<ReadonlySet<string>>;
+    /** Revert every change one review made; the number of reverts. */
+    undoReview(user: string, reviewId: string): Promise<number>;
+    /** The skill → lastUsed ISO map (P4's counters). */
+    usage(user: string): Promise<Readonly<Record<string, string | undefined>>>;
+};
 /** The command and extra environment/read rights for one per-user process. */
 export interface ServiceSpec {
     readonly command: string;
@@ -1036,6 +1303,14 @@ export interface SigrunHost {
             readonly notice?: string;
         }>;
     };
+    /**
+     * The curation surface (curator P6, A9): the curator's read APIs
+     * (eligibility, hints, targets, tools, skills, overlays, usage, job
+     * references) and the run producers (fork review, digest, maintain).
+     * Binds lazily like every bridged member — a factory-body call WAITS
+     * for the bridge, never a silent drop.
+     */
+    readonly curation: SigrunCurationHost;
 }
 /**
  * The documented factory-result contract: EVERY field an extension may
@@ -1073,6 +1348,13 @@ export interface SigrunExtensionResult extends SigrunLifecycleHandlers {
     readonly ambientKinds?: readonly string[];
     /** Idle workers (the curator contract — `wakeOn` only, `every` retired). */
     readonly workers?: readonly ExtensionWorker[];
+    /**
+     * Curation targets (the curator contract, spec P7): this extension's
+     * writable per-user surfaces the curator learns into. Every listed
+     * tool's outside-run calls become review hints (A8's wrapping); a
+     * target without `undo` fails the load.
+     */
+    readonly curationTargets?: readonly CurationTarget[];
     /** Declared jobs (the only time-based scheduler); read-only through the API under `ext:<slug>:<name>` ids. */
     readonly jobs?: readonly JobSpec[];
     /** HTTP routes mounted at `/v1/ext/<slug>/<path>` (lands in Task 2). */