@runbooks/supervise 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Dorokhovich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# `@runbooks/supervise`
+
+The reference supervisor — the implementation of the execution contract.
+
+**Tasks:** [R-01](../../tasks/v0/R-01-supervisor-core.md) through
+[R-09](../../tasks/v2/R-09-run-attestation.md) · **Normative:** RUNBOOK.md §13
+
+## The one sentence that defines scope
+
+> A **runner** performs the steps. A **supervisor** permits them, blocks them, and
+> records what happened. The supervisor does no work of its own and holds no
+> credentials of its own.
+
+Test every proposed feature against it. A feature requiring the supervisor to do work,
+or to hold a secret, is out of scope by construction rather than by preference — and
+the moment this becomes something we host, NG1 is dead.
+
+## What it enforces
+
+Derived from the document, never authored separately (§13.2):
+
+| Document element | Runtime meaning |
+|---|---|
+| `capabilities[]` | the allowlist |
+| current step's `tool` | the **scope** — only this step's declaration, not the run's union |
+| `risk` + `requires_approval` | a gate, decided by a human who is not the agent |
+| `expect` | a postcondition the supervisor evaluates |
+| `on_fail` | a route the supervisor takes |
+| `retry(n)` | a counted budget |
+| terminals | the stop conditions |
+| anything else | a deviation: blocked, recorded, escalated |
+
+Per-step scope is the row that does the most work. Granting an agent the union of a
+procedure's capabilities for the whole run is how a diagnostic session ends in a
+deletion.
+
+## Where it runs
+
+In the operator's environment, between their agent and their tools. No telemetry, no
+callback, no network dependency. Reports and attestations are opt-in, per run, and
+default to emitting nowhere.
+
+## What it is not
+
+Not a sandbox, not a general agent policy engine, not a replacement for the client's
+own allowlist, and not a guarantee. It bounds what the runbook authorizes — a real
+reduction, not a total one (§13.5).

