mergestorm-mcp 0.2.26 → 0.2.27

package/dist/lib/server.js

@@ -0,0 +1,558 @@
+import { breezeChatId } from "./tools/chat-wake.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CommandError, BEARER_SETTINGS } from "mergestorm/client";
+import { MCP_SERVER_ICONS, MCP_WEBSITE_URL } from "./brand-icons.js";
+import { credits } from "./tools/credits.js";
+import { hostedIssueCreateSchema, issueCreate, issueCreateSchema } from "./tools/issue-create.js";
+import { queueStatus } from "./tools/queue-status.js";
+import { reviewDismiss } from "./tools/review-dismiss.js";
+import { reviewStartPr, reviewStopPr } from "./tools/review-start.js";
+import { CYCLONE_JOB_WAIT_DEFAULT_S, CYCLONE_JOB_WAIT_MAX_S, CYCLONE_TASKS, cycloneJob, cycloneStart } from "./tools/cyclone-job.js";
+import { stackEnqueue, stackRestack } from "./tools/stack-actions.js";
+import { surgeSetup } from "./tools/surge-setup.js";
+import { reviewList } from "./tools/review-list.js";
+import { reviewSubmit } from "./tools/review-submit.js";
+import { reviewWaitPr } from "./tools/review-wait-pr.js";
+import { reviewWait } from "./tools/review-wait.js";
+import { settingsGet } from "./tools/settings-get.js";
+import { settingsSet } from "./tools/settings-set.js";
+import { repoSettingsGet, repoSettingsSet } from "./tools/repo-settings.js";
+import { stackAdopt, stackAdoptSchema } from "./tools/stack-adopt.js";
+import { stackList } from "./tools/stack-list.js";
+import { stackPublish, stackPublishSchema, stackPublishStatus, stackPublishStatusSchema } from "./tools/stack-publish.js";
+import { stackSet } from "./tools/stack-set.js";
+import { stackWait, stackWaitSchema } from "./tools/stack-wait.js";
+import { stackStatus } from "./tools/stack-status.js";
+import { whoami } from "./tools/whoami.js";
+import { MCP_FINDING_DEFERRAL_RULE, MCP_STACK_DONE_INSTRUCTIONS, MCP_PR_LOOP_INSTRUCTIONS, MCP_STACK_BASE_INSTRUCTIONS, MCP_STACK_WATCH_INSTRUCTIONS, } from "./pr-loop-instructions.js";
+export const MCP_SERVER_NAME = "mergestorm";
+export const MCP_SERVER_VERSION = "0.2.27";
+export const MCP_TOOL_NAMES = [
+    "whoami",
+    "credits",
+    "review_list",
+    "review_submit",
+    "review_wait",
+    "review_wait_pr",
+    "review_dismiss",
+    "review_start_pr",
+    "review_stop_pr",
+    "cyclone_start",
+    "cyclone_job",
+    "issue_create",
+    "stack_adopt",
+    "stack_enqueue",
+    "stack_list",
+    "stack_publish",
+    "stack_publish_status",
+    "stack_restack",
+    "stack_set",
+    "stack_status",
+    "stack_wait",
+    "queue_status",
+    "settings_get",
+    "settings_set",
+    "repo_settings_get",
+    "repo_settings_set",
+    "surge_setup",
+];
+export const MCP_SERVER_INSTRUCTIONS = [
+    MCP_STACK_DONE_INSTRUCTIONS,
+    MCP_PR_LOOP_INSTRUCTIONS,
+    MCP_STACK_BASE_INSTRUCTIONS,
+    MCP_STACK_WATCH_INSTRUCTIONS,
+].join("\n\n");
+const STACK_ATTENTION_NOTE = " Attention covers every open layer, parked ones included, not only currentCandidate: it names the lowest layer with a blocker an agent must fix and no Vortex or Cyclone run working on it, and once that blocker clears the next read names the next blocked layer.";
+const STACK_WATCH_RESULT_NOTE = " Follow watch.next.args until watch.done; background watching requires a confirmed host notification. See server instructions.";
+function ok(payload) {
+    return {
+        ...(payload.isError ? { isError: true } : {}),
+        content: [
+            { type: "text", text: payload.summary },
+            { type: "text", text: JSON.stringify(payload.data) },
+        ],
+        structuredContent: payload.data,
+    };
+}
+export function fail(err) {
+    const message = err instanceof CommandError
+        ? err.code
+            ? `Mergestorm request failed (${err.code}${err.reason ? `, reason ${err.reason}` : ""}): ${err.message}.`
+            : err.message
+        : err instanceof Error
+            ? err.message
+            : String(err);
+    return ok({
+        isError: true,
+        summary: message,
+        data: {
+            error: {
+                message: err instanceof Error ? err.message : String(err),
+                ...(err instanceof CommandError ? {
+                    exit_code: err.exitCode,
+                    ...(err.code !== undefined ? { code: err.code } : {}),
+                    ...(err.reason !== undefined ? { reason: err.reason } : {}),
+                    ...(err.retryAfterSeconds !== undefined ? { retry_after_seconds: err.retryAfterSeconds } : {}),
+                } : {}),
+            },
+        },
+    });
+}
+export const MCP_WORKSPACE_TOOL_NAMES = ["review_submit", "stack_publish", "stack_publish_status"];
+export const MCP_HOSTED_TOOL_NAMES = MCP_TOOL_NAMES.filter((name) => !MCP_WORKSPACE_TOOL_NAMES.includes(name));
+const HOSTED_ISSUE_CREATE_DESCRIPTION = "Open a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names you in the body. Use it for the issue a pull request must have before it is opened, then put Fixes #<number> in the commit or pull request body. owner and repo name the repository. labels must already exist on the repository; an unknown one is refused with unknown_label and nothing is created. Calling it again with the same title returns the open issue it already made (created: false) when that issue is among the newest 100 open issues of the repository; an older one, or two calls at the same time, can still create a duplicate, so check the returned number before retrying after a lost response. Needs write access to the repository through your linked GitHub account and Surge installed on it.";
+export function createMergestormMcpServer(options = {}) {
+    const { config, hosted = false } = options;
+    const chatId = breezeChatId(options.chatId ?? (hosted ? null : process.env.MERGESTORM_CHAT_ID));
+    const server = new McpServer({
+        name: MCP_SERVER_NAME,
+        title: "Mergestorm",
+        version: MCP_SERVER_VERSION,
+        websiteUrl: MCP_WEBSITE_URL,
+        icons: MCP_SERVER_ICONS,
+    }, { instructions: MCP_SERVER_INSTRUCTIONS });
+    // MCP SDK + zod generic inference hits TS2589 on several schemas; keep
+    // runtime registerTool, drop the instantiation from our typecheck.
+    const registerTool = server.registerTool.bind(server);
+    const addTool = (name, toolConfig, cb) => {
+        if (hosted && MCP_WORKSPACE_TOOL_NAMES.includes(name))
+            return;
+        registerTool(name, toolConfig, cb);
+    };
+    addTool("whoami", {
+        title: "Who am I",
+        description: "Current Mergestorm API key prefix, plan, API base, and the version of this running mergestorm-mcp server.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async () => {
+        try {
+            return ok(await whoami(config, MCP_SERVER_VERSION));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("credits", {
+        title: "Credits",
+        description: "Current standard-credit usage and reset time.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async () => {
+        try {
+            return ok(await credits(config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("review_list", {
+        title: "List reviews",
+        description: "List recent Mergestorm review jobs as job envelopes.",
+        inputSchema: {
+            limit: z.number().int().min(1).max(50).optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ limit }) => {
+        try {
+            return ok(await reviewList(limit, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("review_submit", {
+        title: "Submit review",
+        description: "Submit a local git diff (or an explicit diff) as a Mergestorm review job. Does not wait by default; returns job_id immediately after submission. Explicit wait: true polls one 45s slice by default. Record job_id and loop review_wait until done. Do not pass 300; hosts drop long MCP calls. On rate_limited, wait retry_after_seconds and inspect or wait for an in-flight review before resubmitting. specialists may be security, performance, architecture, tests, data, api, frontend. governance and seam cannot be requested.",
+        inputSchema: {
+            cwd: z.string().optional(),
+            base: z.string().optional(),
+            head: z.string().optional(),
+            diff: z.string().optional(),
+            router: z.enum(["off", "standard", "max", "manual"]).optional(),
+            specialists: z.array(z.string().min(1)).max(5).optional(),
+            context: z.string().optional(),
+            context_files: z.array(z.string().min(1)).max(10).optional(),
+            thread: z.string().min(1).max(120).optional(),
+            idempotency_key: z.string().min(1).max(128).optional(),
+            wait: z.boolean().optional(),
+            timeout_s: z.number().positive().max(300).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await reviewSubmit(args, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("review_wait", {
+        title: "Wait for review",
+        description: "Read one local Mergestorm review job by the job_id that review_submit returned, as a job envelope. timeout_s: 0 reads it once without polling; otherwise it polls for one 45s slice by default (max 300s). On timeout, returns in_progress; call again with the same job_id until done. Do not pass 300; hosts drop long MCP calls. On rate_limited, wait retry_after_seconds before trying again.",
+        inputSchema: {
+            job_id: z.string().min(1),
+            timeout_s: z.number().min(0).max(300).optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ job_id, timeout_s }) => {
+        try {
+            return ok(await reviewWait(job_id, timeout_s, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("review_wait_pr", {
+        title: "Wait for GitHub PR Vortex review",
+        description: "Read the Vortex pass on a GitHub PR from the DB-only endpoint; review identity is head SHA + pass. timeout_s: 0 reads it once without polling; otherwise it polls for one 45s slice by default (max 300) and returns in_progress on timeout so you can call again, or none when no review exists for that PR and head yet (call once more; if it is none again, Vortex is not reviewing that head: comment @mergestorm-vortex review on the PR, run mg review, or push a new commit). Pass after_sha for the head you pushed and pass to read one exact attempt; when you already hold a resting envelope for that head, also pass after_pass set to its pass and keep it unchanged across retries; never replace it with the pass of an in-progress envelope, and omit after_pass for a head you hold no envelope for. With timeout_s: 0, a pass that does not exist yet returns not_found, so after a push use a positive timeout. Do not pass 300; hosts drop long MCP calls. On rate_limited, wait retry_after_seconds before trying again. After a resting pass, verify each finding; prefer the smallest correct patch; if you skip, post a PR comment starting with mergestorm-loop: dismiss.",
+        inputSchema: {
+            owner: z.string().min(1),
+            repo: z.string().min(1),
+            pr_number: z.number().int().min(1),
+            after_sha: z.string().optional(),
+            pass: z.number().int().min(1).optional(),
+            after_pass: z.number().int().min(1).optional(),
+            timeout_s: z.number().min(0).max(300).optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ owner, repo, pr_number, after_sha, pass, after_pass, timeout_s }) => {
+        try {
+            return ok(await reviewWaitPr(owner, repo, pr_number, after_sha, timeout_s, config, { pass, afterPass: after_pass, ...(chatId ? { chatId } : {}) }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("review_dismiss", {
+        title: "Dismiss Vortex findings",
+        description: "Record an audited dismissal of Vortex findings you verified are wrong or not actionable on a GitHub PR. Identity is exact: head_sha must be the PR's live head, review_id a Vortex review (Core or seam) made at that head, and finding_ids the GitHub review comment ids of that review (offdiff-<n> for a body-only finding), or scope \"review\" with no finding_ids to dismiss every finding of that review. reason must say why (at least 20 characters); evidence_url is optional. Call with preview: true first to list the review's finding ids and the seam gate without writing. The caller's linked GitHub account needs write access to the repository. A moved head, another review, an unknown id or a missing permission is refused and nothing is written. Retries are idempotent. The seam gate clears only when every finding of that integration review is dismissed; the Vortex gate at the head clears only once every Vortex Blocker (error finding) at that head is dismissed and no Vortex review of it is running (gate.vortex.cleared, else gate.vortex.message); CI and Auto land policy are unchanged. Vortex does not raise a dismissed finding again on the same diff. Never dismiss a finding you did not check. " + MCP_FINDING_DEFERRAL_RULE + STACK_WATCH_RESULT_NOTE,
+        inputSchema: {
+            owner: z.string().min(1),
+            repo: z.string().min(1),
+            pr_number: z.number().int().min(1),
+            head_sha: z.string().regex(/^[0-9a-fA-F]{40}$/),
+            review_id: z.number().int().min(1),
+            finding_ids: z.array(z.string().min(1)).max(50).optional(),
+            scope: z.enum(["findings", "review"]).optional(),
+            reason: z.string().optional(),
+            evidence_url: z.string().url().optional(),
+            preview: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await reviewDismiss(args, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    const prInput = {
+        owner: z.string().min(1),
+        repo: z.string().min(1),
+        pr_number: z.number().int().min(1),
+    };
+    addTool("review_start_pr", {
+        title: "Start Vortex review",
+        description: "Start a Vortex review of an open GitHub pull request on the user's account, at its current head. head_sha, when given, must still be the head; otherwise nothing starts and the answer names the live head. Uses one standard credit. Findings post on the pull request; read them with review_wait_pr. A review already running at that head is reported, not started twice. When this server serves a Breeze chat, the chat is woken with the result.",
+        inputSchema: { ...prInput, head_sha: z.string().regex(/^[0-9a-fA-F]{7,40}$/).optional() },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await reviewStartPr(args, config, chatId));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("review_stop_pr", {
+        title: "Stop Vortex review",
+        description: "Cancel the Vortex review running on a pull request. Starts nothing; says so when no review is running.",
+        inputSchema: prInput,
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await reviewStopPr(args, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("cyclone_start", {
+        title: "Start Cyclone job",
+        description: "Have Cyclone work on the user's repository and push the result. task fix_findings fixes the open Vortex findings on pr_number, fix_ci fixes its failing CI check (failing_check names one; default the first failing check), resolve_conflicts merges its base in and resolves the conflicts; each pushes a commit to the pull request's branch. task build builds a first working version of a new project from brief into an empty repository the user created and installed Cyclone on, then opens a pull request. Uses Cyclone credits. When the pull request has nothing to do (CI green, no conflicts, no open findings) nothing starts and the answer says why: tell the user that. Returns dispatch_id. Then wait for the job with cyclone_job until it is pushed, completed or failed, and report what it pushed. When this server serves a Breeze chat and the reply ends before the job does, the chat is woken with the result.",
+        inputSchema: {
+            task: z.enum(CYCLONE_TASKS),
+            owner: z.string().min(1),
+            repo: z.string().min(1),
+            pr_number: z.number().int().min(1).optional(),
+            failing_check: z.string().min(1).max(200).optional(),
+            brief: z.string().min(1).max(4000).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await cycloneStart(args, config, chatId));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("cyclone_job", {
+        title: "Wait for Cyclone job",
+        description: `Wait for a Cyclone job started with cyclone_start, by its dispatch_id, and read it: queued, running, pushed, completed or failed, with the outcome, detail, pushed commit and changed files. timeout_s (default ${CYCLONE_JOB_WAIT_DEFAULT_S}, max ${CYCLONE_JOB_WAIT_MAX_S}) waits until the job is pushed, completed or failed, or the time is up; 0 reads it once. While it is queued or running, call again with the same dispatch_id.`,
+        inputSchema: { dispatch_id: z.string().uuid(), timeout_s: z.number().int().min(0).max(CYCLONE_JOB_WAIT_MAX_S).optional() },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ dispatch_id, timeout_s }, extra) => {
+        try {
+            return ok(await cycloneJob(dispatch_id, config, timeout_s ?? CYCLONE_JOB_WAIT_DEFAULT_S, { signal: extra.signal }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("issue_create", {
+        title: "Open GitHub issue",
+        description: hosted
+            ? HOSTED_ISSUE_CREATE_DESCRIPTION
+            : "Open a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names you in the body. Use it for the issue a pull request must have before it is opened, then put Fixes #<number> in the commit or pull request body. Defaults to the origin repository of cwd; pass owner and repo together to name another. labels must already exist on the repository; an unknown one is refused with unknown_label and nothing is created. Calling it again with the same title returns the open issue it already made (created: false) when that issue is among the newest 100 open issues of the repository; an older one, or two calls at the same time, can still create a duplicate, so check the returned number before retrying after a lost response. Needs write access to the repository through your linked GitHub account and Surge installed on it.",
+        inputSchema: hosted ? hostedIssueCreateSchema : issueCreateSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await issueCreate(args, config, hosted ? { parseGithubOriginRepo: () => null } : {}));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("stack_adopt", {
+        title: "Adopt PR stack",
+        description: "Adopt an open GitHub PR chain into a Mergestorm stack. auto_land is boolean; auto_review, auto_patch, auto_resolve_conflicts, and auto_fix_ci accept true, false, or null, where null clears the override. Omitted auto_land seeds from auto_land_default; omitted overrides are not seeded. Never changes account settings. Adoption needs the Mergestorm Surge GitHub App on the repository. Stacks, the merge queue and Auto land run through that App; Cyclone is the auto-patch App. Without it the API returns cyclone_not_connected or cyclone_not_installed; the message, and error.reason starting with surge_ when Surge is the one to install, say which App is missing — do not retry, tell the human what the message says. Read stack_status with result.stack.id afterward to verify policy and Cyclone ownership. With 2+ PRs, adopt moves the bottom PR's GitHub base to mg-stack-<n> and parks PR3+ on an mg-park-* freeze; a 1-PR stack stays on main. Leave those bases. Never retarget the bottom back to main." + STACK_WATCH_RESULT_NOTE,
+        inputSchema: stackAdoptSchema,
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await stackAdopt(args, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("stack_list", {
+        title: "List stacks",
+        description: "List the current user's Mergestorm stacks.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async () => {
+        try {
+            return ok(await stackList(config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("stack_publish", {
+        title: "Publish branch through Mergestorm",
+        description: "Publish a local branch without any GitHub credentials. Reads the branch's commits from the local repository at cwd (never runs gh, git push or git fetch) and sends them to Mergestorm, which writes the exact commits and the branch on GitHub as the Surge App, opens a ready pull request when the branch has none, and registers the stack with Auto land on for a new stack, and Auto patch and Auto review left to the stack, repository and account settings, so Cyclone patches Vortex findings when Auto patch is on. Use it for the first publication and for every later commit to that branch. Defaults: owner and repo from origin, the checked-out branch, the repository's trunk as base, title and body from the tip commit. Two ways to publish: with no base (or trunk as base) the branch opens as a single PR onto trunk; to stack it on another branch, pass that branch as base and extend: true. A base other than trunk without extend is refused with implicit_stack. The result says which one it made. Mergestorm verifies each commit's Git tree before it moves the branch and returns the verified head and tree. It refuses with head_changed when the branch on GitHub holds work your local branch does not, base_changed when the base commit left the base branch, protected_branch for trunk and Mergestorm-owned branches, and payload_too_large beyond 20 commits, 500 changed paths, 2 MiB a file or 8 MiB in total; submodules and merge commits are not carried. replace_head replaces that exact GitHub head with the local branch and discards its commits. Safe to call again after a lost response or a failure: it resumes and never duplicates the branch, commits, pull request or stack." + STACK_WATCH_RESULT_NOTE,
+        inputSchema: stackPublishSchema,
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await stackPublish(args, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("stack_publish_status", {
+        title: "Read branch publication",
+        description: "Read how far a branch published with stack_publish got: absent, pushed (branch on GitHub, no pull request), opened (pull request open, stack not registered) or registered, with the head commit and tree on GitHub, the pull request and the stack's Auto patch and Auto land state. Changes nothing. Call it after a lost stack_publish response, then call stack_publish again to resume.",
+        inputSchema: stackPublishStatusSchema,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await stackPublishStatus(args, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("stack_set", {
+        title: "Set stack policy",
+        description: "Set per-stack automation on one owned Mergestorm stack: auto_land arms or disarms Auto land; auto_review, auto_patch, auto_resolve_conflicts, and auto_fix_ci pin Vortex auto-review, Cyclone auto-patch, Auto-resolve merge conflicts, or Auto-fix failing CI for this stack only (true or false), and null clears the pin so the stack follows the account setting again. Pass at least one key. Never changes account settings." + STACK_WATCH_RESULT_NOTE,
+        inputSchema: {
+            stack_id: z.string().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(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, async ({ stack_id, auto_land, auto_review, auto_patch, auto_resolve_conflicts, auto_fix_ci }) => {
+        try {
+            return ok(await stackSet(stack_id, {
+                ...(auto_land !== undefined ? { auto_land } : {}),
+                ...(auto_review !== undefined ? { auto_review } : {}),
+                ...(auto_patch !== undefined ? { auto_patch } : {}),
+                ...(auto_resolve_conflicts !== undefined ? { auto_resolve_conflicts } : {}),
+                ...(auto_fix_ci !== undefined ? { auto_fix_ci } : {}),
+            }, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("stack_restack", {
+        title: "Restack stack",
+        description: "Rebase one owned stack's layer branches onto their parents and push them, after the trunk or a lower layer moved. Does not merge or enqueue anything." + STACK_WATCH_RESULT_NOTE,
+        inputSchema: { stack_id: z.string().min(1) },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async ({ stack_id }) => {
+        try {
+            return ok(await stackRestack(stack_id, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("stack_enqueue", {
+        title: "Send stack to merge queue",
+        description: "Send one owned stack to the Mergestorm merge queue, which tests it and lands it when its checks pass. To restart a failed or stuck land, call stack_restack first and then this. When this server serves a Breeze chat, the chat is woken when the stack lands, is bounced or is archived." + STACK_WATCH_RESULT_NOTE,
+        inputSchema: { stack_id: z.string().min(1) },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, async ({ stack_id }) => {
+        try {
+            return ok(await stackEnqueue(stack_id, config, chatId));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("stack_status", {
+        title: "Get stack status",
+        description: "Fetch one owned Mergestorm stack with enriched checks and agent state, plus attention, issues, and currentCandidate from the same blocker rules as stack_wait, read against that stack's own merge queue. trunkBranch is mg-stack-<n> for an adopted 2+ PR stack and matches the bottom open PR's GitHub base; an mg-park-* parentBranch is a freeze. Neither is drift to fix. repair names the concrete fix for attention; landGatePending is a wait, not attention. held names a blocker no agent run clears while Vortex or Cyclone is still busy on that PR (actAfter agents_idle, waitingOn); repair then describes the fix to plan, not to apply yet. Auto land off after a merge_failed, gh_error, or ci_timeout bounce (the stack's autoLandOff reads reason bounced) returns attention with the blocker \"Auto land off after <kind> bounce\", the bounce in issues[], and a repair of kind auto_land_off: fix the cause, then turn Auto land back on or enqueue. auto_land_switched_off (returned only when the PR has no live blocker of its own): Auto land was switched off without a bounce (queue entry cancelled, or nothing left to land); do not patch, push or turn it back on yourself, tell the human. A Vortex request_changes handoff at the live head returns attention with blocker \"Vortex findings need a person\" and repair kind vortex_findings; verify its findings against the live head." + STACK_ATTENTION_NOTE + STACK_WATCH_RESULT_NOTE,
+        inputSchema: {
+            stack_id: z.string().min(1),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ stack_id }) => {
+        try {
+            return ok(await stackStatus(stack_id, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("stack_wait", {
+        title: "Wait for stack attention",
+        description: "Wait for a stack to need attention. Returns a mergestorm.stack_watch/v1 envelope; timeout_s: 0 returns one snapshot and timeout_s: 1-45 waits up to that many seconds, returning the current status (waiting or in_progress) if a snapshot was read and no attention is found. A timeout with either of those statuses is not a failure; waiting and in_progress end this slice, and the next call is stack_wait again with the same cursor. A timeout of failed means no assessment was produced. A stack that no longer exists returns status failed with watch.done true (reason not_found) and is not an error. While Cyclone or Vortex is still working on the blocked PR it returns in_progress, not attention, with busy[] naming the PR, blocker, and agent; agents carries that PR's vortexStatus, cycloneStatus, vortexReview, and busy flags. When another layer has a blocker no agent works on, attention names that blocker instead and busy[] is empty. A blocker no agent run clears (a merge conflict vs the live parent, a restack Conflict or Restack failed, a Draft PR, a seam review pending with no review running, \"Seam review stuck in reviewing, no review running\", \"Seam re-review pending, no review running\", \"Seam verdict is for an older head, no review running\", or a review skipped for review quota) is still named during that in_progress, in blocker, prNumber, headSha, and issues[], with actAfter: \"agents_idle\" and waitingOn listing the busy agents: plan the fix, and act when a snapshot after the agents finish returns attention, re-reading the blocker then. Blockers the agents can change keep blocker and actAfter null. Attention never calls for changing a PR's GitHub base. When present, repair names the concrete fix for attention (restack_conflict and merge_conflict carry liveParent, never mg-park-*). For the three stuck-seam blockers, repair kind seam_review_stuck: do not patch or push; tell the human to click Continue, which re-queues the seam review at the live head. A pending land gate (landGatePending) returns in_progress, not attention. Auto land off after a merge_failed, gh_error, or ci_timeout bounce (the stack's autoLandOff reads reason bounced) returns attention with the blocker \"Auto land off after <kind> bounce\", the bounce in issues[], and a repair of kind auto_land_off: fix the cause, then turn Auto land back on or enqueue. auto_land_switched_off (returned only when the PR has no live blocker of its own): Auto land was switched off without a bounce (queue entry cancelled, or nothing left to land); do not patch, push or turn it back on yourself, tell the human. A Vortex request_changes handoff at the live head returns attention with blocker \"Vortex findings need a person\" and repair kind vortex_findings; verify its findings against the live head." + STACK_ATTENTION_NOTE + STACK_WATCH_RESULT_NOTE,
+        inputSchema: stackWaitSchema,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args, extra) => {
+        try {
+            const payload = await stackWait(args, config, { signal: extra.signal, ...(chatId ? { chatId } : {}) });
+            return ok(payload);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("queue_status", {
+        title: "Get merge queue status",
+        description: "List live merge queue entries (position >= 1) plus the newest bounced entries (position 0) with bounceDetail for the current user, optionally filtered by stack.",
+        inputSchema: {
+            stack_id: z.string().min(1).optional(),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ stack_id }) => {
+        try {
+            return ok(await queueStatus(stack_id, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("repo_settings_get", {
+        title: "Get repository settings",
+        description: "Read the repository-level Auto patch, Auto review and Auto land values for the repositories connected to this account. Each value is true, false, or null; null means not set, so the account setting applies. Auto patch and Auto review precedence is the stack override (stack_set), then the repository value, then the account setting (settings_get). The Auto land repository value only seeds new stacks at adoption; it does not override an existing stack. Pass repo as owner/repo for one repository, or omit it for all.",
+        inputSchema: { repo: z.string().min(3).optional() },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await repoSettingsGet(args ?? {}, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("repo_settings_set", {
+        title: "Update repository settings",
+        description: "Set Auto patch (Cyclone), Auto review (Vortex) or the Auto land default for every stack and pull request in one repository connected to this account, and return the stored result. true or false sets the repository value; null clears it so the account setting applies again. A stack override (stack_set) still wins for that stack. auto_patch and auto_review apply to open stacks without an override from their next decision; nothing is cancelled or re-queued. auto_land only seeds new stacks. Only the account that connected the repository can change it. Never changes account settings.",
+        inputSchema: {
+            repo: z.string().min(3),
+            auto_patch: z.boolean().nullable().optional(),
+            auto_review: z.boolean().nullable().optional(),
+            auto_land: z.boolean().nullable().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await repoSettingsSet(args ?? {}, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("surge_setup", {
+        title: "Set up Surge CI",
+        description: "Set up Surge CI on one repository of the user's account: if Surge does not serve it yet, serve it (it joins the repositories Surge serves and gets the account's Surge settings), then open a pull request that points its workflow jobs at Surge runners and adds the merge queue batch trigger. Nothing in the repository's files changes until that pull request is merged. The answer says what happened, with the pull request link.",
+        inputSchema: { owner: z.string().min(1), repo: z.string().min(1) },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await surgeSetup(args, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("settings_get", {
+        title: "Get settings",
+        description: "Read the Bearer /api/v1/settings toggles, including auto_patch_enabled, auto_land_settle_seconds (how long Auto land waits before queueing), merge_queue_batch_enabled and merge_queue_batch_size (whether the merge queue tests several pull requests on one CI run, and how many), cyclone_connected (the Cyclone auto-patch App), and stacks_ready (whether stacks, the merge queue and Auto land can run for this account, which needs Mergestorm Surge).",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async () => {
+        try {
+            return ok(await settingsGet(config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    addTool("settings_set", {
+        title: "Update settings",
+        description: "Update writable Bearer /api/v1/settings values and return the stored result. At least one key is required. auto_land_settle_seconds is a whole number of seconds from 15 through 300; it applies to settle clocks that start after the write. merge_queue_batch_enabled turns merge queue batching on or off for the account, and merge_queue_batch_size is a whole number from 2 through 8. cyclone_connected and github_connected are read-only and cannot be set.",
+        inputSchema: {
+            ...Object.fromEntries(BEARER_SETTINGS.map((row) => [row.key,
+                ("kind" in row
+                    ? row.kind === "logins"
+                        ? z.array(z.string())
+                        : row.kind === "seconds" || row.kind === "count"
+                            ? z.number().int().min(row.min).max(row.max)
+                            : z.enum(row.values)
+                    : z.boolean()).optional(),
+            ])),
+            // Preserve these args so the handler rejects them even alongside a writable key.
+            cyclone_connected: z.unknown().optional(),
+            github_connected: z.unknown().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async (args) => {
+        try {
+            return ok(await settingsSet(args ?? {}, config));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    return server;
+}

package/dist/lib/tools/agent-request.d.ts

@@ -0,0 +1,6 @@
+import { type Config } from "mergestorm/client";
+import type { ToolPayload } from "./types.js";
+export declare function agentRequest(route: string, init: {
+    method: "GET" | "POST";
+    json?: Record<string, unknown>;
+}, cfg?: Config): Promise<ToolPayload>;

package/dist/lib/tools/agent-request.js

@@ -0,0 +1,25 @@
+import { apiFetch, CommandError, loadConfig } from "mergestorm/client";
+export async function agentRequest(route, init, cfg) {
+    const resolved = cfg ?? (await loadConfig());
+    const { status, body, retryAfterSeconds } = await apiFetch(resolved, route, { method: init.method, ...(init.json ? { json: init.json } : {}) });
+    const data = body && typeof body === "object" && !Array.isArray(body) ? body : { body };
+    if (status === 404 && data.error === undefined) {
+        throw new CommandError("This Mergestorm server does not offer that action yet.", 1, "not_found");
+    }
+    const message = typeof data.message === "string" ? data.message : `Mergestorm answered ${status}.`;
+    if (status >= 400) {
+        return {
+            summary: message,
+            isError: true,
+            data: {
+                ...data,
+                error: {
+                    code: typeof data.error === "string" ? data.error : `http_${status}`,
+                    message,
+                    ...(retryAfterSeconds !== undefined ? { retry_after_seconds: retryAfterSeconds } : {}),
+                },
+            },
+        };
+    }
+    return { summary: message, data };
+}

package/dist/lib/tools/chat-wake.d.ts

@@ -0,0 +1,21 @@
+import { type Config } from "mergestorm/client";
+export type ChatWakeTarget = {
+    kind: "vortex";
+    owner: string;
+    repo: string;
+    prNumber: number;
+    headSha: string | null;
+    minPass: number | null;
+} | {
+    kind: "stack";
+    stackId: string;
+};
+export declare function breezeChatId(value: string | null | undefined): string | null;
+export type ChatWake = {
+    id: string;
+    result: "waiting" | "existing" | "finished";
+};
+export declare const CHAT_WAKE_REVIEW_NOTE = "Keep waiting: call review_wait_pr again until the review finishes, then tell the user its verdict and findings. If your reply ends first, this chat is woken with the review's result.";
+export declare const REVIEW_START_WAIT_NOTE = "Wait for it now: call review_wait_pr for this pull request until the review finishes, then tell the user its verdict and findings. If your reply ends first, this chat is woken with the review's result.";
+export declare const CHAT_WAKE_STACK_NOTE = "If your reply ends before the stack is done, this chat is woken when the stack lands, is bounced out of the merge queue, or is archived.";
+export declare function registerChatWake(cfg: Config, chatId: string, target: ChatWakeTarget, signal?: AbortSignal): Promise<ChatWake | null>;

package/dist/lib/tools/chat-wake.js

@@ -0,0 +1,26 @@
+import { apiFetch } from "mergestorm/client";
+const CHAT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function breezeChatId(value) {
+    const trimmed = value?.trim() ?? "";
+    return CHAT_ID.test(trimmed) ? trimmed.toLowerCase() : null;
+}
+export const CHAT_WAKE_REVIEW_NOTE = "Keep waiting: call review_wait_pr again until the review finishes, then tell the user its verdict and findings. If your reply ends first, this chat is woken with the review's result.";
+export const REVIEW_START_WAIT_NOTE = "Wait for it now: call review_wait_pr for this pull request until the review finishes, then tell the user its verdict and findings. If your reply ends first, this chat is woken with the review's result.";
+export const CHAT_WAKE_STACK_NOTE = "If your reply ends before the stack is done, this chat is woken when the stack lands, is bounced out of the merge queue, or is archived.";
+export async function registerChatWake(cfg, chatId, target, signal) {
+    const json = target.kind === "vortex"
+        ? { chat_id: chatId, kind: "vortex", owner: target.owner, repo: target.repo, pr_number: target.prNumber, head_sha: target.headSha, min_pass: target.headSha ? target.minPass : null }
+        : { chat_id: chatId, kind: "stack", stack_id: target.stackId };
+    try {
+        const response = await apiFetch(cfg, "/api/v1/stacks/chat-waits", { method: "POST", json, signal, timeoutMs: 10_000 });
+        const body = response.body;
+        if (response.status !== 200 || !body || typeof body.id !== "string")
+            return null;
+        if (body.result !== "waiting" && body.result !== "existing" && body.result !== "finished")
+            return null;
+        return { id: body.id, result: body.result };
+    }
+    catch {
+        return null;
+    }
+}