mergestorm-mcp 0.2.25 → 0.2.27

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

@@ -0,0 +1,21 @@
+import { agentRequest } from "./agent-request.js";
+import { REVIEW_START_WAIT_NOTE } from "./chat-wake.js";
+export async function reviewStartPr(input, cfg, chatId) {
+    const payload = await agentRequest("/api/v1/agents/vortex/review", {
+        method: "POST",
+        json: {
+            owner: input.owner,
+            repo: input.repo,
+            pr_number: input.pr_number,
+            ...(input.head_sha ? { head_sha: input.head_sha } : {}),
+            ...(chatId ? { chat_id: chatId } : {}),
+        },
+    }, cfg);
+    return payload.data.chat_wake ? { ...payload, summary: `${payload.summary} ${REVIEW_START_WAIT_NOTE}` } : payload;
+}
+export async function reviewStopPr(input, cfg) {
+    return agentRequest("/api/v1/agents/vortex/stop", {
+        method: "POST",
+        json: { owner: input.owner, repo: input.repo, pr_number: input.pr_number },
+    }, cfg);
+}

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

@@ -0,0 +1,36 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+/** Hard maximum for an explicitly requested MCP poll slice. */
+export declare const MCP_WAIT_CEILING_S = 300;
+/**
+ * Default bound for local and PR review waits. Reviews can take minutes or hours;
+ * Cursor kills a single MCP call around a minute, so this is one poll
+ * slice. The skill loops until the review finishes.
+ */
+export declare const MCP_PR_WAIT_DEFAULT_S = 45;
+export declare function assertPinnableSpecialists(specialists: string[] | undefined): void;
+/**
+ * Host-configured root that agent-chosen `context_files` may not escape.
+ * The `cwd` tool argument is agent-controlled, so it cannot serve as the
+ * sandbox root; default to the MCP server's own working directory.
+ */
+export declare function mcpSandboxRoot(): string;
+export type ReviewSubmitInput = {
+    cwd?: string;
+    base?: string;
+    head?: string;
+    diff?: string;
+    router?: string;
+    specialists?: string[];
+    context?: string;
+    context_files?: string[];
+    thread?: string;
+    idempotency_key?: string;
+    wait?: boolean;
+    timeout_s?: number;
+};
+export type ReviewSubmitOptions = {
+    pollIntervalMs?: number;
+};
+export declare function waitTimeoutMs(timeout_s?: number, defaultSeconds?: number): number;
+export declare function reviewSubmit(input: ReviewSubmitInput, cfg?: Config, opts?: ReviewSubmitOptions): Promise<ToolPayload>;

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

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+import { CommandError, REVIEW_THREAD_SLUG_RE, ReviewPollTimeoutError, collectReviewInput, discoverTrunk, formatReviewSubmitError, loadConfig, loadReviewContext, pollReview, rateLimitedMessage, submitReview, } from "mergestorm/client";
+import { payloadFromRateLimit, payloadFromRow } from "./envelope.js";
+/** Hard maximum for an explicitly requested MCP poll slice. */
+export const MCP_WAIT_CEILING_S = 300;
+/**
+ * Default bound for local and PR review waits. Reviews can take minutes or hours;
+ * Cursor kills a single MCP call around a minute, so this is one poll
+ * slice. The skill loops until the review finishes.
+ */
+export const MCP_PR_WAIT_DEFAULT_S = 45;
+/** Pinnable L0 lanes. `governance` and `seam` are L1 and cannot be requested. */
+const PINNABLE_SPECIALISTS = [
+    "security",
+    "performance",
+    "architecture",
+    "tests",
+    "data",
+    "api",
+    "frontend",
+];
+export function assertPinnableSpecialists(specialists) {
+    if (!specialists?.length)
+        return;
+    const unknown = specialists.filter((id) => !PINNABLE_SPECIALISTS.includes(id));
+    if (unknown.length === 0)
+        return;
+    throw new CommandError(`Unknown specialist: ${unknown.join(", ")}. Valid lanes: ${PINNABLE_SPECIALISTS.join(", ")}. governance and seam cannot be requested.`, 2, "usage");
+}
+/**
+ * Host-configured root that agent-chosen `context_files` may not escape.
+ * The `cwd` tool argument is agent-controlled, so it cannot serve as the
+ * sandbox root; default to the MCP server's own working directory.
+ */
+export function mcpSandboxRoot() {
+    return process.env.MERGESTORM_SANDBOX_ROOT?.trim() || process.cwd();
+}
+export function waitTimeoutMs(timeout_s, defaultSeconds = MCP_PR_WAIT_DEFAULT_S) {
+    const seconds = timeout_s ?? defaultSeconds;
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        throw new CommandError("timeout_s must be a positive number of seconds", 2, "usage");
+    }
+    return Math.max(1, Math.round(Math.min(seconds, MCP_WAIT_CEILING_S) * 1_000));
+}
+async function resolveInput(input) {
+    const cwd = input.cwd ?? process.cwd();
+    const head = input.head?.trim() || "HEAD";
+    if (input.diff?.trim()) {
+        const branch = "local";
+        const thread = input.thread?.trim() ||
+            `local/diff-${createHash("sha256").update(input.diff).digest("hex").slice(0, 12)}`;
+        return {
+            thread,
+            branch,
+            baseLabel: input.base?.trim() ||
+                (() => {
+                    try {
+                        return discoverTrunk(cwd);
+                    }
+                    catch {
+                        return "main";
+                    }
+                })(),
+            headLabel: head,
+            diff: input.diff,
+            files: [],
+        };
+    }
+    const sandboxRoot = mcpSandboxRoot();
+    try {
+        const [sandboxReal, cwdReal] = await Promise.all([
+            realpath(resolve(sandboxRoot)),
+            realpath(resolve(cwd)),
+        ]);
+        const relToSandbox = relative(sandboxReal, cwdReal);
+        if (relToSandbox === ".." || relToSandbox.startsWith(`..${sep}`)) {
+            throw new CommandError("cwd must be inside the configured sandbox root", 2, "usage");
+        }
+    }
+    catch (err) {
+        if (err instanceof CommandError)
+            throw err;
+        throw new CommandError("cwd must be inside the configured sandbox root", 2, "usage");
+    }
+    const base = input.base?.trim() || discoverTrunk(cwd);
+    return collectReviewInput(base, head, cwd, sandboxRoot);
+}
+export async function reviewSubmit(input, cfg, opts = {}) {
+    const resolved = cfg ?? (await loadConfig());
+    const wait = input.wait === true;
+    const timeoutMs = waitTimeoutMs(input.timeout_s);
+    assertPinnableSpecialists(input.specialists);
+    if (input.thread && !REVIEW_THREAD_SLUG_RE.test(input.thread)) {
+        throw new CommandError("thread must be 1–120 chars [A-Za-z0-9._/-]", 2, "usage");
+    }
+    if (input.context === "-") {
+        throw new CommandError('context "-" (stdin) is not available over MCP; pass the text directly', 2, "usage");
+    }
+    const collected = await resolveInput(input);
+    if (!collected) {
+        return payloadFromRow(null, { status: "no_changes" });
+    }
+    if (input.thread)
+        collected.thread = input.thread;
+    const extras = await loadReviewContext({
+        context: input.context,
+        contextFiles: input.context_files ?? [],
+        cwd: input.cwd ?? process.cwd(),
+        sandboxCwd: mcpSandboxRoot(),
+    });
+    const submitted = await submitReview(resolved, collected, {
+        routerMode: input.router,
+        specialists: input.specialists,
+        context: extras.context,
+        contextFiles: extras.contextFiles,
+        idempotencyKey: input.idempotency_key,
+    });
+    const jobId = submitted.row.job_id ?? submitted.row.id ?? null;
+    if (submitted.status === 402) {
+        return payloadFromRow(submitted.row, {
+            jobId,
+            status: "quota_exceeded",
+            error: "Review limit reached for this period.",
+        });
+    }
+    if (submitted.status === 429) {
+        return payloadFromRow(submitted.row, {
+            jobId,
+            status: "rate_limited",
+            error: rateLimitedMessage(submitted.retryAfterSeconds),
+            retryAfterSeconds: submitted.retryAfterSeconds,
+        });
+    }
+    if (submitted.status !== 202 && submitted.status !== 200) {
+        return {
+            ...payloadFromRow({ ...submitted.row, status: "failed" }, {
+                jobId,
+                error: formatReviewSubmitError(submitted.status, submitted.row),
+            }),
+            isError: true,
+        };
+    }
+    if (!jobId) {
+        throw new CommandError("Review API returned no job_id");
+    }
+    if (!wait) {
+        return payloadFromRow(submitted.row, { jobId, status: submitted.row.status ?? "queued" });
+    }
+    let row;
+    try {
+        row = await pollReview(resolved, jobId, {
+            timeoutMs,
+            intervalMs: opts.pollIntervalMs,
+        });
+    }
+    catch (err) {
+        if (err instanceof ReviewPollTimeoutError) {
+            return payloadFromRow(err.lastRow, {
+                jobId,
+                status: err.lastRow.status ?? "in_progress",
+                error: "Timed out waiting for review.",
+            });
+        }
+        const rateLimited = payloadFromRateLimit(err, jobId);
+        if (rateLimited)
+            return rateLimited;
+        throw err;
+    }
+    return payloadFromRow(row, { jobId });
+}

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

