toolroll 0.5.0

package/dist/discord.js

@@ -0,0 +1,169 @@
+/** A single leased Discord Gateway connection, hosted by the ordinary worker. */
+import { randomBytes } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+import { Client, GatewayIntentBits, Partials } from "discord.js";
+import { loadDiscordCredentials, discordApi, object, discordId, } from "./discord-api.js";
+import { ChatState, chatHash } from "./chat-delivery-state.js";
+import { receiveDiscord, processDiscordEvent, deliverDiscordPart, planDiscordNotifications, planDiscordRooms, } from "./discord-chat.js";
+export function discordReadyMatches(raw, identity) {
+    const packet = object(raw);
+    return (object(packet.application).id === identity.app &&
+        object(packet.user).id === identity.bot &&
+        object(packet.user).bot === true);
+}
+export async function followDiscord(options) {
+    const owner = randomBytes(16).toString("hex"), state = new ChatState(options.store, "discord");
+    const pause = async (ms) => {
+        try {
+            await sleep(ms, undefined, { signal: options.signal });
+        }
+        catch {
+            /* shutdown */
+        }
+    };
+    while (!options.signal.aborted) {
+        const credentials = loadDiscordCredentials(options.dir);
+        if (!credentials ||
+            !state.lease(credentials.installation, owner, new Date())) {
+            await pause(2000);
+            continue;
+        }
+        let alive = true, connected = false, validated = false;
+        const same = () => {
+            const current = loadDiscordCredentials(options.dir);
+            return (alive &&
+                !options.signal.aborted &&
+                current?.installation === credentials.installation &&
+                current.botToken === credentials.botToken &&
+                state.owns(credentials.installation, owner));
+        };
+        const problem = (message) => state
+            .prepare("UPDATE chat_runtime SET problem=? WHERE installation=? AND owner=?")
+            .run(message, credentials.installation, owner);
+        const api = discordApi(credentials.botToken);
+        const client = new Client({
+            // Guild messages and their content are needed for rooms; the Message
+            // Content intent must be enabled for the app in Discord's developer portal.
+            intents: [GatewayIntentBits.DirectMessages, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
+            partials: [Partials.Channel],
+            allowedMentions: { parse: [], repliedUser: false },
+            rest: { timeout: 15_000, retries: 2 },
+        });
+        const stop = () => {
+            alive = false;
+            connected = false;
+            void client.destroy().catch(() => { });
+        };
+        options.signal.addEventListener("abort", stop, { once: true });
+        const heartbeat = setInterval(() => {
+            if (!same() || !state.lease(credentials.installation, owner, new Date()))
+                stop();
+        }, 10_000);
+        const online = () => {
+            if (!same() || !validated)
+                return;
+            connected = true;
+            state
+                .prepare("UPDATE chat_runtime SET connected=?,problem=NULL WHERE installation=? AND owner=?")
+                .run(new Date().toISOString(), credentials.installation, owner);
+        };
+        client.on("shardReady", online);
+        client.on("shardResume", online);
+        client.on("shardDisconnect", () => {
+            connected = false;
+            problem("Discord is disconnected; saved replies will retry.");
+        });
+        client.on("shardReconnecting", () => {
+            connected = false;
+            problem("Reconnecting to Discord…");
+        });
+        client.on("error", () => problem("Discord connection failed. Check the bot token and reconnect."));
+        client.on("shardError", () => problem("Discord connection failed. Saved replies will retry."));
+        // Never subscribe a logger to raw payloads, SDK debug output or interaction tokens.
+        client.on("raw", (packet) => {
+            if (!same())
+                return;
+            if (packet.t === "READY") {
+                validated = discordReadyMatches(packet.d, credentials);
+                if (!validated) {
+                    problem("Discord returned a different app identity. Disconnect and reconnect the intended app.");
+                    stop();
+                }
+                else
+                    online();
+                return;
+            }
+            if (!validated)
+                return;
+            const body = object(packet.d);
+            try {
+                const saved = receiveDiscord(state, credentials, packet.t, body, new Date());
+                if (packet.t === "INTERACTION_CREATE" &&
+                    body.type === 3 &&
+                    body.application_id === credentials.app &&
+                    discordId(body.id) &&
+                    typeof body.token === "string" &&
+                    /^[A-Za-z0-9._-]{1,300}$/.test(body.token)) {
+                    const repeated = state.event(chatHash(`${credentials.installation}:interaction:${body.id}`)) !== null;
+                    // Immediate acknowledgement; model work and approvals are handled from the durable queue.
+                    void api("POST", `/interactions/${body.id}/${body.token}/callback`, saved || repeated
+                        ? { type: 6 }
+                        : {
+                            type: 4,
+                            data: {
+                                content: "This button is unavailable. Use your paired direct message or ask for the current state.",
+                                flags: 64,
+                                allowed_mentions: { parse: [] },
+                            },
+                        }).catch(() => problem("Discord did not acknowledge the button. Its saved result will appear in the conversation."));
+                }
+            }
+            catch {
+                problem("An incoming Discord message could not be saved. Send it again after reconnecting.");
+            }
+        });
+        const chat = {
+            ...options,
+            identity: credentials,
+            owner,
+            api,
+            current: same,
+            canNotify: options.notifications,
+        };
+        try {
+            await client.login(credentials.botToken);
+            while (same()) {
+                const retry = state
+                    .prepare("SELECT retry_at FROM chat_runtime WHERE installation=?")
+                    .get(credentials.installation)?.retry_at;
+                if (!connected ||
+                    (typeof retry === "string" && retry > new Date().toISOString())) {
+                    await pause(1000);
+                    continue;
+                }
+                await processDiscordEvent(chat);
+                if (same())
+                    await planDiscordRooms(chat);
+                if (same())
+                    await deliverDiscordPart(chat);
+                if (same() && options.notifications())
+                    await planDiscordNotifications(chat);
+                await pause(1000);
+            }
+        }
+        catch {
+            if (alive)
+                problem("Discord is unavailable. Retrying shortly.");
+        }
+        finally {
+            clearInterval(heartbeat);
+            alive = false;
+            options.signal.removeEventListener("abort", stop);
+            await client.destroy().catch(() => { });
+            state
+                .prepare("UPDATE chat_runtime SET owner=NULL,lease_until=NULL,connected=NULL WHERE installation=? AND owner=?")
+                .run(credentials.installation, owner);
+        }
+        await pause(5000);
+    }
+}

package/dist/discover.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Reading the state of repositories.
+ *
+ * Every git invocation here is a read, and every one is prefixed with
+ * `--no-optional-locks` — Toolroll scans repositories the operator may be
+ * working in right now, and a discovery pass must never contend for the index
+ * lock with their editor.
+ *
+ * Nothing raises. A repository that cannot be read comes back as a snapshot
+ * carrying a named problem, because the alternative is a scan of forty repos
+ * ending on the one that is broken.
+ *
+ * The reads are deliberately unequal in cost, and that shapes the module.
+ * Listing refs, worktrees and the remote is O(refs) and lands in tens of
+ * milliseconds. Computing ahead/behind walks history per branch — measured at
+ * 22s on a cold 304MB repo — so it is bounded and degrades to a branch list
+ * without it. Reading the working tree is O(working tree), measured at over
+ * two minutes, so it does not happen at all unless asked for.
+ */
+import { type ExecResult, type RunOptions } from "./exec.js";
+import { type Branch, type Worktree } from "./git.js";
+import { type ScanOptions } from "./scan.js";
+export type RepoSnapshot = {
+    path: string;
+    name: string;
+    /** Current branch, or null in detached HEAD. */
+    head: string | null;
+    remoteUrl: string | null;
+    branches: Branch[];
+    worktrees: Worktree[];
+    /** Uncommitted files, or null when the working tree was not read. */
+    dirtyFiles: number | null;
+    /**
+     * Whether ahead/behind could be computed. False means every branch carries a
+     * zeroed track, which is absence of data and not evidence of being in sync —
+     * a distinction the report has to respect or it hides the whole repository.
+     */
+    hasTracking: boolean;
+    /** What could not be read, in words. Never silently dropped. */
+    problems: string[];
+};
+export type Runner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
+export type InspectOptions = {
+    runner?: Runner;
+    /** Read the working tree for uncommitted changes. Off by default: see above. */
+    dirty?: boolean;
+};
+export type DiscoverOptions = InspectOptions & {
+    scan?: ScanOptions;
+    concurrency?: number;
+};
+/** Enough to keep git busy without turning a laptop fan on. */
+export declare const DEFAULT_CONCURRENCY = 8;
+/** Ref reads land in tens of milliseconds; seconds here means something is wrong. */
+export declare const REF_TIMEOUT_MS = 5000;
+/**
+ * Ahead/behind is worth waiting for, since it is the signal itself. Ten
+ * seconds because a 59MB repo with 18 branches and no commit-graph measured
+ * 7.5s cold — just over a five second bound, which is the worst place for a
+ * limit to sit.
+ */
+export declare const TRACK_TIMEOUT_MS = 10000;
+/** The working tree is unbounded, so the bound has to be ours. */
+export declare const STATUS_TIMEOUT_MS = 10000;
+export declare function inspectRepo(path: string, options?: InspectOptions): Promise<RepoSnapshot>;
+/**
+ * Inspect known repositories, skipping the walk entirely. Enrolled paths are
+ * already the answer to "which repositories" — searching for them again would
+ * be the tool distrusting a list the operator wrote down.
+ */
+export declare function inspectAll(paths: readonly string[], options?: InspectOptions & {
+    concurrency?: number;
+}): Promise<RepoSnapshot[]>;
+/** Every repository at or below `roots`, inspected with bounded concurrency. */
+export declare function discover(roots: readonly string[], options?: DiscoverOptions): Promise<RepoSnapshot[]>;

package/dist/discover.js

@@ -0,0 +1,150 @@
+/**
+ * Reading the state of repositories.
+ *
+ * Every git invocation here is a read, and every one is prefixed with
+ * `--no-optional-locks` — Toolroll scans repositories the operator may be
+ * working in right now, and a discovery pass must never contend for the index
+ * lock with their editor.
+ *
+ * Nothing raises. A repository that cannot be read comes back as a snapshot
+ * carrying a named problem, because the alternative is a scan of forty repos
+ * ending on the one that is broken.
+ *
+ * The reads are deliberately unequal in cost, and that shapes the module.
+ * Listing refs, worktrees and the remote is O(refs) and lands in tens of
+ * milliseconds. Computing ahead/behind walks history per branch — measured at
+ * 22s on a cold 304MB repo — so it is bounded and degrades to a branch list
+ * without it. Reading the working tree is O(working tree), measured at over
+ * two minutes, so it does not happen at all unless asked for.
+ */
+import { basename } from "node:path";
+import { run } from "./exec.js";
+import { parseWorktrees, parseBranches } from "./git.js";
+import { findRepos } from "./scan.js";
+/** Enough to keep git busy without turning a laptop fan on. */
+export const DEFAULT_CONCURRENCY = 8;
+/** Ref reads land in tens of milliseconds; seconds here means something is wrong. */
+export const REF_TIMEOUT_MS = 5_000;
+/**
+ * Ahead/behind is worth waiting for, since it is the signal itself. Ten
+ * seconds because a 59MB repo with 18 branches and no commit-graph measured
+ * 7.5s cold — just over a five second bound, which is the worst place for a
+ * limit to sit.
+ */
+export const TRACK_TIMEOUT_MS = 10_000;
+/** The working tree is unbounded, so the bound has to be ours. */
+export const STATUS_TIMEOUT_MS = 10_000;
+const GIT = "git";
+/** Read-only, and refuses to take the index lock it would otherwise want. */
+const READ_ONLY = ["--no-optional-locks"];
+const HEADS = "refs/heads";
+const BRANCH_FORMAT = "--format=%(refname:short)%09%(upstream:track)%09%(committerdate:iso8601-strict)";
+/** The same three columns with the expensive one left empty. */
+const BRANCH_FORMAT_CHEAP = "--format=%(refname:short)%09%09%(committerdate:iso8601-strict)";
+export async function inspectRepo(path, options = {}) {
+    const { runner = run, dirty = false } = options;
+    const git = (args, timeoutMs = REF_TIMEOUT_MS) => runner(GIT, [...READ_ONLY, ...args], { cwd: path, timeoutMs });
+    const [worktrees, branchRead, head, remote, status] = await Promise.all([
+        git(["worktree", "list", "--porcelain"]),
+        readBranches(git),
+        git(["symbolic-ref", "--quiet", "--short", "HEAD"]),
+        git(["remote", "get-url", "origin"]),
+        dirty ? git(["status", "--porcelain"], STATUS_TIMEOUT_MS) : null,
+    ]);
+    // One missing binary is one problem, not five identical ones.
+    if (worktrees.notFound) {
+        return { ...emptySnapshot(path), problems: ["git is not installed"] };
+    }
+    const branches = branchRead.result;
+    const problems = [
+        describeProblem("read worktrees", worktrees),
+        describeProblem("read branches", branches),
+        branchRead.degraded
+            ? `ahead/behind skipped: it took over ${TRACK_TIMEOUT_MS / 1000}s to compute here`
+            : null,
+        status === null ? null : describeProblem("read the working tree", status),
+    ].filter((problem) => problem !== null);
+    return {
+        path,
+        name: basename(path),
+        // A failed symbolic-ref means detached HEAD, which is a state and not a fault.
+        head: head.code === 0 ? head.stdout.trim() : null,
+        // A repo with no origin is ordinary; reporting it as an error would be noise.
+        remoteUrl: remote.code === 0 ? remote.stdout.trim() : null,
+        branches: branches.code === 0 ? parseBranches(branches.stdout) : [],
+        worktrees: worktrees.code === 0 ? parseWorktrees(worktrees.stdout) : [],
+        dirtyFiles: status !== null && status.code === 0 ? countLines(status.stdout) : null,
+        hasTracking: branches.code === 0 && !branchRead.degraded,
+        problems,
+    };
+}
+/**
+ * Ahead/behind is the whole point of the report, so it is tried first — but a
+ * branch list without it beats a timeout with nothing in it.
+ */
+async function readBranches(git) {
+    const rich = await git(["for-each-ref", BRANCH_FORMAT, HEADS], TRACK_TIMEOUT_MS);
+    if (!rich.timedOut)
+        return { result: rich, degraded: false };
+    const cheap = await git(["for-each-ref", BRANCH_FORMAT_CHEAP, HEADS], REF_TIMEOUT_MS);
+    return { result: cheap, degraded: cheap.code === 0 };
+}
+/**
+ * Inspect known repositories, skipping the walk entirely. Enrolled paths are
+ * already the answer to "which repositories" — searching for them again would
+ * be the tool distrusting a list the operator wrote down.
+ */
+export async function inspectAll(paths, options = {}) {
+    const { runner = run, dirty = false, concurrency = DEFAULT_CONCURRENCY } = options;
+    return mapWithConcurrency(paths, concurrency, path => inspectRepo(path, { runner, dirty }));
+}
+/** Every repository at or below `roots`, inspected with bounded concurrency. */
+export async function discover(roots, options = {}) {
+    const { scan, ...rest } = options;
+    return inspectAll(await findRepos(roots, scan), rest);
+}
+function emptySnapshot(path) {
+    return {
+        path,
+        name: basename(path),
+        head: null,
+        remoteUrl: null,
+        branches: [],
+        worktrees: [],
+        dirtyFiles: null,
+        hasTracking: false,
+        problems: [],
+    };
+}
+function describeProblem(action, result) {
+    if (result.code === 0)
+        return null;
+    if (result.timedOut)
+        return `could not ${action}: timed out`;
+    return `could not ${action}: ${firstLine(result.stderr)}`;
+}
+function firstLine(text) {
+    const [line = ""] = text.trim().split("\n");
+    return line;
+}
+function countLines(text) {
+    return text.split("\n").filter(line => line.trim() !== "").length;
+}
+/**
+ * Results stay in input order regardless of completion order, so the output of
+ * a scan does not depend on which repository happened to answer first.
+ */
+async function mapWithConcurrency(items, limit, worker) {
+    const results = new Array(items.length);
+    let next = 0;
+    const consume = async () => {
+        while (next < items.length) {
+            const index = next++;
+            const item = items[index];
+            results[index] = await worker(item);
+        }
+    };
+    const lanes = Math.max(1, Math.min(limit, items.length));
+    await Promise.all(Array.from({ length: lanes }, consume));
+    return results;
+}

package/dist/dispatch.d.ts

@@ -0,0 +1,100 @@
+/**
+ * One read-side answer to "will this task run?"
+ *
+ * The atomic claim remains the authority. This module owns the task-local
+ * predicates that claim re-proves under its write transaction, then layers
+ * fleet observations on top for people and agents reading the queue. A
+ * diagnosis can go stale; it can never grant a lease.
+ */
+import { type ChatSnapshot, type ReviewRequestOrigin, type ReviewRetryState, type Store, type TaskState } from "./store.js";
+export declare const DEFAULT_MAX_OPEN_DECISIONS = 5;
+export type TaskReadinessBlocker = {
+    code: "unknown-task";
+    message: string;
+} | {
+    code: "state";
+    state: TaskState;
+    message: string;
+} | {
+    code: "hold";
+    ownerKind: string;
+    until: string | null;
+    message: string;
+} | {
+    code: "dependency";
+    blockerId: string;
+    blockerState: TaskState;
+    message: string;
+};
+export type DispatchAction = "open-result" | "retry-task" | "place-task" | "write-scope" | "select-agent" | "approve-scope" | "answer-decision" | "unhold" | "inspect-hold" | "repair-dependency" | "repair-capability" | "start-worker"
+/** v50: ask for the bounded explicit review retry (`task review <run>`
+ * or the console's Retry review). */
+ | "retry-review"
+/** v52: resume the exact stopped attempt (`task resume <id> --run <n>`
+ * or the console's Resume). */
+ | "resume-run";
+export type DispatchDiagnosisCode = "updating" | "complete" | "needs-verification" | "proof-refuted" | "review-pending" | "reviewing" | "review-failed"
+/** v50: every root review attempt ended without a review; nothing retries. */
+ | "review-exhausted" | "cancelled" | "failed" | "running" | "vanished-run" | "retry-scheduled" | "waiting-decision" | "waiting-incident" | "held"
+/** v52: an operator stopped one exact attempt; only resuming it lifts the pause. */
+ | "stopped" | "waiting-dependency" | "terminal-dependency" | "needs-project" | "needs-scope" | "needs-agent-profile" | "needs-approval" | "missing-requirement" | "no-worker-registered" | "no-worker-online" | "worker-at-capacity" | "provider-quota" | "planning-ready" | "planner-source" | "scouting-ready" | "ready";
+export type DispatchDiagnosis = {
+    /** The four-state Never Stuck contract. */
+    condition: "running" | "retrying" | "waiting" | "terminal";
+    code: DispatchDiagnosisCode;
+    summary: string;
+    detail: string;
+    action: DispatchAction | null;
+    /** When the machine already knows the next automatic wake. */
+    nextAt: string | null;
+    /** The phase an eventual claim would dispatch. */
+    role: "builder" | "planner" | "scout" | null;
+    blockerTaskId: string | null;
+    /** v50: the finished build's bounded review-retry status — null until a
+     * review was ever asked for, and on every task that is not done. */
+    review: ReviewDispatchView | null;
+};
+/** The typed review-retry facts a dispatch reader gets (v50): the source
+ * build, the projection's state word, how many root attempts ran and how
+ * many explicit retries remain, and the latest attempt's recorded reason. */
+export type ReviewDispatchView = {
+    sourceRun: number;
+    state: ReviewRetryState["state"];
+    /** The attempt running, queued, or most recently ended (1..cap); null before any. */
+    attempt: number | null;
+    cap: number;
+    retriesUsed: number;
+    retriesRemaining: number;
+    /** The most recently ended root attempt's run id and stored reason. */
+    latestRun: number | null;
+    latestReason: string | null;
+    interrupted: boolean;
+    /** The open ask, when one is queued: who asked and how it was produced
+     * (explicit-only retries: a retry is always an operator's ask; an
+     * automatic producer queues attempt 1 only). */
+    queued: {
+        requestedBy: string;
+        origin: ReviewRequestOrigin;
+    } | null;
+};
+/**
+ * Task state, active holds, and unfinished dependencies in the exact order
+ * acquireIfReady checks them. The claim path calls this while holding its
+ * write transaction; read surfaces call it only as a snapshot.
+ */
+export declare function taskReadinessBlocker(store: Store, taskRef: number, now: Date): TaskReadinessBlocker | null;
+/** The exact live approval predicate used by both the scheduler survey and
+ * the atomic claim. Mode-backed approvals count only while their signer and
+ * mode still stand. */
+export declare function scopeApprovedForDispatch(store: Store, taskRef: number, now: Date): boolean;
+/** The phase the ordinary dispatch loop would choose before it resolves an
+ * agent. Attended authorization is deliberately outside this ordinary path. */
+export declare function dispatchRoleFor(store: Store, taskRef: number, now: Date): "builder" | "planner" | "scout";
+/** The first requirement this task fails, in words, or null. */
+export declare function missingCapability(store: Store, taskRef: number, dispatchRepo: string | null, now: Date): string | null;
+/** The read-side lifecycle answer. It changes nothing and grants nothing. */
+export declare function diagnoseTaskDispatch(store: Store, taskId: string, now: Date): DispatchDiagnosis | null;
+export declare function diagnosisIsDispatchable(diagnosis: DispatchDiagnosis | null): boolean;
+/** Attach the same lifecycle answer to the bounded fleet snapshot used by
+ * both direct chat and the long-running mate. */
+export declare function withDispatchDiagnoses(store: Store, snapshot: ChatSnapshot, now: Date): ChatSnapshot;