mergestorm-mcp 0.2.5 → 0.2.6

package/README.md

@@ -24,7 +24,7 @@ The stack tools expose reads plus one scoped policy write:
 - `stack_status({ stack_id })` returns one owned 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. It returns a structured `stack_not_found` or `rate_limited` error.
 - `stack_wait({ stack_id, timeout_s?, enrolled_head_sha?, after_finished_at?, bounce_id? })` waits for a stack or queue state change and returns the latest snapshots. `timeout_s: 0` returns one snapshot; a positive timeout after a snapshot with no attention returns the current `waiting` or `in_progress` status with selectors to use for the next call. An unread deadline returns `failed`. While Cyclone or Vortex is still working on the blocked PR, `stack_wait` and `stack_status` return `in_progress` instead of `attention`, with `busy[]` naming the PR, blocker, and agent, and `agents` carrying that PR's `vortexStatus`, `cycloneStatus`, `vortexReview`, and busy flags. A nonempty `busy[]` means wait. A queued Vortex run holds for at most 15 minutes, `seam_pending` alone does not hold, and reviewing or patching holds until the run finishes or its lease or check run is cleared. 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) is still named during that `in_progress`, in `blocker`, `prNumber`, `headSha`, and `issues[]`, with `actAfter: "agents_idle"` and `waitingOn` listing the busy agents; act when a snapshot after the agents finish returns `attention`, re-reading the blocker then. `repair` is included when a concrete repair hint is available. Blockers the agents can change keep `blocker` and `actAfter` null. If a hold looks stuck, refresh `stack_status` and tell the human.
 
-Agents that cannot hold a long turn open should not poll `stack_wait` inside their turn. The server instructions tell them to run `mg stack watch <stack-id>` from the `mergestorm` CLI as a background command, notify on output matching `MS-WATCH (ATTENTION|LANDED)`, and end the turn. The watcher loops the same stack wait against the Mergestorm API with the cursor, stays silent while the stack is waiting or in progress, and exits on attention (exit 3), a failed read that failed again on retry (exit 3), or a finished watch (exit 0). On wake the agent reads `stack_status` once, fixes the blocker, pushes, and restarts the watcher with `--head <pushed-sha>`. The stack is still not done until it lands. Agents are told not to subscribe to GitHub events to wait on a stack.
+Agents that cannot hold a long turn open should not poll `stack_wait` inside their turn. The server instructions tell them to run `mg stack watch <stack-id>` from the `mergestorm` CLI as a background command, notify on output matching `MS-WATCH (ATTENTION|LANDED)`, and end the turn. The watcher loops the same stack wait against the Mergestorm API with the cursor, stays silent while the stack is waiting or in progress, and exits on attention (exit 3), a failed read that failed again on retry (exit 3), or a finished watch (exit 0). Every `watch.next` carries that command as `watch.next.background`, and every not-done `watch.message` offers it before the next `stack_wait` call. On wake the agent reads `stack_status` once, fixes the blocker, pushes, and restarts the watcher with `--head <pushed-sha>`. The stack is still not done until it lands. Agents are told not to subscribe to GitHub events to wait on a stack.
 
 Auth is `MERGESTORM_API_KEY`, then `~/.mergestorm/config.json` (same as `mg`).
 

package/dist/index.js

@@ -37,6 +37,17 @@ var MCP_WEBSITE_URL = SITE;
 
 // src/tools/credits.ts
 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 `
+Surge: ${wallet}`;
+  return `
+Surge: ${formatMinutes(surge.usedMinutes)} of ${formatMinutes(surge.includedMinutes)} included min this period \xB7 ${wallet}`;
+}
 async function credits(cfg) {
   const resolved = cfg ?? await loadConfig();
   const me = await getMe(resolved);
@@ -53,9 +64,10 @@ async function credits(cfg) {
   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 ? "" : ` \xB7 ${bonusRemaining} bonus remaining`;
   return {
-    summary: remaining == null ? `${standard.used} used \xB7 unlimited${bonusSummary}` : `${standard.used} used \xB7 ${remaining} remaining${bonusSummary}`,
+    summary: remaining == null ? `${standard.used} used \xB7 unlimited${bonusSummary}${surgeSummary(surge)}` : `${standard.used} used \xB7 ${remaining} remaining${bonusSummary}${surgeSummary(surge)}`,
     data: {
       usage: me.usage,
       resets_at: me.resets_at ?? null
@@ -175,6 +187,7 @@ import {
   pollStackWatch,
   StackWatchError,
   StackWatchTimeoutError,
+  stackWatchBackgroundCommand,
   stackWatchObligation
 } from "mergestorm/client";
 import { z } from "zod";
@@ -216,7 +229,7 @@ function stackWaitStatusLine(envelope) {
     ...envelope.cursor.afterFinishedAt !== void 0 ? [`after_finished_at ${JSON.stringify(envelope.cursor.afterFinishedAt)}`] : [],
     ...envelope.cursor.bounceId !== void 0 ? [`bounce_id ${JSON.stringify(envelope.cursor.bounceId)}`] : []
   ];
-  return `${base} \xB7 watch not finished: call stack_wait again with timeout_s 45 and the same cursor: ${selectors.join(", ")}`;
+  return `${base} \xB7 watch not finished: run ${stackWatchBackgroundCommand(envelope.stackId)} as a background command and end your turn, or call stack_wait again with timeout_s 45 and the same cursor: ${selectors.join(", ")}`;
 }
 async function stackWait(input, cfg, deps = {}) {
   const args = z.object(stackWaitSchema).parse(input);
@@ -1133,14 +1146,14 @@ var MCP_STACK_WATCH_INSTRUCTIONS = [
 
 // src/server.ts
 var MCP_SERVER_NAME = "mergestorm";
-var MCP_SERVER_VERSION = "0.2.5";
+var MCP_SERVER_VERSION = "0.2.6";
 var MCP_SERVER_INSTRUCTIONS = [
   MCP_STACK_DONE_INSTRUCTIONS,
   MCP_PR_LOOP_INSTRUCTIONS,
   MCP_STACK_BASE_INSTRUCTIONS,
   MCP_STACK_WATCH_INSTRUCTIONS
 ].join("\n\n");
-var STACK_WATCH_RESULT_NOTE = ' The result carries watch {done, until: "landed", reason, next, message}: while watch.done is false the stack is not landed and your task is not done; call stack_wait with watch.next.args.';
+var STACK_WATCH_RESULT_NOTE = ' The result carries watch {done, until: "landed", reason, next, message}: while watch.done is false the stack is not landed and your task is not done; call stack_wait with watch.next.args, or run watch.next.background as a background command and end your turn.';
 function stripNulls(value) {
   if (Array.isArray(value)) {
     return value.map((item) => stripNulls(item));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm-mcp",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Mergestorm MCP server — identity, review, and read-only stack tools over stdio",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "mergestorm": "0.3.30",
+    "mergestorm": "0.3.31",
     "zod": "^3.24.2"
   },
   "devDependencies": {