@armanckeser/downstream 0.0.0-stage → 0.1.0

package/dist/domain/next-move.js

@@ -0,0 +1,34 @@
+/** The agent spoke last in an open thread that asks something of you. */
+export function awaitsYou(n) {
+    if (n.status !== "open")
+        return false;
+    const last = n.replies.at(-1)?.author ?? n.author;
+    return last === "agent" && (n.kind === "question" || n.replies.length > 0);
+}
+/** An open thread the agent raised that nobody answered yet: yours to settle. */
+export function awaitsDecision(n) {
+    return n.status === "open" && n.author === "agent" && n.replies.length === 0;
+}
+const first = (notes) => [...notes].sort((a, b) => a.number - b.number)[0];
+/**
+ * Order matters: someone blocked on you comes before reading on, and reading
+ * comes before settling what's left open, which comes before sending. `visited` holds the steps you've opened.
+ */
+export function nextMove(state, visited) {
+    const { review, steps, notes } = state;
+    if (review.published)
+        return { kind: "sent", url: review.published.url };
+    const blocked = first(notes.filter(awaitsYou));
+    if (blocked)
+        return { kind: "answer", noteId: blocked.id, number: blocked.number };
+    const nothingWritten = !review.summary && steps.length === 0 && notes.length === 0;
+    if (nothingWritten && review.status === "drafting")
+        return { kind: "reading" };
+    const unseen = steps.find((s) => !visited.has(s.id));
+    if (unseen)
+        return { kind: "walk", stepId: unseen.id, order: unseen.order, total: steps.length };
+    const open = first(notes.filter(awaitsDecision));
+    if (open)
+        return { kind: "decide", noteId: open.id, number: open.number };
+    return review.mode === "teach" ? { kind: "finish" } : { kind: "send" };
+}

package/dist/domain/pr-detail.js