@@ -0,0 +1,11 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export type ReviewWaitPrOptions = {
+    pollIntervalMs?: number;
+    /** Exact pass on the head (#2027). */
+    pass?: number;
+    /** Only a pass later than this one on the head; fixed for the whole wait (#2027). */
+    afterPass?: number;
+    chatId?: string;
+};
+export declare function reviewWaitPr(owner: string, repo: string, prNumber: number, afterSha?: string, timeout_s?: number, cfg?: Config, opts?: ReviewWaitPrOptions): Promise<ToolPayload>;

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

@@ -0,0 +1,74 @@
+import { PrReviewPollTimeoutError, loadConfig, noPrReviewYetMessage, pollPrVortexReview, } from "mergestorm/client";
+import { payloadFromPrRateLimit, payloadFromPrReview, prReviewSummary, prReviewTarget, reviewGetPr, } from "./review-get-pr.js";
+import { MCP_PR_WAIT_DEFAULT_S, waitTimeoutMs } from "./review-submit.js";
+import { CHAT_WAKE_REVIEW_NOTE, registerChatWake } from "./chat-wake.js";
+export async function reviewWaitPr(owner, repo, prNumber, afterSha, timeout_s, cfg, opts = {}) {
+    const target = prReviewTarget(owner, repo, prNumber);
+    const resolved = cfg ?? (await loadConfig());
+    if (timeout_s === 0) {
+        return reviewGetPr(target.owner, target.repo, target.prNumber, resolved, {
+            afterSha,
+            pass: opts.pass,
+            afterPass: opts.afterPass,
+        });
+    }
+    try {
+        const envelope = await pollPrVortexReview(resolved, target.owner, target.repo, target.prNumber, {
+            timeoutMs: waitTimeoutMs(timeout_s, MCP_PR_WAIT_DEFAULT_S),
+            afterSha,
+            pass: opts.pass,
+            afterPass: opts.afterPass,
+            intervalMs: opts.pollIntervalMs,
+        });
+        return payloadFromPrReview(target.owner, target.repo, target.prNumber, envelope);
+    }
+    catch (err) {
+        if (err instanceof PrReviewPollTimeoutError) {
+            const status = err.reviewSeen ? "in_progress" : "none";
+            const expectedSha = afterSha?.trim().toLowerCase() ?? "";
+            const observedSha = err.lastEnvelope?.head_sha?.trim().toLowerCase() ?? "";
+            const headShaMatches = Boolean(observedSha &&
+                expectedSha.length >= 7 &&
+                (observedSha.startsWith(expectedSha) || expectedSha.startsWith(observedSha)));
+            const findingCount = headShaMatches
+                ? err.lastEnvelope?.finding_count ?? null
+                : null;
+            const summary = prReviewSummary(target.owner, target.repo, target.prNumber, {
+                status,
+                head_sha: err.lastEnvelope?.head_sha ?? null,
+                finding_count: findingCount,
+                phase: err.lastEnvelope?.phase ?? null,
+            });
+            const wakeHead = expectedSha || observedSha || null;
+            const wake = opts.chatId
+                ? await registerChatWake(resolved, opts.chatId, {
+                    kind: "vortex",
+                    owner: target.owner,
+                    repo: target.repo,
+                    prNumber: target.prNumber,
+                    headSha: wakeHead,
+                    minPass: opts.pass ?? (opts.afterPass !== undefined ? opts.afterPass + 1 : (headShaMatches || !expectedSha) && observedSha ? err.lastEnvelope?.pass ?? null : null),
+                })
+                : null;
+            const shown = err.reviewSeen
+                ? summary
+                : `${summary} · ${noPrReviewYetMessage(target.owner, target.repo, target.prNumber, { afterSha, pass: opts.pass, afterPass: opts.afterPass })}`;
+            return {
+                summary: wake ? `${shown} · ${CHAT_WAKE_REVIEW_NOTE}` : shown,
+                data: {
+                    status,
+                    head_sha: err.lastEnvelope?.head_sha ?? null,
+                    pass: headShaMatches ? err.lastEnvelope?.pass ?? null : null,
+                    finding_count: findingCount,
+                    phase: err.lastEnvelope?.phase ?? null,
+                    error: err.message,
+                    ...(wake ? { chat_wake: wake } : {}),
+                },
+            };
+        }
+        const rateLimited = payloadFromPrRateLimit(err, target.owner, target.repo, target.prNumber);
+        if (rateLimited)
+            return rateLimited;
+        throw err;
+    }
+}

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

