mergestorm-mcp 0.2.25 → 0.2.27

package/dist/lib/tools/credits.d.ts

@@ -0,0 +1,3 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare function credits(cfg?: Config): Promise<ToolPayload>;

package/dist/lib/tools/credits.js

@@ -0,0 +1,38 @@
+import { CommandError, getMe, loadConfig } from "mergestorm/client";
+function formatMinutes(value) {
+    return value.toLocaleString("en-US", { maximumFractionDigits: 1 });
+}
+function surgeSummary(surge) {
+    if (!surge)
+        return "";
+    const wallet = `wallet ${formatMinutes(surge.walletMinutes)} min`;
+    if (surge.includedMinutes <= 0)
+        return `\nSurge: ${wallet}`;
+    return (`\nSurge: ${formatMinutes(surge.usedMinutes)} of ${formatMinutes(surge.includedMinutes)} included min this period` +
+        ` · ${wallet}`);
+}
+export async function credits(cfg) {
+    const resolved = cfg ?? (await loadConfig());
+    const me = await getMe(resolved);
+    if (!me) {
+        throw new CommandError("Credits are not available right now (Mergestorm API is offline, unreachable, or too old).");
+    }
+    if (!me.usage) {
+        throw new CommandError("Credits are not available on this server yet. Update the API or use the dashboard.");
+    }
+    const standard = me.usage.standard;
+    const remaining = standard.remaining ??
+        (standard.limit != null ? Math.max(0, standard.limit - standard.used) : null);
+    const bonusRemaining = me.usage.bonus?.remaining;
+    const surge = me.usage.surge;
+    const bonusSummary = bonusRemaining == null ? "" : ` · ${bonusRemaining} bonus remaining`;
+    return {
+        summary: remaining == null
+            ? `${standard.used} used · unlimited${bonusSummary}${surgeSummary(surge)}`
+            : `${standard.used} used · ${remaining} remaining${bonusSummary}${surgeSummary(surge)}`,
+        data: {
+            usage: me.usage,
+            resets_at: me.resets_at ?? null,
+        },
+    };
+}

package/dist/lib/tools/cyclone-job.d.ts