@@ -0,0 +1,45 @@
+// What the preview shows before you decide to start: what the PR says it does,
+// how big it is, and where its checks and reviews stand.
+const GENERATED = [
+    /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|uv\.lock|poetry\.lock|Pipfile\.lock|pdm\.lock|Cargo\.lock|go\.sum|Gemfile\.lock|composer\.lock|flake\.lock|mix\.lock|pubspec\.lock|Podfile\.lock|packages\.lock\.json)$/,
+    /\.(min\.(js|css)|map|snap)$/,
+    /(^|\/)(__snapshots__|dist|build|vendor|node_modules|\.yarn)\//,
+    /(_pb2(_grpc)?\.pyi?|\.pb\.go|\.pb\.(cc|h)|\.g\.dart|\.generated\.[a-z]+)$/,
+];
+const TEST = [
+    /(^|\/)(tests?|__tests__|spec|testdata|fixtures|__fixtures__|__mocks__)\//,
+    /\.(test|spec)\.[cm]?[jt]sx?$/,
+    /(^|\/)(test_[^/]+|[^/]+_test)\.py$/,
+    /(^|\/)conftest\.py$/,
+    /_test\.go$/,
+    /Tests?\.(cs|java|kt|swift)$/,
+];
+const DOCS = [/\.(md|mdx|rst|txt|adoc)$/i, /(^|\/)docs?\//, /(^|\/)(LICENSE|CHANGELOG|AUTHORS)[^/]*$/i];
+export function fileRole(path) {
+    if (GENERATED.some((r) => r.test(path)))
+        return "generated";
+    if (TEST.some((r) => r.test(path)))
+        return "test";
+    if (DOCS.some((r) => r.test(path)))
+        return "docs";
+    return "code";
+}
+export function reviewable(files) {
+    const others = { test: 0, docs: 0, generated: 0 };
+    const code = [];
+    let additions = 0;
+    let deletions = 0;
+    for (const f of files) {
+        const role = fileRole(f.path);
+        if (role !== "generated") {
+            additions += f.additions;
+            deletions += f.deletions;
+        }
+        if (role === "code")
+            code.push(f);
+        else
+            others[role]++;
+    }
+    code.sort((a, b) => b.additions + b.deletions - (a.additions + a.deletions));
+    return { code, others, additions, deletions };
+}

package/dist/server/actions.js

@@ -0,0 +1,564 @@
+// Every way to change a review is an action defined once here. The browser,
+// the agent's CLI and plain HTTP all call the same code, so the user can do
+// anything the agent can and the other way round.
+import { z } from "zod";
+import { Alternative, Author, CodeSymbol, EdgeKind, NavigateCommand, Navigation, Note, NoteKind, NoteStatus, Range, Selection, Severity, Step, Suggestion, SymbolKind, FindingCategory, Outgoing, SymbolStatus, } from "../domain/model.js";
+import { newId, now } from "./store.js";
+import { resolveTarget, Workspace } from "./workspace.js";
+import { tryGit } from "./analyze/git.js";
+import { isTestFile } from "./analyze/graph.js";
+import { draft, HeadMoved, publish } from "./publish.js";
+import { HEAD_MOVED } from "../domain/model.js";
+export const actions = new Map();
+function defineAction(def) {
+    actions.set(def.name, def);
+    return def;
+}
+export class ActionError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+    }
+}
+function requireSymbol(ctx, id) {
+    const s = ctx.store.symbol(ctx.reviewId, id);
+    if (s)
+        return s;
+    // Be forgiving with ids: accept a bare name if it is unique.
+    const byName = ctx.store.symbols(ctx.reviewId).filter((x) => x.name === id || `${x.container}.${x.name}` === id || x.id.endsWith(`#${id}`));
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1)
+        throw new ActionError(`"${id}" is ambiguous: ${byName.map((x) => x.id).join(", ")}`);
+    throw new ActionError(`No symbol "${id}". Run \`downstream show\` for ids.`, 404);
+}
+/** Threads are addressed by id or by their number ("3", "#3"), the way people talk about them. */
+function requireNote(ctx, id) {
+    const byNumber = id.match(/^#?(\d+)$/);
+    const n = byNumber ? (ctx.store.notes(ctx.reviewId).find((x) => x.number === Number(byNumber[1])) ?? null) : ctx.store.note(ctx.reviewId, id);
+    if (!n)
+        throw new ActionError(`No thread "${id}".`, 404);
+    return n;
+}
+// --- review lifecycle ----------------------------------------------------------
+export const openReview = defineAction({
+    name: "review.open",
+    description: "Analyze a change (or a set of paths, in teach mode) and open it as the current review.",
+    input: z.object({
+        mode: z.enum(["diff", "teach"]).default("diff"),
+        base: z.string().optional(),
+        head: z.string().optional(),
+        pr: z.number().int().optional(),
+        paths: z.array(z.string()).default([]),
+        title: z.string().optional(),
+    }),
+    run(ctx, input) {
+        const id = newId("rv");
+        let review;
+        if (input.mode === "teach") {
+            review = {
+                id,
+                title: input.title ?? `Tour of ${input.paths.join(", ") || "the repository"}`,
+                mode: "teach",
+                base: null,
+                baseSha: null,
+                head: "WORKTREE",
+                paths: input.paths,
+                pr: null,
+                repo: ctx.nameWithOwner,
+                account: null,
+                summary: "",
+                status: "drafting",
+                createdAt: now(),
+                verdicts: [],
+                outgoingBody: "",
+                published: null,
+            };
+        }
+        else {
+            const account = input.pr ? ctx.accountFor(input.pr) : null;
+            const t = resolveTarget(ctx.root, { ...input, repo: ctx.nameWithOwner, account });
+            review = {
+                id,
+                title: input.title ?? t.title ?? defaultTitle(ctx.root, t.head, t.base, input.pr),
+                mode: "diff",
+                base: t.base,
+                baseSha: t.baseSha,
+                head: t.head,
+                paths: [],
+                pr: input.pr ?? null,
+                repo: ctx.nameWithOwner,
+                account,
+                summary: "",
+                status: "drafting",
+                createdAt: now(),
+                verdicts: [],
+                outgoingBody: "",
+                published: null,
+            };
+        }
+        ctx.store.saveReview(review, ctx.root);
+        const { files, graph } = ctx.workspace(id).analyze();
+        ctx.store.replaceAnalysis(id, files, graph.symbols, graph.edges);
+        ctx.store.setCurrent(id);
+        ctx.store.emit(id, "review.opened", ctx.actor, { id });
+        return { review, files: files.length, symbols: graph.symbols.length, edges: graph.edges.length };
+    },
+});
+defineAction({
+    name: "review.reanalyze",
+    description: "Re-read the code after it changed (e.g. a finding was fixed). Keeps summaries, threads and the walkthrough.",
+    input: z.object({}),
+    run(ctx) {
+        ctx.dropWorkspace(ctx.reviewId);
+        const { files, graph } = ctx.workspace(ctx.reviewId).analyze();
+        ctx.store.replaceAnalysis(ctx.reviewId, files, graph.symbols, graph.edges);
+        ctx.store.emit(ctx.reviewId, "review.reanalyzed", ctx.actor, { symbols: graph.symbols.length });
+        return { symbols: graph.symbols.length, edges: graph.edges.length };
+    },
+});
+defineAction({
+    name: "review.update",
+    description: "Set the title, the summary (markdown), or the status (drafting → ready when the walkthrough is written).",
+    input: z.object({
+        title: z.string().optional(),
+        summary: z.string().optional(),
+        status: z.enum(["drafting", "ready", "done"]).optional(),
+        /** The review body that goes to the pull request (markdown). */
+        outgoingBody: z.string().optional(),
+    }),
+    run(ctx, input) {
+        const review = ctx.store.review(ctx.reviewId);
+        const next = { ...review, ...Object.fromEntries(Object.entries(input).filter(([, v]) => v !== undefined)) };
+        ctx.store.saveReview(next);
+        ctx.store.emit(ctx.reviewId, "review.updated", ctx.actor, input);
+        return next;
+    },
+});
+defineAction({
+    name: "review.verdict",
+    description: "Record a verdict: approve, changes (request changes), or comment.",
+    input: z.object({ value: z.enum(["approve", "changes", "comment"]), body: z.string().default("") }),
+    run(ctx, input) {
+        const review = ctx.store.review(ctx.reviewId);
+        const verdict = { by: ctx.actor, value: input.value, body: input.body, at: now() };
+        const verdicts = [...review.verdicts.filter((v) => v.by !== ctx.actor), verdict];
+        ctx.store.saveReview({ ...review, verdicts });
+        ctx.store.emit(ctx.reviewId, "review.verdict", ctx.actor, verdict);
+        return verdict;
+    },
+});
+defineAction({
+    name: "review.done",
+    description: "End the session. A waiting agent is released with a `review.done` event.",
+    input: z.object({}),
+    run(ctx) {
+        const review = ctx.store.review(ctx.reviewId);
+        ctx.store.saveReview({ ...review, status: "done" });
+        ctx.store.emit(ctx.reviewId, "review.done", ctx.actor, {});
+        return { ok: true };
+    },
+});
+// --- the map --------------------------------------------------------------------
+const SymbolPatch = z.object({ id: z.string(), summary: z.string().nullable().optional(), entry: z.boolean().optional() });
+defineAction({
+    name: "symbol.annotate",
+    description: "Give a symbol a one-line purpose, or mark/unmark it as an entry point.",
+    input: SymbolPatch,
+    run(ctx, input) {
+        const s = requireSymbol(ctx, input.id);
+        const next = { ...s, summary: input.summary !== undefined ? input.summary : s.summary, entry: input.entry ?? s.entry };
+        ctx.store.putSymbol(ctx.reviewId, next);
+        ctx.store.emit(ctx.reviewId, "symbol.annotated", ctx.actor, { id: s.id, entry: input.entry ?? null });
+        return next;
+    },
+});
+const NewSymbol = z.object({
+    file: z.string(),
+    name: z.string(),
+    lines: Range.optional(),
+    /** Alternatively point at one line and let the analyzer find the enclosing declaration (TS/JS). */
+    line: z.number().int().optional(),
+    kind: SymbolKind.default("function"),
+    status: SymbolStatus.default("context"),
+    summary: z.string().nullable().default(null),
+    entry: z.boolean().default(false),
+    signature: z.string().nullable().default(null),
+});
+defineAction({
+    name: "symbol.add",
+    description: "Put a symbol on the map by hand (other languages, or code the analyzer missed).",
+    input: NewSymbol,
+    run(ctx, input) {
+        let s = null;
+        if (!input.lines && input.line)
+            s = ctx.workspace(ctx.reviewId).symbolAt(input.file, input.line);
+        if (!s) {
+            if (!input.lines)
+                throw new ActionError("Give `lines: {start, end}` (or `line` inside a TS/JS declaration).");
+            s = {
+                id: `${input.file}#${input.name}`,
+                name: input.name,
+                container: null,
+                kind: input.kind,
+                file: input.file,
+                range: input.lines,
+                oldFile: null,
+                oldRange: null,
+                status: input.status,
+                signature: input.signature,
+                exported: false,
+                entry: input.entry,
+                summary: input.summary,
+                changedLines: 0,
+                test: isTestFile(input.file),
+            };
+        }
+        else {
+            s = { ...s, summary: input.summary, entry: input.entry, status: input.status };
+        }
+        ctx.store.putSymbol(ctx.reviewId, s, true);
+        ctx.store.emit(ctx.reviewId, "symbol.added", ctx.actor, { id: s.id });
+        return s;
+    },
+});
+defineAction({
+    name: "symbol.remove",
+    description: "Take a symbol (and its edges) off the map.",
+    input: z.object({ id: z.string() }),
+    run(ctx, input) {
+        const s = requireSymbol(ctx, input.id);
+        ctx.store.deleteSymbol(ctx.reviewId, s.id);
+        ctx.store.emit(ctx.reviewId, "symbol.removed", ctx.actor, { id: s.id });
+        return { ok: true };
+    },
+});
+const NewEdge = z.object({ from: z.string(), to: z.string(), kind: EdgeKind.default("calls"), label: z.string().nullable().default(null), change: z.enum(["added", "removed", "same"]).default("same") });
+defineAction({
+    name: "edge.add",
+    description: "Draw a relationship the analyzer can't see (events, queues, HTTP between services, dynamic dispatch). Label it.",
+    input: NewEdge,
+    run(ctx, input) {
+        const from = requireSymbol(ctx, input.from);
+        const to = requireSymbol(ctx, input.to);
+        const edge = { id: `${from.id}->${to.id}:${input.kind}`, from: from.id, to: to.id, kind: input.kind, change: input.change, line: null, label: input.label };
+        ctx.store.putEdge(ctx.reviewId, edge, true);
+        ctx.store.emit(ctx.reviewId, "edge.added", ctx.actor, { id: edge.id });
+        return edge;
+    },
+});
+defineAction({
+    name: "edge.remove",
+    description: "Remove a relationship that is noise.",
+    input: z.object({ id: z.string() }),
+    run(ctx, input) {
+        ctx.store.deleteEdge(ctx.reviewId, input.id);
+        ctx.store.emit(ctx.reviewId, "edge.removed", ctx.actor, input);
+        return { ok: true };
+    },
+});
+// --- walkthrough ---------------------------------------------------------------------
+const StepInput = z.object({ title: z.string(), body: z.string().default(""), symbolId: z.string().nullable().default(null), lines: Range.nullable().default(null) });
+function toSteps(ctx, steps) {
+    return steps.map((s, i) => ({
+        id: newId("st"),
+        order: i + 1,
+        title: s.title,
+        body: s.body,
+        symbolId: s.symbolId ? requireSymbol(ctx, s.symbolId).id : null,
+        lines: s.lines,
+    }));
+}
+defineAction({
+    name: "steps.set",
+    description: "Replace the walkthrough: an ordered path through the change, entry point first, each step anchored to a symbol.",
+    input: z.object({ steps: z.array(StepInput) }),
+    run(ctx, input) {
+        const steps = toSteps(ctx, input.steps);
+        ctx.store.replaceSteps(ctx.reviewId, steps);
+        ctx.store.emit(ctx.reviewId, "steps.set", ctx.actor, { count: steps.length });
+        return steps;
+    },
+});
+// --- threads ------------------------------------------------------------------------------
+const NoteInput = z.object({
+    kind: NoteKind,
+    title: z.string(),
+    body: z.string().default(""),
+    severity: Severity.nullable().default(null),
+    category: FindingCategory.nullable().default(null),
+    fix: z.string().default(""),
+    impact: z.string().default(""),
+    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),
+    outgoing: Outgoing.nullable().default(null),
+});
+function makeNote(ctx, input) {
+    const symbol = input.symbolId ? requireSymbol(ctx, input.symbolId) : null;
+    if (input.kind === "finding" && !input.severity)
+        input.severity = "concern";
+    return {
+        id: newId("n"),
+        number: ctx.store.nextNoteNumber(ctx.reviewId),
+        kind: input.kind,
+        severity: input.kind === "finding" ? input.severity : null,
+        category: input.kind === "finding" ? input.category : null,
+        title: input.title,
+        body: input.body,
+        fix: input.fix,
+        impact: input.impact,
+        outgoing: input.outgoing,
+        symbolId: symbol?.id ?? null,
+        file: input.file ?? symbol?.file ?? null,
+        lines: input.lines,
+        side: input.side,
+        alternatives: input.alternatives,
+        suggestion: input.suggestion,
+        status: "open",
+        author: ctx.actor,
+        createdAt: now(),
+        replies: [],
+    };
+}
+defineAction({
+    name: "note.add",
+    description: "Say something about the code. kind: why (rationale), decision (with alternatives that lost), finding (problem; severity blocker|concern|nit), question, comment. Anchor with symbolId and optional lines.",
+    input: NoteInput,
+    run(ctx, input) {
+        const note = makeNote(ctx, input);
+        ctx.store.putNote(ctx.reviewId, note);
+        ctx.store.emit(ctx.reviewId, "note.added", ctx.actor, { id: note.id, kind: note.kind, title: note.title, symbolId: note.symbolId });
+        return note;
+    },
+});
+defineAction({
+    name: "note.reply",
+    description: "Reply in a thread.",
+    input: z.object({ noteId: z.string(), body: z.string().min(1) }),
+    run(ctx, input) {
+        const note = requireNote(ctx, input.noteId);
+        const reply = { id: newId("r"), noteId: note.id, author: ctx.actor, body: input.body, createdAt: now() };
+        ctx.store.addReply(ctx.reviewId, reply);
+        ctx.store.emit(ctx.reviewId, "note.replied", ctx.actor, { noteId: note.id, title: note.title, body: input.body, replyId: reply.id });
+        return reply;
+    },
+});
+defineAction({
+    name: "note.status",
+    description: "Resolve, dismiss, or reopen a thread.",
+    input: z.object({ noteId: z.string(), status: NoteStatus, reason: z.string().optional() }),
+    run(ctx, input) {
+        const note = requireNote(ctx, input.noteId);
+        ctx.store.putNote(ctx.reviewId, { ...note, status: input.status });
+        if (input.reason) {
+            ctx.store.addReply(ctx.reviewId, { id: newId("r"), noteId: note.id, author: ctx.actor, body: input.reason, createdAt: now() });
+        }
+        ctx.store.emit(ctx.reviewId, "note.status", ctx.actor, { noteId: note.id, title: note.title, status: input.status, reason: input.reason ?? null });
+        return { ok: true };
+    },
+});
+defineAction({
+    name: "ask",
+    description: "Ask the other side a question about a symbol or a line range. Opens a question thread.",
+    input: z.object({ body: z.string().min(1), symbolId: z.string().nullable().default(null), file: z.string().nullable().default(null), lines: Range.nullable().default(null), side: z.enum(["new", "old"]).default("new") }),
+    run(ctx, input) {
+        const title = input.body.split("\n")[0].slice(0, 120);
+        const note = makeNote(ctx, NoteInput.parse({ kind: "question", title, body: input.body.length > title.length ? input.body : "", symbolId: input.symbolId, file: input.file, lines: input.lines, side: input.side }));
+        ctx.store.putNote(ctx.reviewId, note);
+        ctx.store.emit(ctx.reviewId, "ask", ctx.actor, { id: note.id, body: input.body, symbolId: note.symbolId, file: note.file, lines: note.lines });
+        return note;
+    },
+});
+// --- batch authoring -------------------------------------------------------------------------
+defineAction({
+    name: "apply",
+    description: "Author the whole walkthrough in one call: summary, symbol purposes and entry flags, extra symbols and edges, steps, notes.",
+    input: z.object({
+        title: z.string().optional(),
+        summary: z.string().optional(),
+        status: z.enum(["drafting", "ready"]).optional(),
+        symbols: z.array(SymbolPatch).default([]),
+        addSymbols: z.array(NewSymbol).default([]),
+        edges: z.array(NewEdge).default([]),
+        removeEdges: z.array(z.string()).default([]),
+        steps: z.array(StepInput).optional(),
+        notes: z.array(NoteInput).default([]),
+        /** Edits to existing threads by id or number, e.g. drafting their outgoing comments. */
+        updates: z.array(z.object({ noteId: z.string() }).passthrough()).default([]),
+        /** The review body for the pull request. */
+        outgoingBody: z.string().optional(),
+    }),
+    async run(ctx, input) {
+        // Validate every part before writing any, so a bad update can't leave the notes
+        // above it applied and a retry duplicating them.
+        const planned = [];
+        const plan = (name, payload) => {
+            const parsed = actions.get(name).input.safeParse(payload);
+            if (!parsed.success)
+                throw new ActionError(`Nothing applied. ${name} is invalid:\n${z.prettifyError(parsed.error)}`);
+            planned.push({ name, payload: parsed.data });
+        };
+        const results = [];
+        if (input.title || input.summary || input.status || input.outgoingBody !== undefined) {
+            plan("review.update", { title: input.title, summary: input.summary, status: input.status, outgoingBody: input.outgoingBody });
+            results.push("review updated");
+        }
+        for (const s of input.addSymbols)
+            plan("symbol.add", s);
+        if (input.addSymbols.length)
+            results.push(`${input.addSymbols.length} symbols added`);
+        for (const s of input.symbols)
+            plan("symbol.annotate", s);
+        if (input.symbols.length)
+            results.push(`${input.symbols.length} symbols annotated`);
+        for (const e of input.edges)
+            plan("edge.add", e);
+        for (const id of input.removeEdges)
+            plan("edge.remove", { id });
+        if (input.steps) {
+            plan("steps.set", { steps: input.steps });
+            results.push(`${input.steps.length} steps`);
+        }
+        for (const n of input.notes)
+            plan("note.add", n);
+        if (input.notes.length)
+            results.push(`${input.notes.length} notes`);
+        for (const u of input.updates) {
+            requireNote(ctx, u.noteId);
+            plan("note.update", u);
+        }
+        if (input.updates.length)
+            results.push(`${input.updates.length} threads updated`);
+        for (const { name, payload } of planned)
+            await actions.get(name).run(ctx, payload);
+        return { ok: true, applied: results };
+    },
+});
+// --- shared application state ----------------------------------------------------------------
+defineAction({
+    name: "state.set",
+    description: "The UI reports what the user is looking at (navigation), what they selected (selection), and which steps they've opened (visited).",
+    input: z.discriminatedUnion("key", [
+        z.object({ key: z.literal("navigation"), value: Navigation }),
+        z.object({ key: z.literal("selection"), value: Selection.nullable() }),
+        /** Walkthrough steps the user has opened, so the next move (here and on the home page) knows what's left. */
+        z.object({ key: z.literal("visited"), value: z.array(z.string()) }),
+    ]),
+    run(ctx, input) {
+        ctx.store.setAppState(ctx.reviewId, input.key, input.value);
+        return { ok: true };
+    },
+});
+defineAction({
+    name: "navigate",
+    description: "Move the user's view: open a symbol (optionally highlighting lines), a step, a thread, or switch view.",
+    input: NavigateCommand,
+    run(ctx, input) {
+        if (input.symbolId)
+            input.symbolId = requireSymbol(ctx, input.symbolId).id;
+        if (input.noteId)
+            input.noteId = requireNote(ctx, input.noteId).id;
+        const cmd = { ...input, nonce: newId("nav") };
+        ctx.store.emit(ctx.reviewId, "navigate", ctx.actor, cmd);
+        return cmd;
+    },
+});
+defineAction({
+    name: "screen",
+    readOnly: true,
+    description: "What the user is looking at right now: their view, the trail of open symbols, and their selected code.",
+    input: z.object({}),
+    run(ctx) {
+        const nav = ctx.store.getAppState(ctx.reviewId, "navigation");
+        const sel = ctx.store.getAppState(ctx.reviewId, "selection");
+        const ws = ctx.workspace(ctx.reviewId);
+        let selectedCode = null;
+        if (sel) {
+            const text = ws.read(sel.file, sel.side);
+            selectedCode = text?.split("\n").slice(sel.lines.start - 1, sel.lines.end).join("\n") ?? null;
+        }
+        const symbols = new Map(ctx.store.symbols(ctx.reviewId).map((s) => [s.id, s]));
+        return {
+            view: nav?.view ?? "overview",
+            trail: (nav?.trail ?? []).map((id) => {
+                const s = symbols.get(id);
+                return s ? { id, name: s.name, file: s.file, lines: s.range } : { id };
+            }),
+            step: nav?.stepId ? (ctx.store.steps(ctx.reviewId).find((s) => s.id === nav.stepId) ?? null) : null,
+            thread: nav?.noteId ? ctx.store.note(ctx.reviewId, nav.noteId) : null,
+            selection: sel ? { ...sel, code: selectedCode } : null,
+            presence: ctx.store.presence(),
+        };
+    },
+});
+function defaultTitle(root, head, base, pr) {
+    if (pr)
+        return `PR #${pr}`;
+    if (head !== "WORKTREE")
+        return tryGit(root, ["log", "-1", "--format=%s", head])?.trim() || `${head} against ${base}`;
+    const branch = tryGit(root, ["branch", "--show-current"])?.trim();
+    return branch && branch !== "main" && branch !== "master" ? `${branch}, uncommitted` : "Uncommitted work";
+}
+// --- what goes to the pull request ---------------------------------------------------------------
+defineAction({
+    name: "note.update",
+    description: "Edit a thread: its wording, severity, fix or impact, or its outgoing comment (`outgoing: {include, body}` decides whether and how it goes to the PR author).",
+    input: z.object({
+        noteId: z.string(),
+        title: z.string().optional(),
+        body: z.string().optional(),
+        fix: z.string().optional(),
+        impact: z.string().optional(),
+        severity: Severity.nullable().optional(),
+        category: FindingCategory.nullable().optional(),
+        outgoing: Outgoing.nullable().optional(),
+    }),
+    run(ctx, input) {
+        const note = requireNote(ctx, input.noteId);
+        const { noteId: _id, ...patch } = input;
+        const next = { ...note, ...Object.fromEntries(Object.entries(patch).filter(([, v]) => v !== undefined)) };
+        ctx.store.putNote(ctx.reviewId, next);
+        ctx.store.emit(ctx.reviewId, "note.updated", ctx.actor, { noteId: note.id, number: note.number, title: next.title, fields: Object.keys(patch).filter((k) => patch[k] !== undefined) });
+        return next;
+    },
+});
+defineAction({
+    name: "review.draft",
+    readOnly: true,
+    description: "The review as it would be sent: event, body, and each inline comment (or the ones that fall outside the diff and go into the body).",
+    input: z.object({ event: z.enum(["APPROVE", "REQUEST_CHANGES", "COMMENT"]).optional(), body: z.string().optional() }),
+    run(ctx, input) {
+        return draft(ctx.root, ctx.store.state(ctx.reviewId), input);
+    },
+});
+defineAction({
+    name: "review.publish",
+    description: "Send the review to the pull request on GitHub. Outward-facing and permanent: the agent only calls this when the user has explicitly said to send it. Refuses with 409 when the PR changed since the review was opened; `force` sends anyway, only when the user says so.",
+    input: z.object({ event: z.enum(["APPROVE", "REQUEST_CHANGES", "COMMENT"]).optional(), body: z.string().optional(), force: z.boolean().optional() }),
+    run(ctx, { force, ...input }) {
+        const state = ctx.store.state(ctx.reviewId);
+        const d = draft(ctx.root, state, input);
+        let sent;
+        try {
+            sent = publish(state, d, { force });
+        }
+        catch (e) {
+            if (e instanceof HeadMoved)
+                throw new ActionError(e.message, HEAD_MOVED);
+            const err = e;
+            const detail = err.stderr?.toString().trim() || err.message;
+            if (/own pull request/i.test(detail))
+                throw new ActionError("GitHub doesn't allow approving or requesting changes on your own pull request. Send it as Comment.", 422);
+            throw new ActionError(`GitHub refused the review: ${detail.split("\n").slice(0, 3).join(" ")}`, 502);
+        }
+        const published = { url: sent.url, at: now(), event: d.event, comments: sent.comments };
+        ctx.store.saveReview({ ...state.review, published, outgoingBody: d.body });
+        ctx.store.emit(ctx.reviewId, "review.published", ctx.actor, published);
+        return published;
+    },
+});