@@ -0,0 +1,6 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export type ReviewWaitOptions = {
+    pollIntervalMs?: number;
+};
+export declare function reviewWait(jobId: string, timeout_s?: number, cfg?: Config, opts?: ReviewWaitOptions): Promise<ToolPayload>;

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

@@ -0,0 +1,33 @@
+import { CommandError, ReviewPollTimeoutError, loadConfig, pollReview, } from "mergestorm/client";
+import { payloadFromRateLimit, payloadFromRow } from "./envelope.js";
+import { reviewGet } from "./review-get.js";
+import { waitTimeoutMs } from "./review-submit.js";
+export async function reviewWait(jobId, timeout_s, cfg, opts = {}) {
+    const resolved = cfg ?? (await loadConfig());
+    const id = jobId.trim();
+    if (!id) {
+        throw new CommandError("job_id is required", 2, "usage");
+    }
+    if (timeout_s === 0)
+        return reviewGet(id, resolved);
+    try {
+        const row = await pollReview(resolved, id, {
+            timeoutMs: waitTimeoutMs(timeout_s),
+            intervalMs: opts.pollIntervalMs,
+        });
+        return payloadFromRow(row, { jobId: id });
+    }
+    catch (err) {
+        if (err instanceof ReviewPollTimeoutError) {
+            return payloadFromRow(err.lastRow, {
+                jobId: id,
+                status: err.lastRow.status ?? "in_progress",
+                error: "Timed out waiting for review.",
+            });
+        }
+        const rateLimited = payloadFromRateLimit(err, id);
+        if (rateLimited)
+            return rateLimited;
+        throw err;
+    }
+}

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