@@ -0,0 +1,29 @@
+import type { Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare const CYCLONE_TASKS: readonly ["fix_findings", "fix_ci", "resolve_conflicts", "build"];
+export type CycloneTask = (typeof CYCLONE_TASKS)[number];
+export declare const CYCLONE_JOB_WAIT_DEFAULT_S = 45;
+export declare const CYCLONE_JOB_WAIT_MAX_S = 100;
+export declare const CYCLONE_JOB_POLL_MS = 5000;
+export declare const CYCLONE_JOB_TERMINAL_STATES: readonly ["pushed", "completed", "failed"];
+export declare const CYCLONE_START_WAIT_NOTE = "Wait for it now: call cyclone_job with this dispatch_id and timeout_s 45, again while it is queued or running, then tell the user what Cyclone pushed or why it failed.";
+export declare const CHAT_WAKE_CYCLONE_NOTE = "If your reply ends before Cyclone finishes, this chat is woken with the job's result.";
+export declare const CYCLONE_JOB_STILL_RUNNING_NOTE = "Cyclone is not done. Call cyclone_job again with this dispatch_id and timeout_s 45, and report the result once it is pushed, completed or failed.";
+export type CycloneStartInput = {
+    task: CycloneTask;
+    owner: string;
+    repo: string;
+    pr_number?: number;
+    failing_check?: string;
+    brief?: string;
+};
+export declare function cycloneStart(input: CycloneStartInput, cfg?: Config, chatId?: string | null): Promise<ToolPayload>;
+export declare function isCycloneJobTerminal(job: Record<string, unknown>): boolean;
+export declare function cycloneJobSummary(job: Record<string, unknown>): string;
+export type CycloneJobWaitDeps = {
+    pollMs?: number;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    signal?: AbortSignal;
+};
+export declare function cycloneJob(dispatchId: string, cfg?: Config, timeoutS?: number, deps?: CycloneJobWaitDeps): Promise<ToolPayload>;

package/dist/lib/tools/cyclone-job.js

@@ -0,0 +1,70 @@
+import { agentRequest } from "./agent-request.js";
+export const CYCLONE_TASKS = ["fix_findings", "fix_ci", "resolve_conflicts", "build"];
+export const CYCLONE_JOB_WAIT_DEFAULT_S = 45;
+export const CYCLONE_JOB_WAIT_MAX_S = 100;
+export const CYCLONE_JOB_POLL_MS = 5_000;
+export const CYCLONE_JOB_TERMINAL_STATES = ["pushed", "completed", "failed"];
+export const CYCLONE_START_WAIT_NOTE = `Wait for it now: call cyclone_job with this dispatch_id and timeout_s ${CYCLONE_JOB_WAIT_DEFAULT_S}, again while it is queued or running, then tell the user what Cyclone pushed or why it failed.`;
+export const CHAT_WAKE_CYCLONE_NOTE = "If your reply ends before Cyclone finishes, this chat is woken with the job's result.";
+export const CYCLONE_JOB_STILL_RUNNING_NOTE = `Cyclone is not done. Call cyclone_job again with this dispatch_id and timeout_s ${CYCLONE_JOB_WAIT_DEFAULT_S}, and report the result once it is pushed, completed or failed.`;
+export async function cycloneStart(input, cfg, chatId) {
+    const payload = await agentRequest("/api/v1/agents/cyclone/jobs", {
+        method: "POST",
+        json: {
+            task: input.task,
+            owner: input.owner,
+            repo: input.repo,
+            ...(input.pr_number !== undefined ? { pr_number: input.pr_number } : {}),
+            ...(input.failing_check ? { failing_check: input.failing_check } : {}),
+            ...(input.brief ? { brief: input.brief } : {}),
+            ...(chatId ? { chat_id: chatId } : {}),
+        },
+    }, cfg);
+    if (payload.isError || typeof payload.data.dispatch_id !== "string" || isCycloneJobTerminal(payload.data))
+        return payload;
+    return { ...payload, summary: [payload.summary, CYCLONE_START_WAIT_NOTE, ...(payload.data.chat_wake ? [CHAT_WAKE_CYCLONE_NOTE] : [])].join(" ") };
+}
+export function isCycloneJobTerminal(job) {
+    return CYCLONE_JOB_TERMINAL_STATES.includes(job.state);
+}
+export function cycloneJobSummary(job) {
+    const target = job.pr_number ? `${job.owner}/${job.repo}#${job.pr_number}` : `${job.owner}/${job.repo}`;
+    const parts = [`Cyclone ${job.task ?? "job"} on ${target}: ${job.state}`];
+    if (typeof job.outcome === "string" && job.outcome)
+        parts[0] += ` (${job.outcome})`;
+    if (typeof job.result_sha === "string" && job.result_sha)
+        parts.push(`pushed ${job.result_sha.slice(0, 10)}`);
+    if (typeof job.detail === "string" && job.detail)
+        parts.push(job.detail);
+    return parts.join(". ");
+}
+function sleepFor(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+export async function cycloneJob(dispatchId, cfg, timeoutS = 0, deps = {}) {
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? sleepFor;
+    const deadline = now() + Math.min(Math.max(timeoutS, 0), CYCLONE_JOB_WAIT_MAX_S) * 1000;
+    const route = `/api/v1/agents/cyclone/jobs/${encodeURIComponent(dispatchId)}`;
+    for (;;) {
+        const payload = await agentRequest(route, { method: "GET" }, cfg);
+        if (payload.isError)
+            return payload;
+        if (isCycloneJobTerminal(payload.data))
+            return { ...payload, summary: cycloneJobSummary(payload.data) };
+        const left = deadline - now();
+        if (left <= 0 || deps.signal?.aborted)
+            return { ...payload, summary: `${cycloneJobSummary(payload.data)}. ${CYCLONE_JOB_STILL_RUNNING_NOTE}` };
+        await sleep(Math.min(deps.pollMs ?? CYCLONE_JOB_POLL_MS, left), deps.signal);
+    }
+}

package/dist/lib/tools/envelope.d.ts

@@ -0,0 +1,5 @@
+import { type ReviewEnvelopeFallbacks, type ReviewJobRow } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare const MCP_REVIEW_STATUSES: readonly ["no_changes", "queued", "in_progress", "completed", "failed", "quota_exceeded", "rate_limited"];
+export declare function payloadFromRow(row: ReviewJobRow | null, fallback?: ReviewEnvelopeFallbacks): ToolPayload;
+export declare function payloadFromRateLimit(err: unknown, jobId?: string | null): ToolPayload | null;

package/dist/lib/tools/envelope.js

@@ -0,0 +1,30 @@
+import { isCommandErrorCode, toReviewJobEnvelope, } from "mergestorm/client";
+export const MCP_REVIEW_STATUSES = [
+    "no_changes",
+    "queued",
+    "in_progress",
+    "completed",
+    "failed",
+    "quota_exceeded",
+    "rate_limited",
+];
+export function payloadFromRow(row, fallback = {}) {
+    const envelope = toReviewJobEnvelope(row, fallback);
+    const bits = [envelope.status];
+    if (envelope.verdict)
+        bits.push(envelope.verdict);
+    return {
+        summary: `${envelope.job_id ?? fallback.jobId ?? "review"} · ${bits.join(" · ")}`,
+        data: envelope,
+    };
+}
+export function payloadFromRateLimit(err, jobId) {
+    if (!isCommandErrorCode(err, "rate_limited"))
+        return null;
+    return payloadFromRow(null, {
+        jobId,
+        status: "rate_limited",
+        error: err.message,
+        retryAfterSeconds: err.retryAfterSeconds,
+    });
+}

package/dist/lib/tools/issue-create.d.ts

@@ -0,0 +1,47 @@
+import { openStackIssue, parseGithubOriginRepo, type Config } from "mergestorm/client";
+import { z } from "zod";
+import type { ToolPayload } from "./types.js";
+export declare const issueCreateSchema: {
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    owner: z.ZodOptional<z.ZodString>;
+    repo: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+};
+export declare const hostedIssueCreateSchema: {
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    owner: z.ZodString;
+    repo: z.ZodString;
+};
+declare const inputSchema: z.ZodObject<{
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    owner: z.ZodOptional<z.ZodString>;
+    repo: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    owner?: string | undefined;
+    body?: string | undefined;
+    labels?: string[] | undefined;
+    repo?: string | undefined;
+    cwd?: string | undefined;
+}, {
+    title: string;
+    owner?: string | undefined;
+    body?: string | undefined;
+    labels?: string[] | undefined;
+    repo?: string | undefined;
+    cwd?: string | undefined;
+}>;
+export type IssueCreateInput = z.infer<typeof inputSchema>;
+export type IssueCreateDeps = {
+    openStackIssue?: typeof openStackIssue;
+    parseGithubOriginRepo?: typeof parseGithubOriginRepo;
+};
+export declare function issueCreate(input: IssueCreateInput, cfg?: Config, deps?: IssueCreateDeps): Promise<ToolPayload>;
+export {};

package/dist/lib/tools/issue-create.js

@@ -0,0 +1,53 @@
+import { CommandError, openStackIssue, parseGithubOriginRepo } from "mergestorm/client";
+import { z } from "zod";
+export const issueCreateSchema = {
+    title: z.string().trim().min(1).max(256),
+    body: z.string().max(60_000).optional(),
+    labels: z.array(z.string().trim().min(1).max(50)).max(10).optional(),
+    owner: z.string().trim().regex(/^[A-Za-z0-9_.-]{1,100}$/).optional(),
+    repo: z.string().trim().regex(/^[A-Za-z0-9_.-]{1,100}$/).optional(),
+    cwd: z.string().trim().min(1).optional(),
+};
+export const hostedIssueCreateSchema = {
+    title: issueCreateSchema.title,
+    body: issueCreateSchema.body,
+    labels: issueCreateSchema.labels,
+    owner: z.string().trim().regex(/^[A-Za-z0-9_.-]{1,100}$/),
+    repo: z.string().trim().regex(/^[A-Za-z0-9_.-]{1,100}$/),
+};
+const inputSchema = z.object(issueCreateSchema);
+export async function issueCreate(input, cfg, deps = {}) {
+    const parsed = inputSchema.safeParse(input);
+    if (!parsed.success || Boolean(parsed.data.owner) !== Boolean(parsed.data.repo)) {
+        const message = "issue_create needs a one-line title of at most 256 characters, and owner and repo together";
+        return { summary: message, data: { error: { code: "invalid_input", message } }, isError: true };
+    }
+    const { title, body, labels, owner, repo, cwd } = parsed.data;
+    try {
+        const target = owner && repo ? { owner, repo } : (deps.parseGithubOriginRepo ?? parseGithubOriginRepo)(cwd);
+        if (!target) {
+            const message = "Could not read a GitHub owner/repo from origin. Pass owner and repo.";
+            return { summary: message, data: { error: { code: "invalid_input", message } }, isError: true };
+        }
+        const issue = await (deps.openStackIssue ?? openStackIssue)({ owner: target.owner, repo: target.repo, title, body: body ?? "", labels: labels ?? [] }, cfg);
+        return {
+            summary: `${issue.created ? "Opened" : "Already open:"} ${target.owner}/${target.repo}#${issue.number} ${issue.url}. Put "Fixes #${issue.number}" in the commit or pull request body.`,
+            data: { owner: target.owner, repo: target.repo, ...issue },
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            summary: message,
+            data: {
+                error: {
+                    code: err instanceof CommandError ? err.code ?? "issue_create_failed" : "issue_create_failed",
+                    message,
+                    ...(err instanceof CommandError && err.retryAfterSeconds !== undefined
+                        ? { retry_after_seconds: err.retryAfterSeconds } : {}),
+                },
+            },
+            isError: true,
+        };
+    }
+}

package/dist/lib/tools/queue-status.d.ts

@@ -0,0 +1,3 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare function queueStatus(stackId?: string, cfg?: Config): Promise<ToolPayload>;

package/dist/lib/tools/queue-status.js

@@ -0,0 +1,79 @@
+import { apiFetch, CommandError, isCommandErrorCode, loadConfig, rateLimitedMessage, REVIEW_EXIT, } from "mergestorm/client";
+function entrySummary(entry) {
+    const prNumber = entry.bounceDetail?.prNumber;
+    const repo = `${entry.owner}/${entry.repo}${prNumber ? `#${prNumber}` : ""}`;
+    const reason = entry.bounceDetail?.kind ?? entry.bounceReason ?? entry.waitReason ?? undefined;
+    const sha = entry.bounceDetail?.headSha ?? entry.verifyHeadSha ?? undefined;
+    return [
+        entry.state,
+        repo,
+        `stack ${entry.stackId}`,
+        reason,
+        sha?.slice(0, 7),
+    ].filter(Boolean).join(" · ");
+}
+export async function queueStatus(stackId, cfg) {
+    try {
+        const resolved = cfg ?? (await loadConfig());
+        const id = stackId?.trim();
+        const { status, body, retryAfterSeconds } = await apiFetch(resolved, id
+            ? `/api/v1/stacks/queue?stackId=${encodeURIComponent(id)}`
+            : "/api/v1/stacks/queue");
+        if (status === 404) {
+            throw new CommandError("Merge queue route returned 404. Deploy the API.");
+        }
+        if (status === 429) {
+            throw new CommandError(rateLimitedMessage(retryAfterSeconds), REVIEW_EXIT.rate_limited, "rate_limited", { retryAfterSeconds });
+        }
+        if (status !== 200) {
+            throw new CommandError(`Failed to get queue status (HTTP ${status}): ${JSON.stringify(body)}`);
+        }
+        const entries = body.entries;
+        if (!Array.isArray(entries)) {
+            throw new CommandError(`Failed to get queue status (HTTP 200): ${JSON.stringify(body)}`);
+        }
+        if (id) {
+            const matchingEntries = entries.filter((candidate) => candidate?.stackId?.toLowerCase() === id.toLowerCase());
+            if (matchingEntries.length === 0) {
+                const message = `Queue entry not found for stack: ${id}`;
+                return {
+                    summary: message,
+                    data: {
+                        error: {
+                            code: "queue_entry_not_found",
+                            message,
+                            stack_id: id,
+                        },
+                    },
+                    isError: true,
+                };
+            }
+            return {
+                summary: matchingEntries.map(entrySummary).join("\n"),
+                data: { entries: matchingEntries },
+            };
+        }
+        return {
+            summary: entries.length === 0
+                ? "No merge queue entries (live or bounced)"
+                : entries.map(entrySummary).join("\n"),
+            data: { entries },
+        };
+    }
+    catch (err) {
+        if (isCommandErrorCode(err, "rate_limited")) {
+            return {
+                summary: err.message,
+                data: {
+                    error: {
+                        code: "rate_limited",
+                        message: err.message,
+                        retry_after_seconds: err.retryAfterSeconds,
+                    },
+                },
+                isError: true,
+            };
+        }
+        throw err;
+    }
+}

package/dist/lib/tools/repo-settings.d.ts

@@ -0,0 +1,6 @@
+import { type Config, type RepoSettings, type RepoSettingsPatch } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare function repoSettingsSummary(entry: RepoSettings): string;
+export declare function repoSettingsPatchFromArgs(args: Record<string, unknown>): RepoSettingsPatch;
+export declare function repoSettingsGet(args: Record<string, unknown>, cfg?: Config): Promise<ToolPayload>;
+export declare function repoSettingsSet(args: Record<string, unknown>, cfg?: Config): Promise<ToolPayload>;

package/dist/lib/tools/repo-settings.js

@@ -0,0 +1,54 @@
+import { CommandError, REPO_SETTINGS_KEYS, listRepoSettings, patchRepoSettings, } from "mergestorm/client";
+const ARG_BY_KEY = {
+    auto_patch_enabled: "auto_patch",
+    auto_review_enabled: "auto_review",
+    auto_land_default: "auto_land",
+};
+function parseRepo(raw) {
+    const match = typeof raw === "string" ? /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(raw.trim()) : null;
+    if (!match)
+        throw new CommandError("repo takes <owner>/<repo>.", 2, "usage");
+    return { owner: match[1], repo: match[2] };
+}
+function words(value) {
+    return value === null ? "inherit" : value ? "on" : "off";
+}
+export function repoSettingsSummary(entry) {
+    return `${entry.owner}/${entry.repo}: ${REPO_SETTINGS_KEYS.map((key) => `${ARG_BY_KEY[key]} ${words(entry[key])}`).join(" · ")}`;
+}
+export function repoSettingsPatchFromArgs(args) {
+    const patch = {};
+    for (const key of REPO_SETTINGS_KEYS) {
+        const value = args[ARG_BY_KEY[key]];
+        if (value === undefined)
+            continue;
+        if (value !== null && typeof value !== "boolean") {
+            throw new CommandError(`${ARG_BY_KEY[key]} takes true, false, or null.`, 2, "usage");
+        }
+        patch[key] = value;
+    }
+    if (Object.keys(patch).length === 0) {
+        throw new CommandError(`At least one of ${Object.values(ARG_BY_KEY).join(", ")} is required.`, 2, "usage");
+    }
+    return patch;
+}
+export async function repoSettingsGet(args, cfg) {
+    const wanted = args.repo === undefined ? null : parseRepo(args.repo);
+    const all = await listRepoSettings(cfg);
+    if (!wanted) {
+        return {
+            summary: all.length === 0 ? "No repositories are connected to this account." : all.map(repoSettingsSummary).join("\n"),
+            data: { repos: all },
+        };
+    }
+    const slug = `${wanted.owner}/${wanted.repo}`.toLowerCase();
+    const entry = all.find((candidate) => `${candidate.owner}/${candidate.repo}`.toLowerCase() === slug);
+    if (!entry)
+        throw new CommandError(`${wanted.owner}/${wanted.repo} is not connected to this account.`);
+    return { summary: repoSettingsSummary(entry), data: { ...entry } };
+}
+export async function repoSettingsSet(args, cfg) {
+    const { owner, repo } = parseRepo(args.repo);
+    const entry = await patchRepoSettings(owner, repo, repoSettingsPatchFromArgs(args), cfg);
+    return { summary: repoSettingsSummary(entry), data: { ...entry } };
+}

package/dist/lib/tools/review-dismiss.d.ts

@@ -0,0 +1,16 @@
+import { type Config, type PrFindingDismissResult } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export type ReviewDismissInput = {
+    owner: string;
+    repo: string;
+    pr_number: number;
+    head_sha: string;
+    review_id: number;
+    finding_ids?: string[];
+    scope?: "findings" | "review";
+    reason?: string;
+    evidence_url?: string;
+    preview?: boolean;
+};
+export declare function reviewDismissSummary(result: PrFindingDismissResult): string;
+export declare function reviewDismiss(input: ReviewDismissInput, cfg?: Config): Promise<ToolPayload>;

package/dist/lib/tools/review-dismiss.js

@@ -0,0 +1,68 @@
+import { dismissPrFindings, dismissThreadsLine, stackWatchObligation, } from "mergestorm/client";
+import { withWatchText } from "./stack-wait.js";
+function findingText(finding) {
+    return `${finding.finding_id} (${finding.path ?? "review body"}: ${finding.title})`;
+}
+export function reviewDismissSummary(result) {
+    const pr = `${result.owner}/${result.repo}#${result.pr_number}`;
+    const kind = result.review_kind === "seam" ? "seam review" : "Vortex review";
+    const head = `${kind} ${result.review_id} at ${result.head_sha.slice(0, 7)}`;
+    const lines = [];
+    if (result.status === "preview") {
+        lines.push(`${pr} ${head}: ${result.remaining.length} open finding(s). Nothing was written.`);
+        for (const finding of result.remaining)
+            lines.push(`- ${findingText(finding)}`);
+    }
+    else {
+        lines.push(`${pr} ${head}: dismissed ${result.dismissed.length}, already dismissed ${result.already_dismissed.length}, still open ${result.remaining.length}.`);
+        for (const finding of result.remaining)
+            lines.push(`- open: ${findingText(finding)}`);
+        const threads = dismissThreadsLine(result);
+        if (threads)
+            lines.push(threads);
+    }
+    const seam = result.gate.seam;
+    if (seam) {
+        lines.push(seam.cleared
+            ? "Seam gate cleared at this head. CI, other reviews and Auto land policy are unchanged."
+            : seam.blocking
+                ? `Seam gate still blocking (seam_state=${seam.state}).`
+                : `Seam gate not blocking (seam_state=${seam.state}).`);
+    }
+    const vortex = result.gate.vortex;
+    if (vortex?.cleared) {
+        lines.push("Vortex gate cleared at this head: every Vortex Blocker (error finding) at this head is dismissed. CI and Auto land policy are unchanged.");
+    }
+    else if (vortex?.message && vortex.reason !== "review_findings_open") {
+        lines.push(`Vortex gate not cleared: ${vortex.message}`);
+    }
+    return lines.join("\n");
+}
+export async function reviewDismiss(input, cfg) {
+    const request = {
+        owner: input.owner,
+        repo: input.repo,
+        prNumber: input.pr_number,
+        headSha: input.head_sha,
+        reviewId: input.review_id,
+        ...(input.scope ? { scope: input.scope } : {}),
+        ...(input.finding_ids ? { findingIds: input.finding_ids } : {}),
+        ...(input.reason !== undefined ? { reason: input.reason } : {}),
+        ...(input.evidence_url ? { evidenceUrl: input.evidence_url } : {}),
+        ...(input.preview ? { preview: true } : {}),
+    };
+    const outcome = await dismissPrFindings(request, cfg);
+    if (!outcome.ok) {
+        return {
+            summary: `review_dismiss refused (${outcome.error}): ${outcome.message}`,
+            isError: true,
+            data: { error: { code: outcome.error, message: outcome.message, status: outcome.status } },
+        };
+    }
+    const result = outcome.result;
+    const summary = reviewDismissSummary(result);
+    if (!result.stack_id)
+        return { summary, data: { ...result } };
+    const watch = stackWatchObligation({ stackId: result.stack_id, terminal: null, unread: true, freshCursor: true });
+    return { summary: withWatchText(watch, summary), data: { ...result, watch } };
+}

package/dist/lib/tools/review-get-pr.d.ts

@@ -0,0 +1,22 @@
+import { type Config, type PrVortexReview } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare function prReviewTarget(owner: string, repo: string, prNumber: number): {
+    owner: string;
+    repo: string;
+    prNumber: number;
+};
+export declare function prReviewSummary(owner: string, repo: string, prNumber: number, envelope: {
+    status: string;
+    head_sha?: string | null;
+    finding_count?: number | null;
+    phase?: string | null;
+}): string;
+export declare function payloadFromPrReview(owner: string, repo: string, prNumber: number, envelope: PrVortexReview): ToolPayload;
+export declare function payloadFromPrRateLimit(err: unknown, owner: string, repo: string, prNumber: number): ToolPayload | null;
+/** SHA + pass selection (#2027): `pass` is one exact attempt, `afterPass` a later one on the head. */
+export type ReviewGetPrOptions = {
+    afterSha?: string;
+    pass?: number;
+    afterPass?: number;
+};
+export declare function reviewGetPr(owner: string, repo: string, prNumber: number, cfg?: Config, opts?: ReviewGetPrOptions): Promise<ToolPayload>;

package/dist/lib/tools/review-get-pr.js

@@ -0,0 +1,52 @@
+import { CommandError, getPrVortexReview, isCommandErrorCode, } from "mergestorm/client";
+export function prReviewTarget(owner, repo, prNumber) {
+    const cleanOwner = owner.trim();
+    const cleanRepo = repo.trim();
+    if (!cleanOwner || !cleanRepo || !Number.isInteger(prNumber) || prNumber <= 0) {
+        throw new CommandError("owner, repo, and a positive pr_number are required", 2, "usage");
+    }
+    return { owner: cleanOwner, repo: cleanRepo, prNumber };
+}
+export function prReviewSummary(owner, repo, prNumber, envelope) {
+    const bits = [`${owner}/${repo}#${prNumber}`, envelope.status];
+    const sha = envelope.head_sha?.trim();
+    if (sha)
+        bits.push(`sha ${sha.slice(0, 7)}`);
+    if (typeof envelope.finding_count === "number") {
+        bits.push(`${envelope.finding_count} finding${envelope.finding_count === 1 ? "" : "s"}`);
+    }
+    if (envelope.phase)
+        bits.push(String(envelope.phase));
+    return bits.join(" · ");
+}
+export function payloadFromPrReview(owner, repo, prNumber, envelope) {
+    return {
+        summary: prReviewSummary(owner, repo, prNumber, envelope),
+        data: { ...envelope },
+    };
+}
+export function payloadFromPrRateLimit(err, owner, repo, prNumber) {
+    if (!isCommandErrorCode(err, "rate_limited"))
+        return null;
+    return {
+        summary: `${owner}/${repo}#${prNumber} · rate_limited`,
+        data: {
+            status: "rate_limited",
+            error: err.message,
+            retry_after_seconds: err.retryAfterSeconds,
+        },
+    };
+}
+export async function reviewGetPr(owner, repo, prNumber, cfg, opts = {}) {
+    const target = prReviewTarget(owner, repo, prNumber);
+    try {
+        const envelope = await getPrVortexReview(target.owner, target.repo, target.prNumber, cfg, { afterSha: opts.afterSha, pass: opts.pass, afterPass: opts.afterPass });
+        return payloadFromPrReview(target.owner, target.repo, target.prNumber, envelope);
+    }
+    catch (err) {
+        const rateLimited = payloadFromPrRateLimit(err, target.owner, target.repo, target.prNumber);
+        if (rateLimited)
+            return rateLimited;
+        throw err;
+    }
+}

package/dist/lib/tools/review-get.d.ts

@@ -0,0 +1,3 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare function reviewGet(jobId: string, cfg?: Config): Promise<ToolPayload>;

package/dist/lib/tools/review-get.js

@@ -0,0 +1,27 @@
+import { CommandError, getReview, toReviewJobEnvelope, } from "mergestorm/client";
+import { payloadFromRateLimit } from "./envelope.js";
+export async function reviewGet(jobId, cfg) {
+    let row;
+    try {
+        row = await getReview(jobId, cfg);
+    }
+    catch (err) {
+        const rateLimited = payloadFromRateLimit(err, jobId);
+        if (rateLimited)
+            return rateLimited;
+        throw err;
+    }
+    if (!row ||
+        typeof row !== "object" ||
+        typeof row.status !== "string") {
+        throw new CommandError(`Unexpected response for review ${jobId}.`);
+    }
+    const envelope = toReviewJobEnvelope(row, { jobId });
+    const bits = [envelope.status];
+    if (envelope.verdict)
+        bits.push(envelope.verdict);
+    return {
+        summary: `${envelope.job_id ?? jobId} · ${bits.join(" · ")}`,
+        data: envelope,
+    };
+}

package/dist/lib/tools/review-list.d.ts

@@ -0,0 +1,3 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare function reviewList(limit?: number, cfg?: Config): Promise<ToolPayload>;

package/dist/lib/tools/review-list.js

@@ -0,0 +1,10 @@
+import { listJobs, toReviewJobEnvelope } from "mergestorm/client";
+export async function reviewList(limit = 10, cfg) {
+    const items = await listJobs(limit, cfg);
+    const envelopes = items.map((row) => toReviewJobEnvelope(row));
+    const n = envelopes.length;
+    return {
+        summary: n === 0 ? "No review jobs" : `${n} review job${n === 1 ? "" : "s"}`,
+        data: { items: envelopes },
+    };
+}

package/dist/lib/tools/review-start.d.ts

@@ -0,0 +1,11 @@
+import type { Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export type PullRequestInput = {
+    owner: string;
+    repo: string;
+    pr_number: number;
+};
+export declare function reviewStartPr(input: PullRequestInput & {
+    head_sha?: string;
+}, cfg?: Config, chatId?: string | null): Promise<ToolPayload>;
+export declare function reviewStopPr(input: PullRequestInput, cfg?: Config): Promise<ToolPayload>;