@armanckeser/downstream 0.0.0-stage → 0.1.0

package/dist/domain/approval.js

@@ -0,0 +1,190 @@
+// Which of the agent's tool calls run without asking you. Reading never needs
+// permission; changing anything (files, git history, GitHub) does, and so does
+// sending the review, which the agent must never do on its own.
+/** Tools that only read. */
+const READ_TOOLS = new Set(["Read", "Grep", "Glob", "LS", "NotebookRead", "TodoWrite", "WebFetch", "WebSearch", "Skill", "ToolSearch", "Agent", "Task", "TaskOutput"]);
+/**
+ * Shell commands that only read, and the flags that would make them run or
+ * write something (`rg --pre`, `fd --exec`, `sort -o`, `sed -i`, `find -delete`).
+ */
+const READ_COMMANDS = {
+    cat: null, head: null, tail: null, wc: null, ls: null, grep: null, cut: null, tr: null, echo: null, printf: null, pwd: null,
+    which: null, file: null, stat: null, diff: null, basename: null, dirname: null, realpath: null, true: null, jq: null, nl: null, column: null, uniq: null,
+    read: null,
+    rg: /^--pre/,
+    fd: /^(-x|-X|--exec|--exec-batch)/,
+    sort: /^(-o|--output)/,
+    tree: /^-o$/,
+    sed: /^(-i|--in-place)/,
+    find: /^-(exec|execdir|delete|ok|fprint)/,
+};
+const GIT_READ = new Set(["log", "show", "diff", "status", "rev-parse", "merge-base", "ls-files", "blame", "grep", "fetch", "cat-file", "describe", "shortlog", "rev-list", "ls-tree", "remote"]);
+const GH_READ = {
+    pr: new Set(["view", "diff", "checks", "list", "status"]),
+    repo: new Set(["view"]),
+    run: new Set(["view", "list"]),
+    issue: new Set(["view", "list"]),
+};
+/** Downstream subcommands that publish: always yours to approve. */
+const DOWNSTREAM_PUBLISH = new Set(["send"]);
+/**
+ * `skillDir` is where Downstream lives, so `node <skillDir>/bin/downstream.mjs …`
+ * is recognized as the Downstream CLI.
+ */
+export function autoApprove(tool, input, skillDir) {
+    if (READ_TOOLS.has(tool))
+        return { allow: true };
+    if (tool !== "Bash")
+        return { allow: false, reason: `${tool} can change things` };
+    const command = typeof input.command === "string" ? input.command : "";
+    return readOnlyShell(command, skillDir);
+}
+function readOnlyShell(command, skillDir) {
+    // Discard harmless stderr plumbing first, then refuse anything that could write or hide a second command.
+    const plain = command.replace(/\s2>&1/g, " ").replace(/\s2>\s*\/dev\/null/g, " ");
+    const substituted = substitutions(plain, skillDir);
+    if ("allow" in substituted)
+        return substituted;
+    if (/[>`]|\$\(|<\(|\bsudo\b/.test(substituted.rest))
+        return { allow: false, reason: "redirects, substitutions or sudo" };
+    for (const raw of substituted.rest.split(/&&|\|\||;|\||\n/)) {
+        const words = withoutLoopKeywords(raw.trim().split(/\s+/).filter(Boolean));
+        if (words.length === 0)
+            continue;
+        const verdict = readOnlyCommand(words, skillDir);
+        if (!verdict.allow)
+            return verdict;
+    }
+    return { allow: true };
+}
+/** Stands in for a `$(…)` already judged read-only: an expansion like `$f`, so it gets the same suspicion. */
+const SUBSTITUTED = "$SUBSTITUTED";
+/** Judge each `$(…)` on its own and replace it with an expansion; a refusal inside refuses the whole command. */
+function substitutions(command, skillDir) {
+    let rest = command;
+    for (let start = rest.indexOf("$("); start !== -1; start = rest.indexOf("$(")) {
+        const end = closingParen(rest, start + 2);
+        if (end === -1)
+            return { allow: false, reason: "an unclosed substitution" };
+        const inner = readOnlyShell(rest.slice(start + 2, end), skillDir);
+        if (!inner.allow)
+            return inner;
+        rest = `${rest.slice(0, start)}${SUBSTITUTED}${rest.slice(end + 1)}`;
+    }
+    return { rest };
+}
+function closingParen(text, from) {
+    let depth = 1;
+    for (let i = from; i < text.length; i++) {
+        if (text[i] === "(")
+            depth++;
+        if (text[i] === ")" && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+/** `for f in …; do cat $f; done`: the loop's words are syntax; what runs is the command after them. */
+function withoutLoopKeywords(words) {
+    const [first] = words;
+    if (first === "done" || first === "fi")
+        return words.slice(1);
+    if (first === "for")
+        return [];
+    if (first === "do" || first === "then" || first === "else" || first === "while" || first === "until" || first === "if")
+        return withoutLoopKeywords(words.slice(1));
+    return words;
+}
+/** Programs people often call by path (`~/.local/bin/gh`, `/usr/bin/git`): judged by name, like the bare command. */
+const BY_NAME = new Set(["gh", "git"]);
+function readOnlyCommand(words, skillDir) {
+    const [first, ...args] = words;
+    const base = first.split("/").at(-1);
+    const cmd = first.includes("/") && BY_NAME.has(base) ? base : first;
+    if (cmd === "cd")
+        return { allow: true };
+    if (cmd.includes("$"))
+        return { allow: false, reason: "the program itself is an expansion" };
+    // An expanded value is unseen text: `git show $f` with f = `x --output=~/.zshrc` writes a file. Only programs no flag can turn into a write take one.
+    const expanded = args.some((a) => a.includes("$"));
+    if (Object.hasOwn(READ_COMMANDS, cmd)) {
+        const risky = READ_COMMANDS[cmd];
+        if (risky && expanded)
+            return { allow: false, reason: `an expanded argument to ${cmd} could be a flag` };
+        const flag = risky ? args.find((a) => risky.test(a)) : undefined;
+        return flag ? { allow: false, reason: `${cmd} ${flag} can run or write` } : { allow: true };
+    }
+    const downstreamArgs = downstreamCall(cmd, args, skillDir);
+    if ((cmd === "git" || cmd === "gh" || downstreamArgs) && expanded)
+        return { allow: false, reason: `an expanded argument to ${cmd} could be a flag or a send` };
+    if (cmd === "git")
+        return gitRead(args);
+    if (cmd === "gh")
+        return ghRead(args);
+    if (downstreamArgs) {
+        const [sub, ...rest] = downstreamArgs;
+        const publishes = (sub !== undefined && DOWNSTREAM_PUBLISH.has(sub)) || rest.some((a) => a.includes("review.publish"));
+        return publishes ? { allow: false, reason: "sending the review is yours to approve" } : { allow: true };
+    }
+    return { allow: false, reason: `${cmd} isn't known to be read-only` };
+}
+/** The args after `downstream`, if this is the Downstream CLI. */
+function downstreamCall(cmd, args, skillDir) {
+    if (cmd === "downstream")
+        return args;
+    const script = args[0]?.replace(/^["']|["']$/g, "");
+    const ours = script === `${skillDir}/bin/downstream.mjs` || script?.endsWith("/bin/downstream.mjs");
+    return cmd === "node" && ours ? args.slice(1) : null;
+}
+function gitRead(args) {
+    const rest = args[0] === "-C" ? args.slice(2) : args;
+    const sub = rest[0];
+    if (rest.some((a) => a.startsWith("--output") || a.startsWith("--ext-diff")))
+        return { allow: false, reason: "git writing to a file or running a diff tool" };
+    if (sub === "branch" || sub === "worktree") {
+        const listing = sub === "branch" ? !rest.slice(1).some((a) => /^-[dDmMcC]|^--(delete|move|copy)/.test(a)) : rest[1] === "list";
+        return listing ? { allow: true } : { allow: false, reason: `git ${sub} can change things` };
+    }
+    if (sub === "remote" && rest.length > 2)
+        return { allow: false, reason: "git remote can change things" };
+    return sub && GIT_READ.has(sub) ? { allow: true } : { allow: false, reason: `git ${sub ?? ""} can change things`.trim() };
+}
+function ghRead(args) {
+    const [group, verb] = args;
+    if (group === "api") {
+        const at = args.findIndex((a) => a === "-X" || a === "--method");
+        const writes = at !== -1 && args[at + 1]?.toUpperCase() !== "GET";
+        const graphql = args[1] === "graphql";
+        const fields = args.some((a) => /^(-f|-F|--field|--raw-field|--input)$/.test(a));
+        if (writes)
+            return { allow: false, reason: "gh api with a write method" };
+        if (graphql)
+            return args.some((a) => /\bmutation\b/.test(a)) ? { allow: false, reason: "a GraphQL mutation" } : { allow: true };
+        return fields ? { allow: false, reason: "gh api with fields posts" } : { allow: true };
+    }
+    return group && verb && GH_READ[group]?.has(verb) ? { allow: true } : { allow: false, reason: `gh ${group ?? ""} ${verb ?? ""} can change things`.trim() };
+}
+/**
+ * Commands that reach other people: sending the review, posting or merging on
+ * GitHub, pushing. The agent runs in auto mode, where a classifier approves
+ * most calls; these always come to you, whatever the classifier would say.
+ * Matched across the whole command, so a push inside `$(…)` or after `&&` counts.
+ */
+const OUTWARD = [
+    [/\bdownstream(\.mjs)?["']?\s+send\b/, "sending the review"],
+    [/\breview\.publish\b/, "sending the review"],
+    [/\bgit\b(\s+-C\s+\S+)?\s+push\b/, "pushing to GitHub"],
+    [/\bgh\s+pr\s+(review|comment|merge|close|reopen|create|edit|ready)\b/, "changing a pull request on GitHub"],
+    [/\bgh\s+issue\s+(comment|create|close|reopen|edit)\b/, "changing an issue on GitHub"],
+    [/\bgh\s+(release|repo)\s+(create|delete|edit)\b/, "changing a repository on GitHub"],
+    [/\bgh\s+api\b[^|;&]*(-X|--method)[\s=]*(POST|PATCH|PUT|DELETE)\b/i, "writing through the GitHub API"],
+    [/\bgh\s+api\s+graphql\b[^|;&]*\bmutation\b/, "a GitHub GraphQL mutation"],
+];
+export function reachesOthers(tool, input) {
+    if (tool !== "Bash")
+        return null;
+    const command = typeof input.command === "string" ? input.command : "";
+    const restFields = /\bgh\s+api\s+(?!graphql\b)[^|;&]*\s(-f|-F|--field|--raw-field|--input)\s/.test(command) && !/(-X|--method)[\s=]*GET\b/i.test(command);
+    if (restFields)
+        return "writing through the GitHub API";
+    return OUTWARD.find(([pattern]) => pattern.test(command))?.[1] ?? null;
+}

package/dist/domain/delivery.js

@@ -0,0 +1,21 @@
+/** Null when there's nothing to wait on: the thread is settled, or the agent spoke last. */
+export function delivery(note, readThrough, presence) {
+    if (note.status !== "open")
+        return null;
+    const last = note.replies.at(-1) ?? note;
+    if (last.author !== "user")
+        return null;
+    const read = readThrough !== null && last.createdAt <= readThrough;
+    if (!read)
+        return "unread";
+    // A plain note or flag doesn't ask for an answer, so a busy agent isn't "answering" it.
+    const expectsAnswer = note.kind === "question" || note.replies.length > 0;
+    switch (presence.agent) {
+        case "working":
+            return expectsAnswer ? "answering" : "read";
+        case "listening":
+            return "read";
+        case "away":
+            return expectsAnswer ? "stalled" : "read";
+    }
+}

package/dist/domain/home.js

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

package/dist/domain/inbox.js

@@ -0,0 +1,245 @@
+// The inbox: every open pull request you're part of, reduced to the one thing
+// it needs from you next (Getting Things Done: one next action each; what waits
+// on someone else goes to its own list), then sorted into the Eisenhower matrix:
+// urgent when a person is blocked on you, important when it's part of what
+// you're working on. Downstream makes the first read; yours replaces it.
+import { z } from "zod";
+export const Checks = z.enum(["passing", "failing", "pending", "none"]);
+export const Mergeable = z.enum(["mergeable", "conflicting", "unknown"]);
+export const ReviewDecision = z.enum(["approved", "changes_requested", "review_required"]);
+const TouchAt = z.object({ at: z.string(), how: z.enum(["reviewed", "commented", "opened", "pushed"]) });
+/** What the author did after your last review that hands the PR back to you. */
+const AuthorAct = z.object({ how: z.enum(["pushed", "replied"]), at: z.string() });
+/** A pull request as GitHub describes it, from the point of view of one account. */
+export const PrFacts = z.object({
+    repo: z.string(),
+    number: z.number().int(),
+    title: z.string(),
+    url: z.string(),
+    author: z.string(),
+    /** Bots (GitHub Apps) open PRs as your delegated work, not as someone waiting on you. */
+    authorKind: z.enum(["person", "bot"]),
+    /** What people call the author ("Annie Edison"), when GitHub knows it. */
+    authorName: z.string().nullable(),
+    authorAvatar: z.string().nullable(),
+    isDraft: z.boolean(),
+    updatedAt: z.string(),
+    baseRef: z.string(),
+    headRef: z.string(),
+    headSha: z.string(),
+    reviewDecision: ReviewDecision.nullable(),
+    checks: Checks,
+    mergeable: Mergeable,
+    unresolvedThreads: z.number().int(),
+    /** Whether this account wrote the PR or is (or was) asked to review it. */
+    role: z.enum(["author", "reviewer"]),
+    /** A review from this account is requested right now. */
+    reviewRequested: z.boolean(),
+    /** When this account last reviewed, if it ever did. */
+    myReviewAt: z.string().nullable(),
+    /** The author's latest push or reply after that review. Null when there is none, or no review. */
+    authorSince: AuthorAct.nullable(),
+    /** GitHub's native stacks (`gh stack`): position 1 sits on the base branch. */
+    stack: z.object({ number: z.number().int(), size: z.number().int(), position: z.number().int() }).nullable(),
+    /** The last time this account reviewed, commented on, opened or pushed to it, from its event feed. */
+    touched: TouchAt.nullable(),
+});
+/** Attach each PR's latest touch. `touches` is newest first, as GitHub returns it. */
+export function withTouches(prs, touches) {
+    return prs.map((pr) => {
+        const hit = touches.find((t) => t.repo === pr.repo && (t.number === pr.number || (t.branch !== null && t.branch === pr.headRef)));
+        return hit ? { ...pr, touched: { at: hit.at, how: hit.how } } : pr;
+    });
+}
+/**
+ * How each move reads and what pressing it does. `review` opens Downstream with
+ * the agent; `agent` starts the agent on the task; `github` opens the PR.
+ * Rank orders the action list: two-minute actions first (GTD's two-minute rule),
+ * then whoever is blocked on you, then your own fixes.
+ */
+export const MOVES = {
+    merge: { verb: "Merge", rank: 0, opens: "github" },
+    review: { verb: "Review", rank: 1, opens: "review" },
+    rereview: { verb: "Re-review", rank: 2, opens: "review" },
+    "address-feedback": { verb: "Address feedback", rank: 3, opens: "agent" },
+    "resolve-conflicts": { verb: "Resolve conflicts", rank: 4, opens: "agent" },
+    "fix-checks": { verb: "Fix checks", rank: 5, opens: "agent" },
+    "finish-draft": { verb: "Finish draft", rank: 6, opens: "agent" },
+    waiting: { verb: "Waiting", rank: 99, opens: "github" },
+};
+export const WAITING_ON = {
+    author: "the author",
+    reviewers: "reviewers",
+    checks: "checks",
+    "lower-layer": "the PR below it",
+};
+/**
+ * The next action for a single PR, ignoring the stack it may sit in. Once you
+ * have reviewed, the PR is the author's turn until they push, reply or ask you
+ * again. Commit ids can't tell this: a review posted on a commit the author
+ * force-pushed away mid-review would look like new work forever.
+ */
+export function moveFor(pr) {
+    if (pr.role === "reviewer")
+        return reviewerMove(pr);
+    if (pr.mergeable === "conflicting")
+        return { kind: "resolve-conflicts" };
+    if (pr.checks === "failing")
+        return { kind: "fix-checks" };
+    if (pr.reviewDecision === "changes_requested" || pr.unresolvedThreads > 0)
+        return { kind: "address-feedback", threads: pr.unresolvedThreads };
+    if (pr.isDraft)
+        return { kind: "finish-draft" };
+    if (pr.checks === "pending")
+        return { kind: "waiting", on: "checks" };
+    if (pr.reviewDecision === "approved" && pr.mergeable === "mergeable")
+        return { kind: "merge" };
+    return { kind: "waiting", on: "reviewers" };
+}
+function reviewerMove(pr) {
+    if (pr.myReviewAt === null)
+        return pr.reviewRequested ? { kind: "review" } : { kind: "waiting", on: "author" };
+    // Reviewing fulfils a request, so a request standing after your review was made again.
+    if (pr.reviewRequested)
+        return { kind: "rereview", because: { how: "re-requested", at: pr.updatedAt } };
+    if (pr.authorSince)
+        return { kind: "rereview", because: pr.authorSince };
+    return { kind: "waiting", on: "author" };
+}
+export const itemKey = (pr) => (pr.stack ? `${pr.repo}@${pr.stack.number}` : `${pr.repo}#${pr.number}`);
+/**
+ * Group PRs into items. In a stack only the lowest layer can merge, so an
+ * approved layer above an open one waits on it; the stack's move is the move
+ * of its lowest layer that needs something from you.
+ */
+export function toItems(prs) {
+    const groups = Map.groupBy(dedupe(prs), itemKey);
+    return [...groups.entries()].map(([key, group]) => {
+        const layers = [...group].sort((a, b) => (a.stack?.position ?? 0) - (b.stack?.position ?? 0));
+        const moves = layers.map((pr, i) => {
+            const move = moveFor(pr);
+            if (move.kind === "merge" && i > 0)
+                return { kind: "waiting", on: "lower-layer" };
+            return move;
+        });
+        const actionable = moves.findIndex((m) => m.kind !== "waiting");
+        const at = actionable === -1 ? 0 : actionable;
+        const first = layers[0];
+        return {
+            key,
+            repo: first.repo,
+            prs: layers,
+            lead: layers[at],
+            move: moves[at],
+            stack: first.stack ? { number: first.stack.number, size: first.stack.size } : null,
+        };
+    });
+}
+/**
+ * The same PR can come back from several searches (requested, and reviewed
+ * before). Keep one: a pending request wins.
+ */
+function dedupe(prs) {
+    const byKey = new Map();
+    for (const pr of prs) {
+        const key = `${pr.repo}#${pr.number}`;
+        const seen = byKey.get(key);
+        byKey.set(key, seen
+            ? { ...seen, reviewRequested: seen.reviewRequested || pr.reviewRequested, myReviewAt: seen.myReviewAt ?? pr.myReviewAt, authorSince: seen.authorSince ?? pr.authorSince }
+            : pr);
+    }
+    return [...byKey.values()];
+}
+export const Quadrant = z.enum(["do", "next", "delegate", "someday"]);
+/** Touched in the last three days: what you're in the middle of. */
+const FOCUS_WINDOW_MS = 3 * 24 * 3600_000;
+/** No activity from anyone for two weeks: it has gone stale, whatever its state says, and needs a decision rather than a slot. */
+const QUIET_AFTER_MS = 14 * 24 * 3600_000;
+const latestTouch = (item) => item.prs.map((p) => p.touched).filter((t) => t !== null).sort((a, b) => b.at.localeCompare(a.at))[0] ?? null;
+const lastActivity = (item) => [...item.prs.map((p) => p.updatedAt), latestTouch(item)?.at ?? ""].sort().at(-1);
+/**
+ * Downstream's read of one item. Urgent: a person is blocked on you (their
+ * review, feedback on your PR) or it's done and only needs merging. Important:
+ * you're working on it or near it (touched lately, or you touched another PR by
+ * the same author), or it's yours. A PR handed back after your review is both.
+ * Drafts you haven't opened lately say "someday". Stale PRs never reach here.
+ */
+export function triage(item, context) {
+    const now = context.now.getTime();
+    const pr = item.lead;
+    // Before focus: "you reviewed 1h ago" would hide that the author answered since.
+    if (item.move.kind === "rereview")
+        return { quadrant: "do", why: { kind: "your-turn", who: pr.authorName ?? pr.author, ...item.move.because } };
+    const touch = latestTouch(item);
+    const inFocus = touch !== null && now - Date.parse(touch.at) <= FOCUS_WINDOW_MS;
+    if (inFocus)
+        return { quadrant: "do", why: { kind: "in-focus", at: touch.at, how: touch.how } };
+    if (pr.isDraft)
+        return { quadrant: "someday", why: { kind: "draft" } };
+    const yours = pr.role === "author";
+    if (yours && item.move.kind === "merge")
+        return { quadrant: "do", why: { kind: "ready-to-merge" } };
+    if (yours && item.move.kind === "address-feedback")
+        return { quadrant: "do", why: { kind: "feedback-on-yours" } };
+    if (yours)
+        return { quadrant: "next", why: { kind: "yours" } };
+    if (pr.authorKind === "bot")
+        return { quadrant: "next", why: { kind: "bot-work", who: pr.author } };
+    const waiting = { kind: "person-waiting", who: pr.authorName ?? pr.author, since: pr.updatedAt };
+    return { quadrant: context.focusAuthors.has(pr.author) ? "do" : "delegate", why: waiting };
+}
+const UNTIL_IT_CHANGES = new Set(["someday", "hidden"]);
+/**
+ * Read every item, apply your choices over the reads, and order each quadrant.
+ * `touches` names who you've been working with: the authors of PRs you touched
+ * lately, including ones already merged.
+ */
+export function arrange(items, choices, now, touches) {
+    const standing = (item) => {
+        const chosen = choices[item.key];
+        const woke = chosen !== undefined && UNTIL_IT_CHANGES.has(chosen.quadrant) && lastActivity(item) > chosen.at;
+        return chosen && !woke ? chosen.quadrant : null;
+    };
+    const shown = items.filter((i) => standing(i) !== "hidden");
+    const isStale = (i) => now.getTime() - Date.parse(lastActivity(i)) > QUIET_AFTER_MS;
+    const stale = shown.filter(isStale).sort((a, b) => lastActivity(a).localeCompare(lastActivity(b)));
+    const fresh = shown.filter((i) => !isStale(i));
+    const actionable = fresh.filter((i) => i.move.kind !== "waiting");
+    const recent = touches.filter((t) => now.getTime() - Date.parse(t.at) <= FOCUS_WINDOW_MS);
+    const focusAuthors = new Set(recent.map((t) => t.author).filter((a) => a !== null));
+    const triaged = actionable.map((item) => {
+        const auto = triage(item, { now, focusAuthors });
+        const chosen = standing(item);
+        return chosen && chosen !== "hidden" && chosen !== auto.quadrant ? { ...item, quadrant: chosen, why: { kind: "you-chose" }, auto } : { ...item, ...auto, auto };
+    });
+    const of = (q) => triaged.filter((t) => t.quadrant === q).sort(ORDER[q]);
+    const inbox = { do: of("do"), next: of("next"), delegate: of("delegate"), someday: of("someday") };
+    return {
+        top: inbox.do[0] ?? inbox.next[0] ?? inbox.delegate[0] ?? null,
+        ...inbox,
+        waiting: fresh.filter((i) => i.move.kind === "waiting").sort((a, b) => b.lead.updatedAt.localeCompare(a.lead.updatedAt)),
+        stale,
+    };
+}
+/** When the person on the other side last handed it to you. */
+const waitedLongest = (t) => (t.why.kind === "your-turn" ? t.why.at : t.lead.updatedAt);
+const oldestFirst = (a, b) => a.lead.updatedAt.localeCompare(b.lead.updatedAt);
+const newestFirst = (a, b) => b.lead.updatedAt.localeCompare(a.lead.updatedAt);
+const byMove = (a, b) => MOVES[a.move.kind].rank - MOVES[b.move.kind].rank;
+/** Do: people blocked on you first, longest wait first (they can't move without you); then what you're in the middle of, latest first. */
+const DO_ORDER = { "your-turn": 0, "person-waiting": 0, "feedback-on-yours": 1, "ready-to-merge": 2, "you-chose": 3, "in-focus": 4, yours: 5, "bot-work": 5, draft: 6 };
+const ORDER = {
+    do: (a, b) => DO_ORDER[a.why.kind] - DO_ORDER[b.why.kind] || (a.why.kind === "in-focus" && b.why.kind === "in-focus" ? b.why.at.localeCompare(a.why.at) : waitedLongest(a).localeCompare(waitedLongest(b))),
+    next: (a, b) => byMove(a, b) || newestFirst(a, b),
+    delegate: oldestFirst,
+    someday: newestFirst,
+};
+/** The choices a stale item offers, in the order they're shown. */
+export function staleChoices(item) {
+    const pr = item.lead;
+    const hide = { kind: "hide", nextMove: item.move.kind === "waiting" ? "theirs" : "yours" };
+    if (pr.role === "author")
+        return [{ kind: "comment", to: "reviewers" }, { kind: "close" }, hide, { kind: "ask-agent" }];
+    const request = pr.reviewRequested ? [{ kind: "remove-request" }] : [];
+    return [...request, { kind: "comment", to: "author" }, hide, { kind: "ask-agent" }];
+}

package/dist/domain/model.js

@@ -0,0 +1,180 @@
+// The review model. Shared by the server, the CLI and the browser so the three
+// never disagree about what a symbol, a flow edge or a thread is.
+import { z } from "zod";
+export const Range = z.object({ start: z.number().int().min(1), end: z.number().int().min(1) });
+/** What happened to a symbol in this change. `context` = unchanged, shown so the flow reads end to end. */
+export const SymbolStatus = z.enum(["added", "modified", "removed", "context"]);
+export const SymbolKind = z.enum([
+    "function",
+    "method",
+    "class",
+    "interface",
+    "type",
+    "route",
+    "component",
+    "const",
+    "module",
+]);
+export const CodeSymbol = z.object({
+    /** Stable id: `<file>#<Container.name>`. */
+    id: z.string(),
+    name: z.string(),
+    container: z.string().nullable().default(null),
+    kind: SymbolKind,
+    file: z.string(),
+    /** Lines on the new side. Null for removed symbols. */
+    range: Range.nullable(),
+    oldFile: z.string().nullable().default(null),
+    oldRange: Range.nullable().default(null),
+    status: SymbolStatus,
+    signature: z.string().nullable().default(null),
+    exported: z.boolean().default(false),
+    /** A door into the change: nothing else in the change calls it. */
+    entry: z.boolean().default(false),
+    /** Lives in a test file: shown as "tested by", never a door. */
+    test: z.boolean().default(false),
+    /** The agent's one-line answer to "what is this for?". */
+    summary: z.string().nullable().default(null),
+    /** Changed lines inside the symbol, new side. */
+    changedLines: z.number().int().default(0),
+});
+export const EdgeKind = z.enum(["calls", "renders", "implements", "extends", "uses"]);
+/** Whether the relationship itself is new in this change. */
+export const EdgeChange = z.enum(["added", "removed", "same"]);
+export const Edge = z.object({
+    id: z.string(),
+    from: z.string(),
+    to: z.string(),
+    kind: EdgeKind,
+    change: EdgeChange.default("same"),
+    /** Call site line in `from`'s file (new side, or old side for removed edges). */
+    line: z.number().int().nullable().default(null),
+    label: z.string().nullable().default(null),
+});
+export const Step = z.object({
+    id: z.string(),
+    order: z.number().int(),
+    title: z.string(),
+    body: z.string().default(""),
+    symbolId: z.string().nullable().default(null),
+    lines: Range.nullable().default(null),
+});
+/**
+ * Everything said about the code is a thread.
+ * - why: rationale for something that looks odd
+ * - decision: a design choice with the alternatives that lost
+ * - finding: a problem the reviewer wants addressed
+ * - question: someone needs an answer from the other side
+ * - comment: anything else
+ */
+export const NoteKind = z.enum(["why", "decision", "finding", "question", "comment"]);
+/** Shown as must fix / should fix / nice to have. */
+export const Severity = z.enum(["blocker", "concern", "nit"]);
+export const severityLabel = { blocker: "must fix", concern: "should fix", nit: "nice to have" };
+/** What kind of problem a finding is, in the order a reviewer who gets paged cares about. */
+export const FindingCategory = z.enum(["bug", "risk", "scale", "test", "speed", "lean"]);
+/** The comment this thread becomes on the pull request, if it goes out at all. */
+export const Outgoing = z.object({ include: z.boolean(), body: z.string() });
+export const NoteStatus = z.enum(["open", "resolved", "dismissed"]);
+export const Author = z.enum(["agent", "user"]);
+export const Alternative = z.object({ option: z.string(), tradeoff: z.string() });
+export const Suggestion = z.object({ code: z.string(), lines: Range });
+export const Reply = z.object({
+    id: z.string(),
+    noteId: z.string(),
+    author: Author,
+    body: z.string(),
+    createdAt: z.string(),
+});
+export const Note = z.object({
+    id: z.string(),
+    /** Short handle for conversation: "fix 2 and 5". */
+    number: z.number().int().default(0),
+    kind: NoteKind,
+    severity: Severity.nullable().default(null),
+    category: FindingCategory.nullable().default(null),
+    title: z.string(),
+    /** For findings: the problem, with the concrete case that goes wrong. */
+    body: z.string().default(""),
+    /** For findings: the smallest fix. */
+    fix: z.string().default(""),
+    /** For findings: what happens if we ship it anyway. */
+    impact: z.string().default(""),
+    outgoing: Outgoing.nullable().default(null),
+    symbolId: z.string().nullable().default(null),
+    file: z.string().nullable().default(null),
+    lines: Range.nullable().default(null),
+    side: z.enum(["new", "old"]).default("new"),
+    alternatives: z.array(Alternative).default([]),
+    suggestion: Suggestion.nullable().default(null),
+    status: NoteStatus.default("open"),
+    author: Author,
+    createdAt: z.string(),
+    replies: z.array(Reply).default([]),
+});
+export const FileChange = z.object({
+    path: z.string(),
+    oldPath: z.string().nullable(),
+    status: z.enum(["added", "modified", "deleted", "renamed", "context"]),
+    additions: z.number().int(),
+    deletions: z.number().int(),
+});
+export const Verdict = z.object({
+    by: Author,
+    value: z.enum(["approve", "changes", "comment"]),
+    body: z.string().default(""),
+    at: z.string(),
+});
+export const Review = z.object({
+    id: z.string(),
+    title: z.string(),
+    mode: z.enum(["diff", "teach"]),
+    /** What the user asked to compare against (a branch name, a PR base). */
+    base: z.string().nullable(),
+    /** The merge base actually diffed against. */
+    baseSha: z.string().nullable().default(null),
+    /** A ref, or WORKTREE for uncommitted work. */
+    head: z.string(),
+    /** Teach mode: the paths being explained. */
+    paths: z.array(z.string()).default([]),
+    pr: z.number().int().nullable().default(null),
+    /** `owner/name` on GitHub, when the repo has a GitHub origin. */
+    repo: z.string().nullable().default(null),
+    /** The GitHub account this review reads and sends as. */
+    account: z.string().nullable().default(null),
+    summary: z.string().default(""),
+    status: z.enum(["drafting", "ready", "done"]),
+    createdAt: z.string(),
+    verdicts: z.array(Verdict).default([]),
+    /** The body of the review that goes to the pull request; the agent drafts it, the user edits it. */
+    outgoingBody: z.string().default(""),
+    published: z.object({ url: z.string(), at: z.string(), event: z.string(), comments: z.number().int() }).nullable().default(null),
+});
+// ---------------------------------------------------------------------------
+// Application state: the UI tells the agent what the user sees; the agent can
+// move the user's view. Same idea as agent-native's navigation/selection keys.
+// ---------------------------------------------------------------------------
+export const Navigation = z.object({
+    view: z.enum(["overview", "trail", "map"]),
+    trail: z.array(z.string()).default([]),
+    stepId: z.string().nullable().default(null),
+    noteId: z.string().nullable().default(null),
+});
+export const Selection = z.object({
+    symbolId: z.string().nullable(),
+    file: z.string(),
+    lines: Range,
+    side: z.enum(["new", "old"]).default("new"),
+});
+export const NavigateCommand = z.object({
+    symbolId: z.string().nullable().default(null),
+    stepId: z.string().nullable().default(null),
+    noteId: z.string().nullable().default(null),
+    view: z.enum(["overview", "trail", "map"]).nullable().default(null),
+    lines: Range.nullable().default(null),
+    nonce: z.string().optional(),
+});
+/** The pull request on GitHub, when the review is of one. */
+export const prUrl = (review) => (review.repo && review.pr ? `https://github.com/${review.repo}/pull/${review.pr}` : null);
+/** The status `review.publish` answers with when the PR changed since the review was opened. */
+export const HEAD_MOVED = 409;