toolroll 0.5.0

package/dist/email-settings.d.ts

@@ -0,0 +1,34 @@
+/** The mail server (v87), and where Inbox triggers read it (v89: its IMAP address; same sign-in). */
+export type EmailSettings = {
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    from: string;
+    imap: {
+        host: string;
+        port: number;
+        secure: boolean;
+    } | null;
+};
+export declare const ADDRESS: RegExp;
+export declare function readEmailSettings(dir: string | null): (EmailSettings & {
+    password: string;
+}) | null;
+/** Save the mail server from Settings; an empty password keeps the saved one. An IMAP address lets Inbox triggers read it. */
+export declare function saveEmailSettings(dir: string, input: {
+    host: unknown;
+    port: unknown;
+    secure: unknown;
+    user: unknown;
+    from: unknown;
+    password: unknown;
+    imapHost?: unknown;
+    imapPort?: unknown;
+}): {
+    ok: true;
+    said: string;
+} | {
+    ok: false;
+    message: string;
+};

package/dist/email-settings.js

@@ -0,0 +1,50 @@
+/**
+ * The mail server (v87) and where Inbox triggers read it (v89), saved from
+ * Settings → Email in a 0600 file beside the database. Its own module, with
+ * nothing but the file system, so the mailbox and triggers can read it
+ * without pulling in the step runners.
+ */
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const EMAIL_FILE = "email.json";
+export const ADDRESS = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}$/;
+export function readEmailSettings(dir) {
+    if (dir === null || !existsSync(join(dir, EMAIL_FILE)))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(join(dir, EMAIL_FILE), "utf8"));
+        if (typeof raw["host"] !== "string" || typeof raw["from"] !== "string")
+            return null;
+        const imap = raw["imap"] !== null && typeof raw["imap"] === "object" ? raw["imap"] : null;
+        return { host: raw["host"], port: Number(raw["port"]) || 587, secure: raw["secure"] === true, user: typeof raw["user"] === "string" ? raw["user"] : "", from: raw["from"], password: typeof raw["password"] === "string" ? raw["password"] : "",
+            imap: imap !== null && typeof imap["host"] === "string" ? { host: imap["host"], port: Number(imap["port"]) || 993, secure: imap["secure"] !== false } : null };
+    }
+    catch {
+        return null;
+    }
+}
+/** Save the mail server from Settings; an empty password keeps the saved one. An IMAP address lets Inbox triggers read it. */
+export function saveEmailSettings(dir, input) {
+    const host = typeof input.host === "string" ? input.host.trim() : "";
+    if (!/^[A-Za-z0-9.-]{1,253}$/.test(host))
+        return { ok: false, message: "Give the mail server's name, like smtp.gmail.com." };
+    const port = Number(input.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return { ok: false, message: "The port is a number, usually 587 or 465." };
+    const from = typeof input.from === "string" ? input.from.trim() : "";
+    if (!ADDRESS.test(from))
+        return { ok: false, message: "Give the address emails come from." };
+    const user = typeof input.user === "string" ? input.user.trim().slice(0, 254) : "";
+    const imapHost = typeof input.imapHost === "string" ? input.imapHost.trim() : "";
+    if (imapHost !== "" && !/^[A-Za-z0-9.-]{1,253}$/.test(imapHost))
+        return { ok: false, message: "Give the server Inbox triggers read from, like imap.gmail.com, or leave it empty." };
+    const imapPort = input.imapPort === undefined || input.imapPort === "" || input.imapPort === null ? 993 : Number(input.imapPort);
+    if (!Number.isInteger(imapPort) || imapPort < 1 || imapPort > 65535)
+        return { ok: false, message: "The reading port is a number, usually 993." };
+    const password = typeof input.password === "string" && input.password !== "" ? input.password : readEmailSettings(dir)?.password ?? "";
+    writeFileSync(join(dir, EMAIL_FILE), JSON.stringify({ host, port, secure: input.secure === true || input.secure === "on" || input.secure === "true" || port === 465, user, from, password,
+        // 993 is TLS from the start; any other port must upgrade with STARTTLS before the password is sent.
+        imap: imapHost === "" ? null : { host: imapHost, port: imapPort, secure: imapPort === 993 } }), { mode: 0o600 });
+    chmodSync(join(dir, EMAIL_FILE), 0o600);
+    return { ok: true, said: imapHost === "" ? `Email is set up: it comes from ${from}.` : `Email is set up: it comes from ${from}, and Inbox triggers read ${imapHost}.` };
+}

package/dist/envelope.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The machine envelope — the one shape every `--json` answer takes.
+ *
+ * Agents branch on this output ten thousand times a night, so the contract
+ * is versioned and deliberately dull: `envelopeVersion` first, then `ok`,
+ * then `command`, then whatever the command has to say. Failures add a
+ * stable `reason` token and a human `message`. Nothing else about the
+ * shape is promised, and consumers are told to ignore keys they do not
+ * recognize — that is what lets the envelope grow without breaking anyone.
+ *
+ * Every emission in the CLI routes through `envelopeJson` (a source-level
+ * test enforces it), which is also what makes `-o <file>` possible: the
+ * entry point asks this module for the last envelope written and copies it
+ * to the file, so an agent never has to scrape a terminal.
+ */
+export declare const ENVELOPE_VERSION = 1;
+/**
+ * Feature detection for agent consumers, Claude-`system/init` style:
+ * a bounded list of protocol behaviors this build honors. Consumers must
+ * ignore values they do not recognize. Behaviors, not versions — an agent
+ * should ask "can I rely on stable reasons", never "is this 0.1.2".
+ */
+export declare const CAPABILITIES: readonly string[];
+/**
+ * DOCUMENTED reasons — the curated vocabulary the command guide's
+ * `notableReasons` may cite. Deliberately named for what it is: a list of
+ * tokens that are DOCUMENTED, not a proof of runtime exhaustiveness (the
+ * runtime `reason` field remains the truth; consumers branch on tokens
+ * and ignore ones they do not recognize). A test ties every entry to a
+ * literal in the source so a typo cannot ship.
+ */
+export declare const DOCUMENTED_REASONS: readonly string[];
+export type EnvelopePayload = {
+    ok: boolean;
+    command: string;
+    [key: string]: unknown;
+};
+/** The entry point's early-flush hook (arc 2): for long-running commands,
+ * `-o` lands the startup envelope the moment it exists. The hook must not
+ * throw — the entry point's own hook catches internally. */
+export declare function onEnvelopeCaptured(hook: ((body: string) => void) | null): void;
+/** Serialize one envelope, remembering it for `-o` teeing at the entry point. */
+export declare function envelopeJson(payload: EnvelopePayload): string;
+/** The last envelope this process serialized, or null if none has been. */
+export declare function capturedEnvelope(): string | null;
+/** Forget the captured envelope — the entry point calls this before dispatch. */
+export declare function resetCapturedEnvelope(): void;

package/dist/envelope.js

@@ -0,0 +1,105 @@
+/**
+ * The machine envelope — the one shape every `--json` answer takes.
+ *
+ * Agents branch on this output ten thousand times a night, so the contract
+ * is versioned and deliberately dull: `envelopeVersion` first, then `ok`,
+ * then `command`, then whatever the command has to say. Failures add a
+ * stable `reason` token and a human `message`. Nothing else about the
+ * shape is promised, and consumers are told to ignore keys they do not
+ * recognize — that is what lets the envelope grow without breaking anyone.
+ *
+ * Every emission in the CLI routes through `envelopeJson` (a source-level
+ * test enforces it), which is also what makes `-o <file>` possible: the
+ * entry point asks this module for the last envelope written and copies it
+ * to the file, so an agent never has to scrape a terminal.
+ */
+export const ENVELOPE_VERSION = 1;
+/**
+ * Feature detection for agent consumers, Claude-`system/init` style:
+ * a bounded list of protocol behaviors this build honors. Consumers must
+ * ignore values they do not recognize. Behaviors, not versions — an agent
+ * should ask "can I rely on stable reasons", never "is this 0.1.2".
+ */
+export const CAPABILITIES = [
+    "envelope/1", //          every --json answer is one versioned envelope on stdout
+    "stable-reasons", //      failure `reason` is a token that survives rewording
+    "idempotency-keys", //    every mutation takes --key; retries return the first answer
+    "exit-codes/0-1-2-3", //  0 ok · 1 broke · 2 usage · 3 ran fine, answer is no
+    "output-file", //         -o <file> writes the same envelope to a file
+    "command-schema/1", //    contract --commands dumps the declared command guide
+    "skill-guides/1", //      skills list / skills get serve version-matched guides
+    "session-client/1", //    typed operator transport; query the service for actual availability
+];
+/**
+ * DOCUMENTED reasons — the curated vocabulary the command guide's
+ * `notableReasons` may cite. Deliberately named for what it is: a list of
+ * tokens that are DOCUMENTED, not a proof of runtime exhaustiveness (the
+ * runtime `reason` field remains the truth; consumers branch on tokens
+ * and ignore ones they do not recognize). A test ties every entry to a
+ * literal in the source so a typo cannot ship.
+ */
+export const DOCUMENTED_REASONS = [
+    "usage", //             the invocation itself was malformed
+    "database-busy", //     another writer held the selected database for the full wait
+    "unknown-task", //      the named task does not exist
+    "timeout", //           task wait reached its caller-supplied deadline
+    "failed", //            the watched attempt or task failed
+    "needs-person", //      the task reached a decision or approval only a person can provide
+    "unknown-skill", //     the named guide does not exist (skills get)
+    "unconfirmed", //       a preview answered; add --yes to apply
+    "foreign-file", //      an installer target exists but is not managed by it
+    "not-an-approver", //   the credential offered does not authenticate
+    "held", //              somebody else holds it
+    "fenced", //            a newer lease superseded yours — stop
+    "claimed", //           already being worked
+    "unapproved", //        no person has agreed to the scope yet
+    "reserved", //          the task belongs to another worker's queue
+    "external", //          a tracker mirror is not dispatchable (see detail)
+    "contest-open", //      a tournament is running; a person picks
+    "all-lanes-raceable", // every compared agent could hold a real budget — race them instead
+    "provider-unattested", // the provider binary is outside its attested range
+    "daily-runs", //        the active mode's daily run cap is spent
+    "daily-dollars", //     the active mode's daily measured-spend rail is reached
+    "steering-pending", //  a steering note is waiting; contests refuse
+    "not-ready", //         blocked, held, or otherwise not dispatchable
+    "not-leased", //        the lease does not exist or already ended
+    "not-yours", //         held or reserved by someone else
+    "no-op", //             nothing to do — an answer, not an error
+    "duplicate", //         the identity already exists
+    "empty", //             nothing matched
+    "quota", //             a budget or cap refused the act
+    "not-a-repo", //        the path has no .git
+    "stale-approval", //    what would run no longer matches what was approved
+    "profile-unresolved", // the scope cannot say exactly what would run — restate it
+    "repair-attempts-spent", // the chain's signed attempt cap is spent
+    "repair-no-progress", // two consecutive repair attempts failed to shrink the unresolved set
+    "repair-refused-integrity", // a refutation named an altered term, not a gap — no automatic repair
+];
+let captured = null;
+let captureHook = null;
+/** The entry point's early-flush hook (arc 2): for long-running commands,
+ * `-o` lands the startup envelope the moment it exists. The hook must not
+ * throw — the entry point's own hook catches internally. */
+export function onEnvelopeCaptured(hook) {
+    captureHook = hook;
+}
+/** Serialize one envelope, remembering it for `-o` teeing at the entry point. */
+export function envelopeJson(payload) {
+    const body = JSON.stringify({ envelopeVersion: ENVELOPE_VERSION, ...payload }, null, 2);
+    captured = body;
+    try {
+        captureHook?.(body);
+    }
+    catch {
+        // A hook that throws must never reach the command's envelope path.
+    }
+    return body;
+}
+/** The last envelope this process serialized, or null if none has been. */
+export function capturedEnvelope() {
+    return captured;
+}
+/** Forget the captured envelope — the entry point calls this before dispatch. */
+export function resetCapturedEnvelope() {
+    captured = null;
+}

package/dist/evidence-pack.d.ts

@@ -0,0 +1,185 @@
+import { type Filer } from "./approval-policy.js";
+import { type AssignmentAccess, type AssignmentSnapshot } from "./assignment.js";
+import type { SealedLedgerEntry, Store } from "./store.js";
+import type { LedgerChainReport } from "./ledger-chain.js";
+export declare const EVIDENCE_PACK_FORMAT = "standing-orders/evidence-pack/v1";
+/** How to recheck one entry's seal, for whoever reads the JSON. */
+export declare const SEAL_RECIPE = "hash = sha256(prev + \"\\n\" + JSON.stringify([id, at, actor, repo, taskId, runId, action, outcome, source, detail]))";
+type SealedEntry = SealedLedgerEntry;
+export type EvidencePack = {
+    format: typeof EVIDENCE_PACK_FORMAT;
+    generatedAt: string;
+    generatedBy: string;
+    task: {
+        id: string;
+        title: string;
+        state: string;
+        repo: string | null;
+        project: string | null;
+        filedAt: string;
+    };
+    rules: {
+        now: string;
+        changes: {
+            id: number;
+            at: string;
+            by: string;
+            change: string | null;
+        }[];
+    } | null;
+    /** The task and each revision of it, oldest first. */
+    versions: {
+        id: string;
+        title: string;
+        state: string;
+        filedAt: string;
+        filedBy: Filer | null;
+        scope: {
+            goal: string;
+            outOfScope: string | null;
+            touches: string[];
+            acceptance: {
+                id: string;
+                statement: string;
+            }[];
+            budgetUsd: number | null;
+            digest: string;
+            approved: {
+                by: string;
+                at: string;
+                digest: string;
+                basis: "person" | "mode";
+                current: boolean;
+            } | null;
+            writtenBy: {
+                digest: string;
+                author: string;
+                at: string;
+            }[];
+            approvals: {
+                digest: string;
+                approver: string;
+                at: string;
+            }[];
+        } | null;
+        runs: {
+            id: number;
+            role: string;
+            agent: string;
+            model: string | null;
+            outcome: string | null;
+            reason: string | null;
+            base: string | null;
+            head: string | null;
+            startedAt: string;
+            finishedAt: string | null;
+            tokensIn: number | null;
+            tokensOut: number | null;
+            costUsd: number | null;
+            /** The files a build changed (renames on both sides); null when its record can't be read whole. */
+            changedFiles: string[] | null;
+            diff: {
+                sha256: string;
+                bytes: number;
+                complete: boolean;
+            } | null;
+            proof: {
+                verdict: string;
+                decidedAt: string;
+                reasons: string[];
+            } | null;
+            publication: {
+                repo: string;
+                branch: string;
+                commit: string;
+                state: string;
+                pr: number | null;
+                url: string | null;
+                remoteState: string | null;
+                checks: string | null;
+            } | null;
+        }[];
+    }[];
+    result: {
+        runId: number;
+        base: string | null;
+        head: string | null;
+        kind: string | null;
+        checks: {
+            status: string;
+            command: string | null;
+            exitCode: number | null;
+            detail: string;
+        };
+        completedBy: string | null;
+        completedAt: string | null;
+        caveats: string[];
+        publication: AssignmentSnapshot["publication"];
+    } | null;
+    totals: {
+        runs: number;
+        costUsd: number;
+        tokensIn: number;
+        tokensOut: number;
+    };
+    ledger: {
+        entries: SealedEntry[];
+        /** More entries (or requests) exist than a pack carries; the ledger export has them all. */
+        truncated: boolean;
+        /** `checkedAt`: when the whole chain was last walked (entries since were checked as they came). */
+        chain: {
+            ok: boolean;
+            entries: number;
+            through: number | null;
+            head: string;
+            problem: string | null;
+            checkedAt: string | null;
+        };
+        checkpoint: {
+            through: number;
+            hash: string;
+            at: string;
+        } | null;
+        recipe: string;
+    };
+    /** sha256 of this pack's JSON without this field. */
+    digest: string;
+};
+/** The pack for one task (the whole family: the task and every revision), as `who` may see it. null when they can't. */
+export declare function evidencePack(store: Store, taskId: string, access: AssignmentAccess, who: string, now: Date, evidenceRoot: string, checked?: LedgerChainReport): EvidencePack | null;
+export declare function packDigest(body: Omit<EvidencePack, "digest">): string;
+/** A day as the export takes it (YYYY-MM-DD, UTC), or null. */
+export declare function exportDay(value: string | null): string | null;
+export type LedgerExport = {
+    format: "standing-orders/ledger-export/v1";
+    generatedAt: string;
+    generatedBy: string;
+    from: string;
+    to: string;
+    chain: EvidencePack["ledger"]["chain"];
+    checkpoint: EvidencePack["ledger"]["checkpoint"];
+    recipe: string;
+    entries: SealedEntry[];
+    /** An evidence pack for every task the range's entries name. */
+    packs: EvidencePack[];
+    truncated: {
+        entries: boolean;
+        packs: boolean;
+    };
+};
+/** Every ledger entry in [from, to) that `who` may read, sealed, with a pack for each task they name: one JSON
+ * document (a `LedgerExport`), a piece at a time (a page of entries, or one pack), so an export never holds
+ * the whole range at once. */
+export declare function ledgerExportChunks(store: Store, range: {
+    from: string;
+    to: string;
+}, scope: {
+    repos: readonly string[] | null;
+    instance: boolean;
+}, access: AssignmentAccess, who: string, now: Date, evidenceRoot: string): Generator<string, void, undefined>;
+export declare const EVIDENCE_PACK_CSS: string;
+/** The pack as a page: the same facts, in the order an auditor reads them. No script. */
+export declare function evidencePackHtml(pack: EvidencePack): string;
+/** The page as a file on its own (the CLI's --html): the same facts with just enough style to print. */
+export declare function standaloneEvidenceHtml(pack: EvidencePack): string;
+export {};