@sigrun/warden 0.0.0-stage → 0.1.1

package/dist/cards.js

@@ -0,0 +1,141 @@
+/**
+ * Skill cards (warden spec §3.4): a compact digest of one skill body,
+ * built once per body hash by `host.models.complete` and stored under
+ * the warden's data root. A build yields `undefined` on any failure or
+ * an answer over 8192 bytes; builds are single-flight per hash.
+ */
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export const CARD_MAX_BYTES = 8192;
+export const CARD_TIMEOUT_MS = 60_000;
+/** The system prompt for one card build: quote the skill, invent nothing. */
+export const CARD_SYSTEM_PROMPT = `You are writing a rule card for one skill, from the skill text alone.
+
+For EACH tool the skill names as destructive (remove, delete, import, deny, unmatch, purge, blocklist, and similar actions that change or destroy data), write one heading:
+
+## <tool>
+
+Under each heading write exactly three bullet lists:
+
+**Allowed without asking when:** the exact conditions the skill states.
+**Evidence required first:** which earlier lookups the skill requires, and what they must show. Quote the skill's own check names and values.
+**Escalate instead when:** the exact conditions the skill states.
+
+Quote the skill's own thresholds, limits, and names verbatim. Do not invent conditions, thresholds, tools, or evidence steps the skill does not name. If the skill names no destructive tools, answer exactly: no destructive tools.`;
+/** The warden's card store: one JSON file per card at `<dataDir>/cards/<hash>.json`. */
+export class CardStore {
+    #dir;
+    /** `dataDir` is the warden's `host.stores.paths.data`. */
+    constructor(dataDir) {
+        this.#dir = join(dataDir, "cards");
+    }
+    async get(hash) {
+        let raw;
+        try {
+            raw = await readFile(join(this.#dir, `${hash}.json`), "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async put(card) {
+        await mkdir(this.#dir, { recursive: true });
+        await writeFile(join(this.#dir, `${card.hash}.json`), `${JSON.stringify(card, null, 2)}\n`, "utf8");
+    }
+    async list() {
+        let names;
+        try {
+            names = await readdir(this.#dir);
+        }
+        catch {
+            return [];
+        }
+        const cards = [];
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            const card = await this.get(name.slice(0, -".json".length));
+            if (card !== undefined)
+                cards.push(card);
+        }
+        // Newest build first.
+        cards.sort((a, b) => (a.builtAt < b.builtAt ? 1 : a.builtAt > b.builtAt ? -1 : 0));
+        return cards;
+    }
+}
+/**
+ * In-flight builds, keyed by body hash: concurrent builds for one hash
+ * call the model once (spec §3.4 single-flight). Module-scoped — one
+ * process, one warden instance.
+ */
+const inflight = new Map();
+/** Test hook: drop the single-flight map (a failed build must not pin a test). */
+export function resetInflightForTests() {
+    inflight.clear();
+}
+/**
+ * Build (or fetch the in-flight build of) the card for one skill body.
+ * `undefined` on any failure or an answer over the byte cap; the caller
+ * (an afterTool background task or `/warden card --rebuild`) treats
+ * undefined as "no card" and never blocks on it.
+ */
+export function buildCard(host, skill, settings) {
+    const existing = inflight.get(skill.hash);
+    if (existing !== undefined)
+        return existing;
+    const build = buildCardUncached(host, skill, settings).finally(() => {
+        inflight.delete(skill.hash);
+    });
+    inflight.set(skill.hash, build);
+    return build;
+}
+async function buildCardUncached(host, skill, settings) {
+    // Store first: a card already built for this body is returned
+    // without a model call.
+    const store = new CardStore(host.stores.paths.data);
+    try {
+        const stored = await store.get(skill.hash);
+        if (stored !== undefined)
+            return stored;
+    }
+    catch {
+        // An unreadable store falls through to a fresh build.
+    }
+    let answer;
+    try {
+        answer = await host.models.complete({
+            ...(settings.cardModel === undefined
+                ? { role: "utility" }
+                : { model: settings.cardModel }),
+            systemPrompt: CARD_SYSTEM_PROMPT,
+            prompt: `Skill: ${skill.name}\n\n${skill.body}`,
+            timeoutMs: CARD_TIMEOUT_MS,
+        });
+    }
+    catch {
+        return undefined;
+    }
+    if (Buffer.byteLength(answer.text, "utf8") > CARD_MAX_BYTES)
+        return undefined;
+    const card = {
+        hash: skill.hash,
+        skill: skill.name,
+        ...(skill.location === undefined ? {} : { location: skill.location }),
+        builtAt: new Date().toISOString(),
+        model: answer.model,
+        text: answer.text,
+    };
+    try {
+        await store.put(card);
+    }
+    catch {
+        return undefined;
+    }
+    return card;
+}

package/dist/classify.d.ts

@@ -0,0 +1,76 @@
+import type { WardenSettings } from "./settings.js";
+export type Classification = {
+    kind: "allow";
+    reason: string;
+    warns?: readonly string[];
+} | {
+    kind: "deny";
+    reason: string;
+} | {
+    kind: "destructive";
+    reasons: readonly string[];
+    mcp?: {
+        server: string;
+        mcpName: string;
+    };
+    warns?: readonly string[];
+} | {
+    kind: "bash-unknown";
+    command: string;
+    warns?: readonly string[];
+};
+/**
+ * The annotation answer for one MCP tool name (`server/mcpName`):
+ * `found` carries the published annotation entry, `unknown` means the
+ * provider answered but the tool carried no trustable annotation
+ * (`unknown: true`), and `no-provider` means no extension publishes the
+ * `mcp.tool-annotations` hook at all.
+ */
+export type AnnotationLookup = {
+    status: "found";
+    server: string;
+    mcpName: string;
+    readOnly?: boolean;
+    destructive?: boolean;
+} | {
+    status: "unknown";
+} | {
+    status: "no-provider";
+};
+export interface ClassifyDeps {
+    annotations(tool: string): Promise<AnnotationLookup>;
+    settings: WardenSettings;
+}
+/**
+ * The published-hook call Task 11's host wiring uses, kept here so both
+ * the factory and future tests share the mapping: the hook is
+ * `mcp.tool-annotations`; `absent` maps to `no-provider`, an `ok` value
+ * with `unknown: true` maps to `unknown`, anything else `ok` is the
+ * annotation entry.
+ */
+export declare function annotationFromHookResult(tool: string, result: {
+    status: "absent";
+} | {
+    status: "ok";
+    value: unknown;
+} | {
+    status: string;
+}): AnnotationLookup;
+/**
+ * Classify one tool call. The order is the warden spec's:
+ * 1. deny rule → deny;
+ * 2. core read-only names → allow;
+ * 3. bash: read-only → allow; `matchPatterns` on the RAW command →
+ *    destructive; else bash-unknown;
+ * 4. a name containing `/` → the annotations lookup (readOnly or
+ *    `destructive === false` → allow; destructive / unknown /
+ *    no-provider → destructive with the mcp pair);
+ * 5. hold rules → destructive;
+ * 6. otherwise allow.
+ * `warn` rules never change the verdict; the matched patterns come back
+ * in `warns` so the caller writes the warn log records.
+ */
+export declare function classify(call: {
+    name: string;
+    arguments: Record<string, unknown>;
+}, deps: ClassifyDeps): Promise<Classification>;

package/dist/classify.js

@@ -0,0 +1,196 @@
+/**
+ * Action classification (warden spec §3.1). Pure over injected deps: the
+ * MCP annotations lookup is provided by the caller (Task 11 wires it to
+ * `host.publishedHooks.call("mcp.tool-annotations", …)`; tests inject
+ * fakes).
+ */
+import { isReadOnlyCommand, matchPatterns } from "pi-warden";
+import { matchGlob } from "./glob.js";
+/** Core tool names that are always read-only. */
+const CORE_READ_ONLY = new Set(["read", "ls", "find", "grep", "load_skill"]);
+function splitMcpName(name) {
+    const slash = name.indexOf("/");
+    return { server: name.slice(0, slash), mcpName: name.slice(slash + 1) };
+}
+/**
+ * The published-hook call Task 11's host wiring uses, kept here so both
+ * the factory and future tests share the mapping: the hook is
+ * `mcp.tool-annotations`; `absent` maps to `no-provider`, an `ok` value
+ * with `unknown: true` maps to `unknown`, anything else `ok` is the
+ * annotation entry.
+ */
+export function annotationFromHookResult(tool, result) {
+    if (result.status === "absent")
+        return { status: "no-provider" };
+    if (result.status !== "ok")
+        return { status: "no-provider" };
+    const value = result.value;
+    if (typeof value !== "object" || value === null)
+        return { status: "unknown" };
+    const record = value;
+    if (record.unknown === true)
+        return { status: "unknown" };
+    const { server, mcpName } = splitMcpName(tool);
+    // The hook's published output schema (ext-mcp 0.2.3's
+    // `mcp.tool-annotations`) nests the hints under `annotations`, spelled
+    // `readOnlyHint` / `destructiveHint`. The flat `readOnly` / `destructive`
+    // keys were the warden spec's shorthand and no provider ever served
+    // them; they stay accepted defensively, but the nested shape is the
+    // wire truth and wins when both appear.
+    const hints = typeof record.annotations === "object" && record.annotations !== null
+        ? record.annotations
+        : {};
+    const readOnlyHint = hints.readOnlyHint;
+    const destructiveHint = hints.destructiveHint;
+    return {
+        status: "found",
+        server,
+        mcpName,
+        ...(typeof readOnlyHint === "boolean"
+            ? { readOnly: readOnlyHint }
+            : typeof record.readOnly === "boolean"
+                ? { readOnly: record.readOnly }
+                : {}),
+        ...(typeof destructiveHint === "boolean"
+            ? { destructive: destructiveHint }
+            : typeof record.destructive === "boolean"
+                ? { destructive: record.destructive }
+                : {}),
+    };
+}
+/** Every string argument of a tool call (the `path`-rule match surface). */
+function stringArguments(args) {
+    const out = [];
+    for (const value of Object.values(args)) {
+        if (typeof value === "string")
+            out.push(value);
+    }
+    return out;
+}
+/**
+ * Classify one tool call. The order is the warden spec's:
+ * 1. deny rule → deny;
+ * 2. core read-only names → allow;
+ * 3. bash: read-only → allow; `matchPatterns` on the RAW command →
+ *    destructive; else bash-unknown;
+ * 4. a name containing `/` → the annotations lookup (readOnly or
+ *    `destructive === false` → allow; destructive / unknown /
+ *    no-provider → destructive with the mcp pair);
+ * 5. hold rules → destructive;
+ * 6. otherwise allow.
+ * `warn` rules never change the verdict; the matched patterns come back
+ * in `warns` so the caller writes the warn log records.
+ */
+export async function classify(call, deps) {
+    const { name, arguments: args } = call;
+    const rules = deps.settings.rules;
+    const command = typeof args.command === "string" ? args.command : undefined;
+    const ruleTargets = (match) => {
+        if (match === "tool")
+            return [name];
+        if (match === "command")
+            return command === undefined ? [] : [command];
+        return stringArguments(args);
+    };
+    for (const rule of rules) {
+        if (rule.level !== "deny")
+            continue;
+        const target = ruleTargets(rule.match).find((value) => matchGlob(value, [rule.pattern]) !== undefined);
+        if (target !== undefined) {
+            return {
+                kind: "deny",
+                reason: `deny rule ${JSON.stringify(rule.pattern)} matched ${JSON.stringify(target)}`,
+            };
+        }
+    }
+    const warns = [];
+    for (const rule of rules) {
+        if (rule.level !== "warn")
+            continue;
+        const target = ruleTargets(rule.match).find((value) => matchGlob(value, [rule.pattern]) !== undefined);
+        if (target !== undefined)
+            warns.push(rule.pattern);
+    }
+    const withWarns = (classification) => warns.length === 0 ? classification : { ...classification, warns };
+    // 2. Core read-only names.
+    if (CORE_READ_ONLY.has(name)) {
+        return withWarns({ kind: "allow", reason: `core tool ${name} is read-only` });
+    }
+    // 3. Bash. A script containing operators (`< & | ; \` $(`) is not plain
+    // read-only syntax: skip the read-only head check and go straight to
+    // the destructive patterns, whose matcher treats heredoc bodies as
+    // data. An unmatched compound lands as bash-unknown (held), which is
+    // the safe class for "we cannot tell".
+    if (name === "bash") {
+        if (command !== undefined &&
+            !/[<&|;`]/.test(command) &&
+            !command.includes("$(") &&
+            isReadOnlyCommand(command)) {
+            return withWarns({ kind: "allow", reason: "read-only shell command" });
+        }
+        // matchPatterns does its own comment/heredoc handling — never pre-strip.
+        if (command !== undefined) {
+            const hits = matchPatterns("bash", { command });
+            if (hits.length > 0) {
+                return withWarns({
+                    kind: "destructive",
+                    reasons: hits.map((hit) => hit.label),
+                });
+            }
+        }
+        return withWarns({ kind: "bash-unknown", command: command ?? "" });
+    }
+    // 4. MCP tools (`server/mcpName`) via the annotations lookup.
+    if (name.includes("/")) {
+        const annotation = await deps.annotations(name);
+        if (annotation.status === "found") {
+            if (annotation.readOnly === true) {
+                return withWarns({
+                    kind: "allow",
+                    reason: `MCP tool ${name} is annotated readOnly`,
+                });
+            }
+            if (annotation.destructive === false) {
+                return withWarns({
+                    kind: "allow",
+                    reason: `MCP tool ${name} is annotated non-destructive`,
+                });
+            }
+            return withWarns({
+                kind: "destructive",
+                reasons: [`MCP tool ${name} is annotated destructive`],
+                mcp: { server: annotation.server, mcpName: annotation.mcpName },
+            });
+        }
+        if (annotation.status === "unknown") {
+            return withWarns({
+                kind: "destructive",
+                reasons: [`MCP tool ${name} has no trustable annotation`],
+                mcp: splitMcpName(name),
+            });
+        }
+        return withWarns({
+            kind: "destructive",
+            reasons: [
+                `no MCP annotation provider is available; treating ${name} as destructive`,
+            ],
+            mcp: splitMcpName(name),
+        });
+    }
+    // 5. Hold rules.
+    for (const rule of rules) {
+        if (rule.level !== "hold")
+            continue;
+        const target = ruleTargets(rule.match).find((value) => matchGlob(value, [rule.pattern]) !== undefined);
+        if (target !== undefined) {
+            return withWarns({
+                kind: "destructive",
+                reasons: [
+                    `hold rule ${JSON.stringify(rule.pattern)} matched ${JSON.stringify(target)}`,
+                ],
+            });
+        }
+    }
+    // 6. Otherwise allow.
+    return withWarns({ kind: "allow", reason: `no rule or annotation covers ${name}` });
+}

package/dist/commands.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionCommandContribution, SigrunHost } from "@sigrun/sigrun/extension";
+/** Build the warden's slash commands over the host (one per factory). */
+export declare function createWardenCommands(host: SigrunHost): readonly ExtensionCommandContribution[];

package/dist/commands.js

@@ -0,0 +1,104 @@
+import { buildCard, CardStore } from "./cards.js";
+import { HoldLog } from "./log.js";
+import { parseSettings } from "./settings.js";
+import { skillsInRun } from "./skills.js";
+const RUN_PAGE = 500;
+/** Build the warden's slash commands over the host (one per factory). */
+export function createWardenCommands(host) {
+    return [
+        {
+            name: "warden",
+            description: "Skill cards: list, show, rebuild; hold log: list",
+            args: "cards | card <skill> [--rebuild] | holds [n]",
+            run: async (ctx) => ({
+                notice: await runWardenCommands(host, ctx.conversationId, ctx.args),
+            }),
+        },
+    ];
+}
+async function runWardenCommands(host, conversationId, args) {
+    const words = args.trim().split(/\s+/).filter((word) => word.length > 0);
+    const [sub, ...rest] = words;
+    if (sub === "cards")
+        return cardsList(host);
+    if (sub === "card") {
+        const rebuild = rest.includes("--rebuild");
+        const skill = rest.find((word) => word !== "--rebuild");
+        if (skill === undefined)
+            return "usage: /warden card <skill> [--rebuild]";
+        if (rebuild)
+            return cardRebuild(host, conversationId, skill);
+        return cardShow(host, skill);
+    }
+    if (sub === "holds")
+        return holdsList(host, rest[0]);
+    return "usage: /warden cards | /warden card <skill> [--rebuild] | /warden holds [n]";
+}
+const HOLDS_DEFAULT = 20;
+/**
+ * `/warden holds [n]` (warden spec §3.6): the newest `n` hold-log
+ * records, NEWEST FIRST (default 20; n <= 0 → an empty listing). The
+ * log's `call` field is stored redacted (route.ts appends through
+ * pi-warden's `redact`), so the listing renders it verbatim — never
+ * re-derive from anything unmasked.
+ */
+async function holdsList(host, countArg) {
+    let n = HOLDS_DEFAULT;
+    if (countArg !== undefined) {
+        const parsed = Number.parseInt(countArg, 10);
+        if (!Number.isFinite(parsed))
+            return "usage: /warden holds [n]";
+        n = parsed;
+    }
+    if (n <= 0)
+        return "";
+    const log = new HoldLog(`${host.stores.paths.state}/holds.jsonl`, () => new Date());
+    const records = await log.recent(n);
+    if (records.length === 0)
+        return "no holds recorded";
+    // `recent` is oldest-first within the window; the listing is newest first.
+    return records.reverse().map(holdLine).join("\n");
+}
+function holdLine(record) {
+    const parts = [
+        record.at,
+        `conv ${String(record.conversationId)}`,
+        record.tool,
+        record.action,
+    ];
+    if (record.outcome !== undefined)
+        parts.push(record.outcome);
+    return parts.join(" · ");
+}
+async function cardsList(host) {
+    const store = new CardStore(host.stores.paths.data);
+    const cards = await store.list();
+    if (cards.length === 0)
+        return "no cards";
+    return cards.map((card) => cardLine(card)).join("\n");
+}
+function cardLine(card) {
+    return `${card.skill} · ${card.hash.slice(0, 8)} · ${card.builtAt} · ${card.model}`;
+}
+async function cardShow(host, skill) {
+    const store = new CardStore(host.stores.paths.data);
+    const cards = (await store.list()).filter((card) => card.skill === skill);
+    if (cards.length === 0)
+        return `no card for ${skill}`;
+    return cards[0].text;
+}
+async function cardRebuild(host, conversationId, skill) {
+    // Newest page first: a skill loaded late in a long run must be found.
+    const page = await host.conversations.entries(conversationId, { order: "descending" }, RUN_PAGE, undefined);
+    const seen = skillsInRun(page.items);
+    const copy = seen.find((entry) => entry.name === skill);
+    if (copy === undefined) {
+        return `no copy of ${skill} in this conversation; load it first`;
+    }
+    const raw = await host.stores.settings.get();
+    const settings = parseSettings(raw, (message) => console.warn(message));
+    const card = await buildCard(host, copy, settings);
+    if (card === undefined)
+        return `card build failed for ${skill}`;
+    return card.text;
+}

package/dist/context.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Where the tool call is happening (warden spec §3.2 presence classes):
+ * an internal curator run, a scheduled job run, or a live conversation.
+ */
+import type { SigrunHost } from "@sigrun/sigrun/extension";
+import type { ConversationId, EntryId } from "@earendil-works/pi-durable";
+import type { EntryRecord } from "@earendil-works/pi-durable";
+export type Presence = {
+    kind: "live";
+    owner?: string;
+} | {
+    kind: "job";
+    jobId: string;
+    owner?: string;
+} | {
+    kind: "internal";
+};
+/**
+ * Classify the conversation the hook is running in. `meta.internal` wins
+ * (a curator run never escalates); otherwise the job whose fire is
+ * currently running in this conversation decides job-vs-live.
+ */
+export declare function presenceOf(host: SigrunHost, conversationId: ConversationId): Promise<Presence>;
+/** The current run's context, from the newest user input entry. */
+export interface RunInfo {
+    /** The newest user-input entry (this run's start), absent when none. */
+    runStart: EntryId | undefined;
+    /** The newest user input's text ("" when unreachable). */
+    request: string;
+    /** The tail of `request` (last 3000 chars) for prompt-style use. */
+    asked: string;
+    /** This run's entries (from `runStart` on), oldest first. */
+    entries: readonly EntryRecord[];
+}
+/**
+ * Read the run a held call belongs to. Tolerant by contract: it feeds
+ * the judge's clear-ask input (Task 12), so an unreadable history yields
+ * an empty run rather than throwing (beforeTool never fails through it —
+ * the hook still wraps everything, but this keeps the failure mode a
+ * simple degraded context).
+ */
+export declare function runInfo(host: SigrunHost, conversationId: ConversationId): Promise<RunInfo>;

package/dist/context.js

@@ -0,0 +1,103 @@
+/**
+ * Classify the conversation the hook is running in. `meta.internal` wins
+ * (a curator run never escalates); otherwise the job whose fire is
+ * currently running in this conversation decides job-vs-live.
+ */
+export async function presenceOf(host, conversationId) {
+    const meta = await host.conversations.meta(conversationId);
+    if (meta.internal === true)
+        return { kind: "internal" };
+    const run = await host.jobs.activeRun(conversationId);
+    if (run !== undefined) {
+        return {
+            kind: "job",
+            jobId: run.jobId,
+            ...(run.owner === undefined ? {} : { owner: run.owner }),
+        };
+    }
+    return {
+        kind: "live",
+        ...(meta.owner === undefined ? {} : { owner: meta.owner }),
+    };
+}
+const ASKED_MAX = 3000;
+/** Extract the visible text of one entry's first user-model message. */
+function userText(entry) {
+    const messages = entry.model;
+    if (messages === undefined || messages.length === 0)
+        return "";
+    const parts = [];
+    for (const message of messages) {
+        if (message.role !== "user")
+            continue;
+        const content = message.content;
+        if (typeof content === "string") {
+            parts.push(content);
+        }
+        else if (Array.isArray(content)) {
+            for (const block of content) {
+                if (typeof block === "object" &&
+                    block !== null &&
+                    block.type === "text" &&
+                    typeof block.text === "string") {
+                    parts.push(block.text);
+                }
+            }
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * Read the run a held call belongs to. Tolerant by contract: it feeds
+ * the judge's clear-ask input (Task 12), so an unreadable history yields
+ * an empty run rather than throwing (beforeTool never fails through it —
+ * the hook still wraps everything, but this keeps the failure mode a
+ * simple degraded context).
+ */
+export async function runInfo(host, conversationId) {
+    let records;
+    try {
+        // Newest-first probe: find the newest "pi.user" entry id. Anchoring
+        // the window at it keeps the run current even when the transcript
+        // outgrows a single page — a plain ascending page would read the
+        // OLDEST entries and freeze runStart near the conversation start.
+        const probe = await host.conversations.entries(conversationId, { order: "descending" }, 200, undefined);
+        const newestUser = probe.items.find((entry) => entry.kind === "pi.user");
+        if (newestUser === undefined) {
+            // No user input in the newest page: fall back to the plain
+            // ascending read (whole page / empty run).
+            const page = await host.conversations.entries(conversationId, { order: "ascending" }, 200, undefined);
+            records = [...page.items];
+        }
+        else {
+            // The run window: from the newest user input onward, oldest
+            // first — what runStart/request/asked/entries derive from.
+            const page = await host.conversations.entries(conversationId, { order: "ascending", minEntryId: newestUser.id }, 200, undefined);
+            records = [...page.items];
+        }
+    }
+    catch {
+        return { runStart: undefined, request: "", asked: "", entries: [] };
+    }
+    // The window starts at the newest user input, so the first "pi.user"
+    // entry walking forward is the run start (kept as a scan so the
+    // fallback page — which may predate it — still anchors correctly).
+    let startIndex = -1;
+    for (let i = 0; i < records.length; i += 1) {
+        if (records[i].kind === "pi.user") {
+            startIndex = i;
+            break;
+        }
+    }
+    if (startIndex < 0) {
+        return { runStart: undefined, request: "", asked: "", entries: records };
+    }
+    const runEntries = records.slice(startIndex);
+    const request = userText(runEntries[0]);
+    return {
+        runStart: runEntries[0].id,
+        request,
+        asked: request.slice(-ASKED_MAX),
+        entries: runEntries,
+    };
+}