@@ -0,0 +1,8 @@
+import { type Config, type SettingsResponse } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+/**
+ * One line an agent can act on without opening the data: is Cyclone allowed
+ * to patch, and is it even connected.
+ */
+export declare function settingsSummary(settings: SettingsResponse): string;
+export declare function settingsGet(cfg?: Config): Promise<ToolPayload>;

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

@@ -0,0 +1,33 @@
+import { CommandError, getSettings, } from "mergestorm/client";
+/**
+ * One line an agent can act on without opening the data: is Cyclone allowed
+ * to patch, and is it even connected.
+ */
+export function settingsSummary(settings) {
+    const autoPatch = settings.auto_patch_enabled ? "on" : "off";
+    const automations = [
+        settings.auto_resolve_conflicts_enabled ? "auto_resolve_conflicts on" : null,
+        settings.auto_fix_ci_enabled ? "auto_fix_ci on" : null,
+    ].filter((label) => label !== null);
+    const autoPatchLabel = [`auto_patch ${autoPatch}`, ...automations].join(" · ");
+    const cyclone = settings.cyclone_connected
+        ? "Cyclone connected"
+        : "Cyclone not connected";
+    if (typeof settings.stacks_ready !== "boolean")
+        return `${autoPatchLabel} · ${cyclone}`;
+    const stacks = settings.stacks_ready
+        ? "stacks, merge queue and Auto land ready"
+        : "stacks, merge queue and Auto land not ready (install Mergestorm Surge)";
+    return `${autoPatchLabel} · ${cyclone} (auto patch) · ${stacks}`;
+}
+export async function settingsGet(cfg) {
+    const settings = await getSettings(cfg);
+    if (!settings) {
+        throw new CommandError("Settings are not available (offline or API too old). " +
+            "Try again or open https://mergestorm.ai/settings");
+    }
+    return {
+        summary: settingsSummary(settings),
+        data: { ...settings },
+    };
+}

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

