@vibeframe/cli 0.106.9 → 0.107.1

package/dist/tools/_shared/long-poll.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @module tools/_shared/long-poll
+ * @description Long-poll promotion for long-running MCP tool calls.
+ *
+ * MCP hosts (notably Claude Desktop) time out tool calls after a minute or
+ * two, while `build`/`render` legitimately run for many minutes. The fix:
+ * run the work normally, and if it finishes inside the synchronous window
+ * return its result untouched — byte-identical to the unwrapped call, and no
+ * job record is ever written. If the window elapses first, persist a local
+ * {@link JobRecord} (jobType "build"/"render", provider "local"), return a
+ * `promoted` envelope immediately, and let the work continue in-process; the
+ * settle handlers write the terminal record that `status_job` then serves.
+ *
+ * CLI surfaces never reach this module — callers gate on
+ * `ctx.surface === "mcp"`.
+ */
+import type { ToolExecuteResult } from "../define-tool.js";
+export interface LocalJobUpdate {
+    /** 0-100 when a percentage is known; otherwise omit. */
+    progress?: number;
+    /** Pipeline stage label, e.g. "assets" | "compose" | "render". */
+    stage?: string;
+    message?: string;
+}
+export interface PromotionOptions {
+    jobType: "build" | "render";
+    /** Absolute project dir — the job record lands in `<projectDir>/.vibeframe/jobs/`. */
+    projectDir: string;
+    /** CLI equivalent of this invocation, stored on the record for retryWith. */
+    command: string;
+    /** Synchronous window before promotion. Default 45s; see resolveWindowMs. */
+    windowMs?: number;
+    /** Heartbeat cadence once promoted. Default 10s. */
+    heartbeatMs?: number;
+    now?: () => Date;
+}
+/**
+ * Resolve the promotion window. `VIBE_MCP_PROMOTE_AFTER_MS` overrides the
+ * default; `"off"` or `"0"` disables promotion entirely (pure synchronous
+ * behavior — the escape hatch for hosts with generous timeouts).
+ */
+export declare function resolveWindowMs(optionMs?: number): number | null;
+/**
+ * Run `work`; promote to a polled background job if it outlives the window.
+ *
+ * The `report` callback passed to `work` is safe to call at any time: before
+ * promotion it only buffers the latest update (callers typically also feed
+ * `ctx.onProgress` for MCP progress notifications); after promotion it
+ * coalesces updates into the job record on disk.
+ */
+export declare function runWithMcpPromotion(work: (report: (update: LocalJobUpdate) => void) => Promise<ToolExecuteResult>, opts: PromotionOptions): Promise<ToolExecuteResult>;

package/dist/tools/_shared/long-poll.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/adapters/mcp.d.ts

@@ -22,12 +22,41 @@ export interface McpTool {
     description: string;
     inputSchema: McpInputSchema;
 }