package/dist/approval.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The approval gate protocol.
+ *
+ * `requires_approval` is forced on for destructive and irreversible work regardless of
+ * what the source document says (RUNBOOK.md 12). At run time that becomes a halt, and
+ * §13.4 adds the requirement that carries the weight: **an actual human decision, not a
+ * self-approval.** An agent approving its own destructive step is the failure this
+ * product exists to prevent, so the protocol makes it impossible rather than
+ * discouraged.
+ *
+ * Two properties are structural here, not policy:
+ *
+ * - A grant names the identity that decided, and that identity may not be the agent's.
+ * - A grant authorizes **one invocation of one step**. It is consumed on use, so it can
+ *   never become a standing permission for the rest of the run.
+ */
+import type { PolicyEnvelope } from "./policy.js";
+import type { RunState } from "./run.js";
+import type { Risk } from "@runbooks/schema";
+export declare const REDACTED = "***";
+export interface ApprovalRequest {
+    readonly id: string;
+    readonly stepId: string;
+    readonly title: string;
+    readonly risk: Risk;
+    /** Rendered with secret inputs redacted. */
+    readonly command?: string;
+    readonly capabilities: readonly string[];
+    /** Whether the graph can undo this, and where. Absent means it cannot. */
+    readonly rollbackTo?: string;
+    /** Seconds from issue after which the gate aborts the run. */
+    readonly expiresInSeconds: number;
+    readonly issuedAt: number;
+}
+export interface Grant {
+    readonly requestId: string;
+    readonly stepId: string;
+    /** Who decided. Never the agent — checked when the grant is made. */
+    readonly decidedBy: string;
+}
+export interface Decision {
+    readonly requestId: string;
+    readonly decidedBy: string;
+    readonly at?: number;
+}
+export declare class SelfApprovalError extends Error {
+    constructor(identity: string);
+}
+export type BoundCommand = {
+    readonly ok: true;
+    readonly command: string;
+}
+/** Named, because "it did not run" is not an answer somebody can act on. */
+ | {
+    readonly ok: false;
+    readonly missing: readonly string[];
+};
+/**
+ * The command as it will actually be executed.
+ *
+ * Distinct from `renderCommand` on purpose, and the distinction is the point: that one
+ * redacts declared secrets because an approval channel is somewhere a credential must
+ * never arrive, and executing its output would run the redaction mark as an argument.
+ *
+ * Nothing is substituted for a value that was not supplied. An empty string does not make
+ * a command narrower — `rm -rf /var/log/{{inputs.dir}}` with nothing bound is not a
+ * smaller command than the one that was reviewed, it is a different and larger one. So a
+ * missing value is a refusal that names it.
+ */
+export declare function bindCommand(envelope: PolicyEnvelope, command: string, bound: Readonly<Record<string, unknown>>): BoundCommand;
+export declare function renderCommand(envelope: PolicyEnvelope, command: string, bound: Readonly<Record<string, unknown>>): string;
+export interface RequestOptions {
+    readonly expiresInSeconds?: number;
+    readonly now?: number;
+    readonly id?: string;
+}
+/** The default is short on purpose: a gate held open is a gate. */
+export declare const DEFAULT_EXPIRY_SECONDS = 900;
+export declare function requestApproval(envelope: PolicyEnvelope, state: RunState, options?: RequestOptions): ApprovalRequest | undefined;
+/**
+ * Record a decision. Throws on self-approval rather than returning a refusal: a caller
+ * that ignores a returned error would ship the exact hole this prevents, and there is no
+ * sensible way to continue.
+ */
+export declare function grant(request: ApprovalRequest, decision: Decision, agentIdentity: string): Grant;
+/**
+ * A person looked at the request and said no.
+ *
+ * `RunOutcome` has always documented `aborted` as "stopped deliberately: a rollback, an
+ * operator, **a refused gate**", and until now there was no way to refuse one. The only
+ * exit from a pending gate was expiry — so a considered no was indistinguishable from
+ * nobody having looked, both in the run and in everything downstream of it.
+ *
+ * The reason is required, and that is the point of the type. An approval needs no
+ * justification: proceeding is what the runbook already asked for. A refusal is a
+ * departure from the written procedure, and the next person to meet this step is entitled
+ * to know why the last one stopped.
+ */
+export interface GateRefusal {
+    readonly requestId: string;
+    readonly stepId: string;
+    readonly decidedBy: string;
+    readonly reason: string;
+}
+/**
+ * Record a refusal, under the same rules a grant is recorded under.
+ *
+ * Self-refusal throws for the same reason self-approval does: a decision the agent made
+ * about its own request is not a decision, whichever way it went. An agent that can refuse
+ * its own gate can route around a step it does not want to take.
+ */
+export declare function refuse(request: ApprovalRequest, decision: Decision & {
+    readonly reason: string;
+}, agentIdentity: string): GateRefusal;
+/**
+ * What a refused gate does: end the run, deliberately, with the refusal recorded.
+ *
+ * The same outcome an expiry produces and not the same event: `aborted` is where both
+ * land, and what distinguishes them is that this one carries who decided and why. A report
+ * that cannot tell a considered no from an unanswered question is a report that will be
+ * read as the flattering one.
+ */
+export declare function refuseGate(state: RunState, refusal: GateRefusal): RunState;
+export declare function hasExpired(request: ApprovalRequest, now: number): boolean;
+/**
+ * What a pending, expired gate does: abort.
+ *
+ * "Proceed on timeout" is the convenient default someone will eventually add, and it
+ * turns every gate into a delay. A gate whose answer never came is an unanswered
+ * question, not a yes.
+ */
+export declare function expireGate(state: RunState): RunState;

package/dist/approval.js