@@ -0,0 +1,11 @@
+import { type Config, type SettingsPatch } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+/** Read-only on `/api/v1/settings`; the API owns them, agents never write them. */
+export declare const SETTINGS_READ_ONLY_KEYS: readonly ["cyclone_connected", "github_connected"];
+/**
+ * Build a PATCH body from raw tool args. Only the Bearer-writable allowlist
+ * passes through; read-only keys and empty patches are usage errors so the
+ * failure is the caller's wording, never a silent no-op.
+ */
+export declare function settingsPatchFromArgs(args: Record<string, unknown>): SettingsPatch;
+export declare function settingsSet(args: Record<string, unknown>, cfg?: Config): Promise<ToolPayload>;

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

@@ -0,0 +1,62 @@
+import { CommandError, BEARER_SETTINGS, SETTINGS_WRITABLE_KEYS, patchSettings, } from "mergestorm/client";
+import { settingsSummary } from "./settings-get.js";
+/** Read-only on `/api/v1/settings`; the API owns them, agents never write them. */
+export const SETTINGS_READ_ONLY_KEYS = [
+    "cyclone_connected",
+    "github_connected",
+];
+/**
+ * Build a PATCH body from raw tool args. Only the Bearer-writable allowlist
+ * passes through; read-only keys and empty patches are usage errors so the
+ * failure is the caller's wording, never a silent no-op.
+ */
+export function settingsPatchFromArgs(args) {
+    for (const key of SETTINGS_READ_ONLY_KEYS) {
+        if (args[key] !== undefined) {
+            throw new CommandError(`${key} is read-only and cannot be set.`, 2, "usage");
+        }
+    }
+    const patch = {};
+    for (const key of SETTINGS_WRITABLE_KEYS) {
+        const value = args[key];
+        if (value === undefined)
+            continue;
+        const row = BEARER_SETTINGS.find((row) => row.key === key);
+        if ("kind" in row && (row.kind === "seconds" || row.kind === "count")) {
+            if (typeof value !== "number" ||
+                !Number.isInteger(value) ||
+                value < row.min ||
+                value > row.max) {
+                const unit = row.kind === "seconds" ? " of seconds" : "";
+                throw new CommandError(`${key} takes a whole number${unit} from ${row.min} through ${row.max}.`, 2, "usage");
+            }
+            Object.assign(patch, { [key]: value });
+            continue;
+        }
+        if ("kind" in row) {
+            const valid = row.kind === "logins"
+                ? Array.isArray(value) && value.every((login) => typeof login === "string")
+                : typeof value === "string" && row.values.includes(value);
+            if (!valid)
+                throw new CommandError(`Invalid value for ${key}.`, 2, "usage");
+            Object.assign(patch, { [key]: value });
+            continue;
+        }
+        if (typeof value !== "boolean") {
+            throw new CommandError(`${key} takes a boolean.`, 2, "usage");
+        }
+        Object.assign(patch, { [key]: value });
+    }
+    if (Object.keys(patch).length === 0) {
+        throw new CommandError(`At least one settings key is required: ${SETTINGS_WRITABLE_KEYS.join(", ")}.`, 2, "usage");
+    }
+    return patch;
+}
+export async function settingsSet(args, cfg) {
+    const patch = settingsPatchFromArgs(args);
+    const settings = await patchSettings(patch, cfg);
+    return {
+        summary: settingsSummary(settings),
+        data: { ...settings },
+    };
+}