-export type McpDispatcher = (name: string, args: Record<string, unknown>) => Promise<{
+/** Per-call extras forwarded by the MCP server request handler. */
+export interface McpCallExtra {
+    /**
+     * Raw progress sink — typically sends an MCP `notifications/progress` for
+     * the request's progressToken. The dispatcher wraps it with throttling,
+     * monotonicity, and post-completion cutoff before exposing it to tools.
+     */
+    onProgress?: (update: {
+        progress: number;
+        total?: number;
+        message?: string;
+    }) => void;
+}
+export type McpDispatcher = (name: string, args: Record<string, unknown>, extra?: McpCallExtra) => Promise<{
     content: Array<{
         type: "text";
         text: string;
     }>;
 }>;
+export interface ProgressSink {
+    send: (update: {
+        progress?: number;
+        total?: number;
+        message?: string;
+    }) => void;
+    close: () => void;
+}
+/**
+ * Wrap a raw progress callback with the guarantees the MCP spec expects:
+ * `progress` increases monotonically per token, updates are throttled to at
+ * most one per `minIntervalMs` (the first always passes), and nothing is
+ * emitted after `close()` — progress notifications must stop once the
+ * request's result has been sent.
+ */
+export declare function makeProgressSink(raw: McpCallExtra["onProgress"], minIntervalMs?: number): ProgressSink;
 /** Filter manifest by `surfaces.mcp` (default: included) and project to MCP tool shape. */
 export declare function manifestToMcpTools(manifest: readonly ToolDefinition[]): McpTool[];
 /** Build the dispatcher used by `handleToolCall` in the MCP server. */

package/dist/tools/adapters/mcp.js

@@ -140,7 +140,16 @@ async function withCapturedStdout(fn) {
 `;
   };
   process.stdout.write = (chunk, encodingOrCallback, callback) => {
-    captured += formatStdoutChunk(chunk, encodingOrCallback);
+    const text = formatStdoutChunk(chunk, encodingOrCallback);
+    if (text.startsWith("{") && text.includes('"jsonrpc":"2.0"')) {
+      return originalWrite.call(
+        process.stdout,
+        chunk,
+        encodingOrCallback,
+        callback
+      );
+    }
+    captured += text;
     invokeWriteCallback(encodingOrCallback, callback);
     return true;
   };
@@ -159,6 +168,32 @@ async function withCapturedStdout(fn) {
     }
   }
 }
+function makeProgressSink(raw, minIntervalMs = 1e3) {
+  if (!raw) {
+    return { send: () => void 0, close: () => void 0 };
+  }
+  let closed = false;
+  let lastSentAt = 0;
+  let lastProgress = 0;
+  return {
+    send: (update) => {
+      if (closed) return;
+      const now = Date.now();
+      if (lastSentAt !== 0 && now - lastSentAt < minIntervalMs) return;
+      lastSentAt = now;
+      const progress = update.progress !== void 0 && update.progress > lastProgress ? update.progress : lastProgress + 1;
+      lastProgress = progress;
+      raw({
+        progress,
+        ...update.total !== void 0 ? { total: update.total } : {},
+        ...update.message ? { message: update.message } : {}
+      });
+    },
+    close: () => {
+      closed = true;
+    }
+  };
+}
 function formatZodError(err) {
   const missing = err.issues.filter((i) => {
     if (i.code !== "invalid_type") return false;
@@ -193,7 +228,7 @@ function buildMcpDispatcher(manifest) {
       byName.set(t.name, t);
     }
   }
-  return async (name, args) => {
+  return async (name, args, extra) => {
     const tool = byName.get(name);
     if (!tool) {
       return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
@@ -204,11 +239,13 @@ function buildMcpDispatcher(manifest) {
         content: [{ type: "text", text: `${name} failed: ${formatZodError(parsed.error)}` }]
       };
     }
+    const sink = makeProgressSink(extra?.onProgress);
     try {
       const result = await withCapturedStdout(
         () => tool.execute(parsed.data, {
           workingDirectory: process.cwd(),
-          surface: "mcp"
+          surface: "mcp",
+          ...extra?.onProgress ? { onProgress: sink.send } : {}
         })
       );
       const text = result.success ? JSON.stringify({ success: true, ...result.data }) : result.data ? JSON.stringify({
@@ -220,10 +257,13 @@ function buildMcpDispatcher(manifest) {
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
       return { content: [{ type: "text", text: `${name} threw: ${msg}` }] };
+    } finally {
+      sink.close();
     }
   };
 }
 export {
   buildMcpDispatcher,
+  makeProgressSink,
   manifestToMcpTools
 };

package/dist/tools/adapters/mcp.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/define-tool.d.ts

@@ -37,6 +37,18 @@ export interface ExecuteContext {
         projectPath: string | null;
         setProjectPath(path: string): void;
     };
+    /**
+     * Optional progress sink. The MCP adapter wires this to MCP
+     * `notifications/progress` when the client supplied a progressToken;
+     * CLI/Agent surfaces leave it undefined. Omitting `progress` advances an
+     * internal monotonic counter; the adapter also throttles and enforces
+     * monotonicity defensively.
+     */
+    onProgress?: (update: {
+        progress?: number;
+        total?: number;
+        message?: string;
+    }) => void;
 }
 export interface ToolExecuteResult {
     success: boolean;