@@ -0,0 +1,148 @@
+export const REDACTED = "***";
+export class SelfApprovalError extends Error {
+    constructor(identity) {
+        super(`"${identity}" is the identity running this procedure and cannot approve its own step. An approval must come from someone else.`);
+        this.name = "SelfApprovalError";
+    }
+}
+/**
+ * Render a command for a human, redacting inputs declared secret.
+ *
+ * The target is never redacted: someone approving a destructive operation has to see
+ * what it acts on, and an approval request that hides the target is theatre. Only values
+ * the runbook declares as credentials are hidden — an approval channel is somewhere a
+ * secret should never arrive.
+ */
+/**
+ * What an interpolation looks like, in one place.
+ *
+ * The grammar is the schema's — `checkInterpolations` validates a document against it —
+ * and it is written here once for the two things that act on it: showing a human what
+ * will run, and binding what actually runs. A third spelling is how the two come to
+ * disagree about a command somebody approved.
+ */
+const INTERPOLATION = /\{\{\s*inputs\.([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
+/**
+ * The command as it will actually be executed.
+ *
+ * Distinct from `renderCommand` on purpose, and the distinction is the point: that one
+ * redacts declared secrets because an approval channel is somewhere a credential must
+ * never arrive, and executing its output would run the redaction mark as an argument.
+ *
+ * Nothing is substituted for a value that was not supplied. An empty string does not make
+ * a command narrower — `rm -rf /var/log/{{inputs.dir}}` with nothing bound is not a
+ * smaller command than the one that was reviewed, it is a different and larger one. So a
+ * missing value is a refusal that names it.
+ */
+export function bindCommand(envelope, command, bound) {
+    const missing = [];
+    const filled = command.replace(INTERPOLATION, (match, name) => {
+        const value = envelope.inputs[name] ? bound[name] : undefined;
+        if (value === undefined || String(value) === "") {
+            missing.push(name);
+            return match;
+        }
+        return String(value);
+    });
+    return missing.length > 0 ? { ok: false, missing: [...new Set(missing)] } : { ok: true, command: filled };
+}
+export function renderCommand(envelope, command, bound) {
+    return command.replace(INTERPOLATION, (_match, name) => {
+        const declaration = envelope.inputs[name];
+        if (!declaration)
+            return REDACTED;
+        if (declaration.secret)
+            return REDACTED;
+        const value = bound[name];
+        return value === undefined ? REDACTED : String(value);
+    });
+}
+/** The default is short on purpose: a gate held open is a gate. */
+export const DEFAULT_EXPIRY_SECONDS = 900;
+export function requestApproval(envelope, state, options = {}) {
+    const stepId = state.current;
+    if (!stepId)
+        return undefined;
+    const scope = envelope.steps[stepId];
+    if (!scope || !scope.gated)
+        return undefined;
+    const issuedAt = options.now ?? 0;
+    return {
+        id: options.id ?? `${stepId}@${issuedAt}`,
+        stepId,
+        title: scope.title,
+        risk: scope.risk,
+        ...(scope.command
+            ? { command: renderCommand(envelope, scope.command, state.inputs) }
+            : {}),
+        capabilities: scope.tools,
+        ...(scope.rollbackTo ? { rollbackTo: scope.rollbackTo } : {}),
+        expiresInSeconds: options.expiresInSeconds ?? DEFAULT_EXPIRY_SECONDS,
+        issuedAt,
+    };
+}
+/**
+ * Record a decision. Throws on self-approval rather than returning a refusal: a caller
+ * that ignores a returned error would ship the exact hole this prevents, and there is no
+ * sensible way to continue.
+ */
+export function grant(request, decision, agentIdentity) {
+    if (decision.decidedBy === agentIdentity) {
+        throw new SelfApprovalError(decision.decidedBy);
+    }
+    if (decision.requestId !== request.id) {
+        throw new Error(`Decision names request ${decision.requestId}, but the pending request is ${request.id}. An approval authorizes one invocation of one step.`);
+    }
+    if (hasExpired(request, decision.at ?? request.issuedAt)) {
+        throw new Error(`Request ${request.id} expired after ${request.expiresInSeconds}s. Ask again rather than acting on a stale decision.`);
+    }
+    return { requestId: request.id, stepId: request.stepId, decidedBy: decision.decidedBy };
+}
+/**
+ * Record a refusal, under the same rules a grant is recorded under.
+ *
+ * Self-refusal throws for the same reason self-approval does: a decision the agent made
+ * about its own request is not a decision, whichever way it went. An agent that can refuse
+ * its own gate can route around a step it does not want to take.
+ */
+export function refuse(request, decision, agentIdentity) {
+    if (decision.decidedBy === agentIdentity) {
+        throw new SelfApprovalError(decision.decidedBy);
+    }
+    if (decision.requestId !== request.id) {
+        throw new Error(`Decision names request ${decision.requestId}, but the pending request is ${request.id}. A refusal answers one request.`);
+    }
+    if (decision.reason.trim() === "") {
+        throw new Error("A refusal needs a reason. Approving needs none — the runbook already asked for the step — but stopping is a departure from it, and the next person here is owed the why.");
+    }
+    return {
+        requestId: request.id,
+        stepId: request.stepId,
+        decidedBy: decision.decidedBy,
+        reason: decision.reason,
+    };
+}
+/**
+ * What a refused gate does: end the run, deliberately, with the refusal recorded.
+ *
+ * The same outcome an expiry produces and not the same event: `aborted` is where both
+ * land, and what distinguishes them is that this one carries who decided and why. A report
+ * that cannot tell a considered no from an unanswered question is a report that will be
+ * read as the flattering one.
+ */
+export function refuseGate(state, refusal) {
+    return { ...state, status: "ended", outcome: "aborted", refusal };
+}
+export function hasExpired(request, now) {
+    return now - request.issuedAt > request.expiresInSeconds;
+}
+/**
+ * What a pending, expired gate does: abort.
+ *
+ * "Proceed on timeout" is the convenient default someone will eventually add, and it
+ * turns every gate into a delay. A gate whose answer never came is an unanswered
+ * question, not a yes.
+ */
+export function expireGate(state) {
+    return { ...state, status: "ended", outcome: "aborted" };
+}

package/dist/approval.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/approval.test.js

@@ -0,0 +1,190 @@
+import { describe, it, expect } from "vitest";
+import { derivePolicy } from "./policy.js";
+import { startRun, propose, applyGrant, advance } from "./run.js";
+import { requestApproval, grant, refuse, refuseGate, hasExpired, expireGate, renderCommand, SelfApprovalError, REDACTED, DEFAULT_EXPIRY_SECONDS, } from "./approval.js";
+const runbook = (r) => ({ runbook: r });
+const doc = runbook({
+    capabilities: ["mcp:postgres"],
+    inputs: {
+        slot: { type: "string", required: true },
+        token: { type: "string", required: true, secret: true },
+    },
+    steps: [
+        {
+            id: "s1", kind: "action", title: "Drop the replication slot", risk: "destructive",
+            tool: "mcp:postgres", requires_approval: true,
+            command: "psql --token {{inputs.token}} -c \"select pg_drop_replication_slot('{{inputs.slot}}')\"",
+            next: "end:success",
+        },
+    ],
+});
+function start(agentIdentity = "agent-7") {
+    const env = derivePolicy(doc);
+    const r = startRun(env, { inputs: { slot: "wal_keeper", token: "hunter2" }, agentIdentity });
+    if (!r.ok)
+        throw new Error("expected a start");
+    return { env, state: r.state };
+}
+describe("the request carries enough to decide, and nothing more", () => {
+    it("names the step, its risk, its capabilities and whether it can be undone", () => {
+        const { env, state } = start();
+        const request = requestApproval(env, state, { now: 1000 });
+        expect(request.stepId).toBe("s1");
+        expect(request.risk).toBe("destructive");
+        expect(request.title).toBe("Drop the replication slot");
+        expect(request.capabilities).toEqual(["mcp:postgres"]);
+        expect(request.rollbackTo).toBeUndefined();
+    });
+    // The target is never hidden: someone approving a destructive operation has to see
+    // what it acts on, and a request that hides the target is theatre.
+    it("shows the target", () => {
+        const { env, state } = start();
+        expect(requestApproval(env, state, { now: 0 }).command).toContain("wal_keeper");
+    });
+    // An approval channel is somewhere a secret should never arrive.
+    it("redacts an input declared secret", () => {
+        const { env, state } = start();
+        const command = requestApproval(env, state, { now: 0 }).command;
+        expect(command).not.toContain("hunter2");
+        expect(command).toContain(REDACTED);
+    });
+    it("redacts an interpolation it cannot account for", () => {
+        const { env } = start();
+        expect(renderCommand(env, "x {{inputs.unknown}}", {})).toBe(`x ${REDACTED}`);
+    });
+    it("is not issued for an ungated step", () => {
+        const ungated = derivePolicy(runbook({
+            capabilities: [],
+            steps: [{ id: "s1", kind: "action", title: "Go", risk: "read-only", next: "end:success" }],
+        }));
+        const r = startRun(ungated, {});
+        expect(r.ok && requestApproval(ungated, r.state, {})).toBeUndefined();
+    });
+});
+describe("self-approval is impossible, not discouraged", () => {
+    it("refuses a decision from the identity running the procedure", () => {
+        const { env, state } = start("agent-7");
+        const request = requestApproval(env, state, { now: 0 });
+        expect(() => grant(request, { requestId: request.id, decidedBy: "agent-7" }, state.agentIdentity))
+            .toThrow(SelfApprovalError);
+    });
+    it("accepts a decision from anyone else", () => {
+        const { env, state } = start("agent-7");
+        const request = requestApproval(env, state, { now: 0 });
+        expect(grant(request, { requestId: request.id, decidedBy: "operator" }, state.agentIdentity).decidedBy)
+            .toBe("operator");
+    });
+});
+describe("a grant authorizes one entry into one step", () => {
+    it("permits the gated step once granted", () => {
+        const { env, state } = start();
+        const request = requestApproval(env, state, { now: 0 });
+        const granted = applyGrant(state, grant(request, { requestId: request.id, decidedBy: "operator" }, state.agentIdentity)).state;
+        expect(propose(env, granted, { tool: "mcp:postgres" }).authorization.verdict).toBe("permit");
+    });
+    it("refuses a decision naming a different request", () => {
+        const { env, state } = start();
+        const request = requestApproval(env, state, { now: 0 });
+        expect(() => grant(request, { requestId: "someone-elses", decidedBy: "operator" }, state.agentIdentity))
+            .toThrow(/one invocation of one step/);
+    });
+    // The realistic replay: a retry loop returning to the gated step and reusing the one
+    // approval a human gave for the first attempt.
+    it("does not survive leaving and re-entering the step", () => {
+        const loop = derivePolicy(runbook({
+            capabilities: ["mcp:postgres"],
+            steps: [
+                { id: "s1", kind: "action", title: "Drop it", risk: "destructive", tool: "mcp:postgres", requires_approval: true, next: "s2" },
+                { id: "s2", kind: "wait", title: "Wait", duration: "5s", retry: { max: 3, target: "s1" }, next: "end:success" },
+            ],
+        }));
+        const r = startRun(loop, { agentIdentity: "agent-7" });
+        expect(r.ok).toBe(true);
+        if (!r.ok)
+            return;
+        const request = requestApproval(loop, r.state, { now: 0 });
+        let s = applyGrant(r.state, grant(request, { requestId: request.id, decidedBy: "operator" }, "agent-7")).state;
+        expect(propose(loop, s, { tool: "mcp:postgres" }).authorization.verdict).toBe("permit");
+        s = advance(loop, s, "s2").state;
+        s = advance(loop, s, "s1").state;
+        expect(s.grant).toBeUndefined();
+        expect(propose(loop, s, { tool: "mcp:postgres" }).authorization.verdict).toBe("require-approval");
+    });
+});
+describe("a gate that is never answered aborts", () => {
+    it("treats an expired request as expired", () => {
+        const { env, state } = start();
+        const request = requestApproval(env, state, { now: 0, expiresInSeconds: 60 });
+        expect(hasExpired(request, 59)).toBe(false);
+        expect(hasExpired(request, 61)).toBe(true);
+    });
+    it("refuses a decision that arrives after expiry", () => {
+        const { env, state } = start();
+        const request = requestApproval(env, state, { now: 0, expiresInSeconds: 60 });
+        expect(() => grant(request, { requestId: request.id, decidedBy: "operator", at: 120 }, state.agentIdentity))
+            .toThrow(/stale decision/);
+    });
+    // "Proceed on timeout" is the convenient default someone will eventually add, and it
+    // turns every gate into a delay. An unanswered question is not a yes.
+    it("aborts the run rather than proceeding", () => {
+        const { state } = start();
+        const expired = expireGate(state);
+        expect(expired.status).toBe("ended");
+        expect(expired.outcome).toBe("aborted");
+    });
+    it("defaults to a short expiry", () => {
+        expect(DEFAULT_EXPIRY_SECONDS).toBeLessThanOrEqual(3600);
+    });
+});
+/**
+ * §13: a person may say no, and the run has to be able to record that.
+ *
+ * `RunOutcome` has documented `aborted` as "stopped deliberately: a rollback, an operator,
+ * **a refused gate**" since it was written, and there was no way to refuse one. The only
+ * exit from a pending gate was expiry — so a considered no and nobody having looked landed
+ * in the same state, indistinguishable to everything downstream.
+ *
+ * This catalog publishes `adapted/design-the-rejection-path-too`, whose whole point is that
+ * approval paths get tested and rejection paths get discovered in production. It had one.
+ */
+describe("a gate can be refused, not only granted or expired", () => {
+    const request = (over = {}) => ({
+        id: "req-1",
+        stepId: "s5",
+        reason: "destructive",
+        capabilities: [],
+        expiresInSeconds: 300,
+        issuedAt: 0,
+        ...over,
+    });
+    it("records who refused and why", () => {
+        const refusal = refuse(request(), { requestId: "req-1", decidedBy: "ada", reason: "wrong node" }, "agent-7");
+        expect(refusal.decidedBy).toBe("ada");
+        expect(refusal.reason).toBe("wrong node");
+        expect(refusal.stepId).toBe("s5");
+    });
+    /**
+     * A refusal needs a reason and an approval does not: proceeding is what the runbook
+     * already asked for, stopping is a departure from it.
+     */
+    it("refuses to record a refusal with no reason", () => {
+        expect(() => refuse(request(), { requestId: "req-1", decidedBy: "ada", reason: "  " }, "agent-7")).toThrow(/needs a reason/);
+    });
+    it("will not let the agent refuse its own gate", () => {
+        expect(() => refuse(request(), { requestId: "req-1", decidedBy: "agent-7", reason: "no" }, "agent-7")).toThrow(SelfApprovalError);
+    });
+    it("answers one request, like a grant", () => {
+        expect(() => refuse(request(), { requestId: "req-2", decidedBy: "ada", reason: "no" }, "agent-7")).toThrow(/answers one request/);
+    });
+    /** Both end the run; only one of them says a person decided. */
+    it("is distinguishable from an expiry in the run state", () => {
+        const pending = { status: "awaiting-approval", visited: [], agentIdentity: "agent-7" };
+        const refusal = refuse(request(), { requestId: "req-1", decidedBy: "ada", reason: "wrong node" }, "agent-7");
+        const refused = refuseGate(pending, refusal);
+        const expired = expireGate(pending);
+        expect(refused.outcome).toBe("aborted");
+        expect(expired.outcome).toBe("aborted");
+        expect(refused.refusal?.reason).toBe("wrong node");
+        expect(expired.refusal).toBeUndefined();
+    });
+});

package/dist/budgets.test.d.ts

@@ -0,0 +1 @@
+export {};