package/dist/lib/tools/stack-actions.d.ts

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

package/dist/lib/tools/stack-actions.js

@@ -0,0 +1,22 @@
+import { enqueueStack, loadConfig, restackStack, stackWatchObligation } from "mergestorm/client";
+import { CHAT_WAKE_STACK_NOTE, registerChatWake } from "./chat-wake.js";
+import { withWatchText } from "./stack-wait.js";
+export async function stackRestack(stackId, cfg) {
+    const result = await restackStack(stackId, cfg);
+    const watch = stackWatchObligation({ stackId, terminal: null, unread: true, freshCursor: true });
+    return {
+        summary: withWatchText(watch, `Restacked stack ${stackId}: its layer branches were rebased onto their parents and pushed`),
+        data: { stack_id: stackId, result, watch },
+    };
+}
+export async function stackEnqueue(stackId, cfg, chatId) {
+    const resolved = cfg ?? (await loadConfig());
+    const result = await enqueueStack(stackId, resolved);
+    const watch = stackWatchObligation({ stackId, terminal: null, unread: true, freshCursor: true });
+    const wake = chatId ? await registerChatWake(resolved, chatId, { kind: "stack", stackId }) : null;
+    const summary = withWatchText(watch, `Sent stack ${stackId} to the Mergestorm merge queue`);
+    return {
+        summary: wake ? `${summary} ${CHAT_WAKE_STACK_NOTE}` : summary,
+        data: { stack_id: stackId, result, watch, ...(wake ? { chat_wake: wake } : {}) },
+    };
+}

package/dist/lib/tools/stack-adopt.d.ts

@@ -0,0 +1,44 @@
+import { type Config } from "mergestorm/client";
+import { z } from "zod";
+import type { ToolPayload } from "./types.js";
+export declare const stackAdoptSchema: {
+    owner: z.ZodString;
+    repo: z.ZodString;
+    pr_number: z.ZodNumber;
+    auto_land: z.ZodOptional<z.ZodBoolean>;
+    auto_review: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    auto_patch: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    auto_resolve_conflicts: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    auto_fix_ci: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+};
+declare const inputSchema: z.ZodObject<{
+    owner: z.ZodString;
+    repo: z.ZodString;
+    pr_number: z.ZodNumber;
+    auto_land: z.ZodOptional<z.ZodBoolean>;
+    auto_review: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    auto_patch: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    auto_resolve_conflicts: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    auto_fix_ci: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    owner: string;
+    repo: string;
+    pr_number: number;
+    auto_patch?: boolean | null | undefined;
+    auto_review?: boolean | null | undefined;
+    auto_land?: boolean | undefined;
+    auto_resolve_conflicts?: boolean | null | undefined;
+    auto_fix_ci?: boolean | null | undefined;
+}, {
+    owner: string;
+    repo: string;
+    pr_number: number;
+    auto_patch?: boolean | null | undefined;
+    auto_review?: boolean | null | undefined;
+    auto_land?: boolean | undefined;
+    auto_resolve_conflicts?: boolean | null | undefined;
+    auto_fix_ci?: boolean | null | undefined;
+}>;
+export type StackAdoptInput = z.infer<typeof inputSchema>;
+export declare function stackAdopt(input: StackAdoptInput, cfg?: Config): Promise<ToolPayload>;
+export {};

package/dist/lib/tools/stack-adopt.js

@@ -0,0 +1,55 @@
+import { adoptStack, CommandError, stackWatchObligation } from "mergestorm/client";
+import { z } from "zod";
+import { stackSetPatch } from "./stack-set.js";
+import { withWatchText } from "./stack-wait.js";
+export const stackAdoptSchema = {
+    owner: z.string().trim().min(1),
+    repo: z.string().trim().min(1),
+    pr_number: z.number().int().min(1),
+    auto_land: z.boolean().optional(),
+    auto_review: z.boolean().nullable().optional(),
+    auto_patch: z.boolean().nullable().optional(),
+    auto_resolve_conflicts: z.boolean().nullable().optional(),
+    auto_fix_ci: z.boolean().nullable().optional(),
+};
+const inputSchema = z.object(stackAdoptSchema);
+export async function stackAdopt(input, cfg) {
+    const parsed = inputSchema.safeParse(input);
+    if (!parsed.success) {
+        const message = "stack_adopt requires owner, repo, a positive pr_number, and valid policy values";
+        return { summary: message, data: { error: { code: "invalid_input", message } }, isError: true };
+    }
+    const { owner, repo, pr_number } = parsed.data;
+    try {
+        const result = await adoptStack(owner, repo, pr_number, cfg, stackSetPatch(parsed.data));
+        const summary = `Adopted stack for ${owner}/${repo}#${pr_number}`;
+        const stackId = typeof result === "object" && result !== null
+            ? result.stack?.id
+            : undefined;
+        if (typeof stackId !== "string" || !stackId) {
+            return { summary, data: { owner, repo, pr_number, result } };
+        }
+        const watch = stackWatchObligation({ stackId, terminal: null, unread: true, freshCursor: true });
+        return {
+            summary: withWatchText(watch, summary),
+            data: { owner, repo, pr_number, result, watch },
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            summary: message,
+            data: {
+                error: {
+                    code: err instanceof CommandError ? err.code ?? "stack_adopt_failed" : "stack_adopt_failed",
+                    message,
+                    ...(err instanceof CommandError ? { exit_code: err.exitCode } : {}),
+                    ...(err instanceof CommandError && err.reason !== undefined ? { reason: err.reason } : {}),
+                    ...(err instanceof CommandError && err.retryAfterSeconds !== undefined
+                        ? { retry_after_seconds: err.retryAfterSeconds } : {}),
+                },
+            },
+            isError: true,
+        };
+    }
+}

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

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

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

@@ -0,0 +1,30 @@
+import { isCommandErrorCode, listMergeQueueEntries, listStacks, } from "mergestorm/client";
+import { stackSummary } from "./stack-summary.js";
+export async function stackList(cfg) {
+    try {
+        const stacks = await listStacks(cfg);
+        const entries = await listMergeQueueEntries(cfg);
+        return {
+            summary: stacks.length === 0
+                ? "No stacks"
+                : stacks.map((stack) => stackSummary(stack, entries)).join("\n"),
+            data: { stacks },
+        };
+    }
+    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;
+    }
+}