driggsby 0.6.0 → 0.6.1

package/dist/dev/dev-command.js

@@ -17,6 +17,7 @@ import { DEV_IDLE_MINUTES, DEV_START_COMMAND, DEV_STOP_COMMAND } from "./dev-com
 import { startDevServers } from "./dev-servers.js";
 import { pruneDevStatesForPorts, readDevStates, removeDevState, writeDevState } from "./dev-state.js";
 import { McpBroker } from "./mcp-broker.js";
+import { toolCallLine } from "./tool-call-line.js";
 import { watchDirectory } from "./watcher.js";
 export const DEV_HOST_PORT = 4111;
 export const DEV_APP_PORT = 4112;
@@ -62,12 +63,18 @@ export async function runDev(options = {}, environment = defaultCredentialEnviro
     const session = await requireDeploySession(environment);
     await refuseSecondPreview(environment.homeDirectory, projectDirectory);
     const sdkBundle = await loadSdkBundle();
-    const broker = new McpBroker({ baseUrl: session.baseUrl, token: session.token });
+    // Retries like the production host, so the preview loads the way the
+    // deployed app would.
+    const broker = new McpBroker({ baseUrl: session.baseUrl, token: session.token, retries: true });
     const hostPort = options.hostPort ?? DEV_HOST_PORT;
     const appPort = options.appPort ?? DEV_APP_PORT;
     const pairs = options.portPairs ?? DEV_PORT_PAIRS;
     // Ephemeral ports (0, in tests) are never in use, so they never move.
     const fixedPorts = hostPort !== 0 && appPort !== 0;
+    // A call's terminal line prints only if the page that made it is still
+    // the current one and the preview is still running.
+    let documentGeneration = 0;
+    let stopping = false;
     let servers = null;
     for (let pair = 0; servers === null; pair += 1) {
         try {
@@ -76,7 +83,15 @@ export async function runDev(options = {}, environment = defaultCredentialEnviro
                 background: config.background,
                 serveDirectory: config.serveDirectory,
                 sdkBundle,
-                runToolCall: (tool, argumentsObject) => broker.runToolCall(tool, argumentsObject),
+                runToolCall: async (tool, argumentsObject) => {
+                    const started = Date.now();
+                    const calledIn = documentGeneration;
+                    const result = await broker.runToolCall(tool, argumentsObject);
+                    if (!stopping && calledIn === documentGeneration) {
+                        io.out(toolCallLine(tool, result, Date.now() - started));
+                    }
+                    return result;
+                },
                 hostPort: shiftedPort(hostPort, pair),
                 appPort: shiftedPort(appPort, pair),
             });
@@ -92,6 +107,10 @@ export async function runDev(options = {}, environment = defaultCredentialEnviro
         }
     }
     const stopWatching = watchDirectory(config.serveDirectory, () => {
+        // The app reloads in every open preview, so the old documents'
+        // pending calls go.
+        documentGeneration += 1;
+        broker.dropPending();
         servers.notifyChange();
     });
     const idleTimeoutMs = options.idleTimeoutMs ?? DEV_IDLE_TIMEOUT_MS;
@@ -110,6 +129,10 @@ export async function runDev(options = {}, environment = defaultCredentialEnviro
         return 0;
     }
     finally {
+        // No retry outlives the preview: waiting calls are answered, and no
+        // new request starts.
+        stopping = true;
+        broker.close();
         idle.cancel();
         stopWatching();
         // The record goes before the ports are freed, so a dev starting the

package/dist/dev/host-page.js

@@ -217,7 +217,14 @@ export const HOST_PAGE_JS = [
     "  );",
     "}",
     "",
+    "// Watch ids restart in every fresh document, so a result minted for the",
+    "// document before a reload must never reach the new one: same id,",
+    "// different watch. Raised on every ready and every new version, like",
+    "// the production host's document generation.",
+    "let generation = 0;",
+    "",
     "async function runToolCall(id, tool, params) {",
+    "  const calledIn = generation;",
     "  const body = JSON.stringify({ tool: tool, arguments: params });",
     "  let payload = null;",
     "  try {",
@@ -230,6 +237,9 @@ export const HOST_PAGE_JS = [
     "  } catch (error) {",
     "    payload = null;",
     "  }",
+    "  if (calledIn !== generation) {",
+    "    return;",
+    "  }",
     "  if (payload && payload.ok === true) {",
     '    postToApp({ protocol: PROTOCOL, type: "result", id: id, result: payload.result });',
     "    return;",
@@ -238,7 +248,14 @@ export const HOST_PAGE_JS = [
     "    payload && payload.error && typeof payload.error.message === \"string\"",
     "      ? payload.error.message",
     '      : "We couldn\'t run that just now. Try again in a moment.";',
-    '  postToApp({ protocol: PROTOCOL, type: "result", id: id, error: { message: message } });',
+    "  const failure = { message: message };",
+    "  // Like the production host: only the service's own failure kinds reach",
+    "  // the app's onError; anything else in the field is dropped.",
+    "  const kind = payload && payload.error ? payload.error.kind : undefined;",
+    '  if (kind === "timeout" || kind === "unavailable" || kind === "busy" || kind === "rate_limited") {',
+    "    failure.kind = kind;",
+    "  }",
+    '  postToApp({ protocol: PROTOCOL, type: "result", id: id, error: failure });',
     "}",
     "",
     'window.addEventListener("message", (event) => {',
@@ -247,6 +264,7 @@ export const HOST_PAGE_JS = [
     "  }",
     "  const data = event.data;",
     '  if (data.type === "ready") {',
+    "    generation += 1;",
     "    const hello = { protocol: PROTOCOL, type: \"hello\" };",
     '    if (appRoute !== "") {',
     "      hello.route = appRoute;",
@@ -292,6 +310,7 @@ export const HOST_PAGE_JS = [
     "// new-version, exactly as it would after a deploy.",
     'const events = new EventSource("/events");',
     'events.addEventListener("change", () => {',
+    "  generation += 1;",
     '  postToApp({ protocol: PROTOCOL, type: "new-version" });',
     "});",
     "",

package/dist/dev/mcp-broker.js

@@ -1,12 +1,15 @@
 // The tool-call broker: the only place `driggsby dev` talks to Driggsby.
 // It holds the app token in the CLI process (never in page HTML), calls the
 // Driggsby MCP endpoint, and hands the host page a plain
-// { ok, result | error } envelope. Bounds mirror the production host: a few
-// calls in flight, a bounded queue, and a hard per-call timeout, so a
-// buggy app can hammer its own laptop but never Driggsby.
+// { ok, result | error } envelope. Bounds mirror the production host: two
+// calls in flight, a bounded queue, a hard per-call timeout, and (for the
+// preview) the host's retries by kind of failure, so a preview loads the
+// way the deployed app would and a buggy app can hammer its own laptop but
+// never Driggsby.
 import { capForTerminal, sanitizeForTerminal } from "../terminal-text.js";
 import { GENERIC_TOOL_TROUBLE } from "./dev-servers.js";
-export const MAX_IN_FLIGHT_CALLS = 4;
+import { httpRetryHint, refusalKind, refusalRetryHint, RETRY_LIMITS, retryDelayMs, } from "./retry-policy.js";
+export const MAX_IN_FLIGHT_CALLS = 2;
 export const MAX_QUEUED_CALLS = 64;
 export const TOOL_CALL_TIMEOUT_MS = 30_000;
 // Server-supplied error text is untrusted; it reaches the page's console,
@@ -23,22 +26,44 @@ const DEFAULT_REASON = "Rendering this data in the developer's own Driggsby app
 export class McpBroker {
     options;
     queue = [];
+    // Calls waiting out a retry delay, outside the queue until it's over.
+    waiting = new Set();
     inFlight = 0;
     nextRequestId = 1;
+    closed = false;
+    epoch = 0;
     constructor(options) {
         this.options = options;
     }
     async runToolCall(tool, argumentsObject) {
-        if (this.queue.length >= MAX_QUEUED_CALLS) {
+        if (this.closed || this.queue.length + this.waiting.size >= MAX_QUEUED_CALLS) {
             return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
         }
         return await new Promise((resolve, reject) => {
-            this.queue.push({ tool, argumentsObject, resolve, reject });
+            this.queue.push({ tool, argumentsObject, attempt: 0, epoch: this.epoch, resolve, reject });
             this.pump();
         });
     }
+    // The page reloaded (a file changed): calls still queued or waiting to
+    // retry belong to the old document, so they're answered now instead of
+    // run, like the production host clearing its queue. A call already in
+    // flight gets its answer but is never retried.
+    dropPending() {
+        this.epoch += 1;
+        for (const call of [...this.queue, ...this.waiting]) {
+            call.resolve({ ok: false, error: { message: GENERIC_TOOL_TROUBLE } });
+        }
+        this.queue.length = 0;
+        this.waiting.clear();
+    }
+    // The preview is stopping: pending calls are answered and no new
+    // request starts.
+    close() {
+        this.closed = true;
+        this.dropPending();
+    }
     pump() {
-        while (this.inFlight < MAX_IN_FLIGHT_CALLS) {
+        while (!this.closed && this.inFlight < MAX_IN_FLIGHT_CALLS) {
             const call = this.queue.shift();
             if (call === undefined) {
                 return;
@@ -51,18 +76,44 @@ export class McpBroker {
         }
     }
     async execute(call) {
-        let result;
+        let outcome;
         try {
-            result = await this.callMcp(call.tool, call.argumentsObject);
+            outcome = await this.callMcp(call.tool, call.argumentsObject);
         }
         catch (error) {
             if (this.options.transportErrors === "throw") {
                 call.reject(error);
                 return;
             }
-            result = { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
+            outcome = { ...failed(GENERIC_TOOL_TROUBLE), retry: { kind: "transport", afterMs: null } };
+        }
+        const current = !this.closed && call.epoch === this.epoch;
+        const retry = this.options.retries === true && current ? outcome.retry : null;
+        if (retry !== null && call.attempt < RETRY_LIMITS[retry.kind]) {
+            this.retryLater(call, retry, outcome.result);
+            return;
         }
-        call.resolve(result);
+        call.resolve(outcome.result);
+    }
+    // A call waiting to retry gives up its slot and rejoins the back of the
+    // queue when its wait is over. If the queue is full by then, it keeps the
+    // answer it has; if the pending calls were dropped or the broker closed
+    // meanwhile, that already answered it.
+    retryLater(call, retry, answer) {
+        const delay = retryDelayMs(call.attempt, retry.afterMs, this.options.random);
+        call.attempt += 1;
+        this.waiting.add(call);
+        void (this.options.wait ?? sleep)(delay).then(() => {
+            if (!this.waiting.delete(call)) {
+                return;
+            }
+            if (this.queue.length >= MAX_QUEUED_CALLS) {
+                call.resolve(answer);
+                return;
+            }
+            this.queue.push(call);
+            this.pump();
+        });
     }
     async callMcp(tool, argumentsObject) {
         const toolArguments = { ...argumentsObject };
@@ -72,68 +123,98 @@ export class McpBroker {
         const requestId = this.nextRequestId;
         this.nextRequestId += 1;
         const doFetch = this.options.fetchImplementation ?? fetch;
-        // Bare headers on purpose: the Driggsby endpoint refuses anything that
-        // looks like a browser call (an Origin or Sec-Fetch-Site header), and
-        // Node's fetch sends neither on its own.
-        const response = await doFetch(new URL("/mcp", this.options.baseUrl), {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${this.options.token}`,
-            },
-            body: JSON.stringify({
-                jsonrpc: "2.0",
-                id: requestId,
-                method: "tools/call",
-                params: { name: tool, arguments: toolArguments },
-            }),
-            // The bearer token must never travel to a redirect target, and tool
-            // results must never come from one either.
-            redirect: "error",
-            signal: AbortSignal.timeout(this.options.timeoutMs ?? TOOL_CALL_TIMEOUT_MS),
-        });
+        const signal = AbortSignal.timeout(this.options.timeoutMs ?? TOOL_CALL_TIMEOUT_MS);
+        // Our own timeout is retried once, like a server timeout; any other
+        // failure to get an answer is retried as a failed request.
+        const cutOff = () => ({ kind: signal.aborted ? "timeout" : "transport", afterMs: null });
+        let response;
+        try {
+            // Bare headers on purpose: the Driggsby endpoint refuses anything that
+            // looks like a browser call (an Origin or Sec-Fetch-Site header), and
+            // Node's fetch sends neither on its own.
+            response = await doFetch(new URL("/mcp", this.options.baseUrl), {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.options.token}`,
+                },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: requestId,
+                    method: "tools/call",
+                    params: { name: tool, arguments: toolArguments },
+                }),
+                // The bearer token must never travel to a redirect target, and tool
+                // results must never come from one either.
+                redirect: "error",
+                signal,
+            });
+        }
+        catch (error) {
+            if (this.options.transportErrors === "throw") {
+                throw error;
+            }
+            return { ...failed(GENERIC_TOOL_TROUBLE), retry: cutOff() };
+        }
         if (response.status === 401) {
-            return { ok: false, error: { message: this.options.signInAgainMessage ?? SIGN_IN_AGAIN_MESSAGE } };
+            return failed(this.options.signInAgainMessage ?? SIGN_IN_AGAIN_MESSAGE);
         }
         if (!response.ok) {
-            return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
+            return { ...failed(GENERIC_TOOL_TROUBLE), retry: httpRetryHint(response.status, response.headers.get("Retry-After")) };
         }
         let payload;
         try {
             payload = await response.json();
         }
-        catch {
-            return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
+        catch (error) {
+            // A body that isn't JSON would come back the same; a read cut off by
+            // the timeout or a dropped connection may not.
+            return { ...failed(GENERIC_TOOL_TROUBLE), retry: error instanceof SyntaxError ? null : cutOff() };
         }
         return interpretJsonRpc(payload);
     }
 }
+function failed(message) {
+    return { result: { ok: false, error: { message } }, retry: null };
+}
+// Unref'd: a retry's wait never keeps a stopped preview's process alive.
+async function sleep(milliseconds) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, milliseconds).unref();
+    });
+}
 // The Driggsby MCP endpoint answers in JSON-RPC 2.0. Three shapes matter:
 // a protocol-level error ({ error: { message } }), a tool-level refusal
 // (result.isError true, message in content[0].text), and success
-// (result.structuredContent is the data the app's watch callback gets).
+// (result.structuredContent is the data the app's watch callback gets). A
+// refusal the service marks retryable carries its kind and retry hint in
+// structuredContent.
 function interpretJsonRpc(payload) {
     if (typeof payload !== "object" || payload === null) {
-        return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
+        return failed(GENERIC_TOOL_TROUBLE);
     }
     const envelope = payload;
     const error = envelope.error;
     if (typeof error === "object" && error !== null) {
         const message = error.message;
-        return {
-            ok: false,
-            error: { message: typeof message === "string" ? capMessage(message) : GENERIC_TOOL_TROUBLE },
-        };
+        return failed(typeof message === "string" ? capMessage(message) : GENERIC_TOOL_TROUBLE);
     }
     const result = envelope.result;
     if (typeof result !== "object" || result === null) {
-        return { ok: false, error: { message: GENERIC_TOOL_TROUBLE } };
+        return failed(GENERIC_TOOL_TROUBLE);
     }
     const resultRecord = result;
     if (resultRecord.isError === true) {
-        return { ok: false, error: { message: toolRefusalMessage(resultRecord) } };
+        // A known kind reaches the app even when it isn't worth retrying (a
+        // daily limit), as the production host forwards it.
+        const kind = refusalKind(resultRecord.structuredContent);
+        const message = toolRefusalMessage(resultRecord);
+        return {
+            result: { ok: false, error: kind === null ? { message } : { message, kind } },
+            retry: refusalRetryHint(resultRecord.structuredContent),
+        };
     }
-    return { ok: true, result: resultRecord.structuredContent ?? null };
+    return { result: { ok: true, result: resultRecord.structuredContent ?? null }, retry: null };
 }
 function toolRefusalMessage(resultRecord) {
     const content = resultRecord.content;

package/dist/dev/retry-policy.js

@@ -0,0 +1,58 @@
+// How `driggsby dev` retries a failed tool call: the same policy the
+// Driggsby console's dashboard host uses, so a preview loads (or fails)
+// the way the deployed app would. A timeout is retried once (an immediate
+// retry of a timeout usually times out again); a busy or unavailable
+// answer, a rate limit, and a failed request up to three times; a wrong
+// input never. The wait backs off with full jitter and is never shorter
+// than the server asked.
+export const RETRY_LIMITS = {
+    timeout: 1,
+    unavailable: 3,
+    busy: 3,
+    rate_limited: 3,
+    transport: 3,
+};
+// The failure kinds the Driggsby service names. Only these reach an app's
+// onError; anything else in a kind field is dropped.
+export const SERVICE_FAILURE_KINDS = new Set(["timeout", "unavailable", "busy", "rate_limited"]);
+const BACKOFF_BASE_MS = 1_000;
+const BACKOFF_CAP_MS = 8_000;
+// A server-provided wait is honored, but never beyond this.
+const MAX_RETRY_AFTER_MS = 60_000;
+// Full jitter: a random wait up to an exponentially growing ceiling, and
+// never sooner than the server asked.
+export function retryDelayMs(attempt, afterMs, random = Math.random) {
+    const ceiling = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
+    const jitter = Math.floor(random() * ceiling);
+    const serverWait = afterMs === null ? 0 : Math.min(Math.max(afterMs, 0), MAX_RETRY_AFTER_MS);
+    return Math.max(serverWait, jitter);
+}
+// The service's named kind of a refused tool call (structuredContent.kind),
+// or null for anything else.
+export function refusalKind(structuredContent) {
+    if (typeof structuredContent !== "object" || structuredContent === null) {
+        return null;
+    }
+    const kind = structuredContent.kind;
+    return typeof kind === "string" && SERVICE_FAILURE_KINDS.has(kind) ? kind : null;
+}
+// A retryable refusal in an MCP tool result: a named kind, retryable true,
+// and an optional retry_after_ms in structuredContent.
+export function refusalRetryHint(structuredContent) {
+    const kind = refusalKind(structuredContent);
+    if (kind === null || structuredContent.retryable !== true) {
+        return null;
+    }
+    const after = structuredContent.retry_after_ms;
+    return { kind, afterMs: typeof after === "number" && Number.isFinite(after) ? after : null };
+}
+// An HTTP failure that can pass on its own: a request timeout (408), a
+// limit (429), or a server error (5xx). Any other status would fail the
+// same way again.
+export function httpRetryHint(status, retryAfterHeader) {
+    if (status !== 408 && status !== 429 && status < 500) {
+        return null;
+    }
+    const seconds = retryAfterHeader === null ? Number.NaN : Number.parseInt(retryAfterHeader, 10);
+    return { kind: "transport", afterMs: Number.isFinite(seconds) ? seconds * 1_000 : null };
+}

package/dist/dev/tool-call-line.js

@@ -0,0 +1,17 @@
+// The terminal line `driggsby dev` prints for each tool call the preview
+// makes, after any retries: a check and the time it took, or a cross and
+// the reason. A developer (or their agent) sees a failing watch in the
+// terminal, not only in the page. The tool name passed the app allowlist
+// before the call ran, and the broker has already sanitized the message;
+// here it's capped shorter and wrapped, its continuation lines indented
+// deeper than the CLI's own command suggestions, so server text can't pass
+// for one.
+import { capForTerminal, wrapProse } from "../terminal-text.js";
+const MAX_LINE_MESSAGE_CHARS = 240;
+export function toolCallLine(tool, result, elapsedMs) {
+    if (result.ok) {
+        return `✓ ${tool} ${(elapsedMs / 1000).toFixed(2)}s\n`;
+    }
+    const wrapped = wrapProse(`✗ ${tool}: ${capForTerminal(result.error.message, MAX_LINE_MESSAGE_CHARS)}`, 72);
+    return `${wrapped.split("\n").join("\n    ")}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driggsby",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Set up and build on Driggsby, the MCP server for personal finance.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@driggsby/deploy": "0.6.0",
-    "@driggsby/sdk": "0.6.0"
+    "@driggsby/deploy": "0.6.1",
+    "@driggsby/sdk": "0.6.1"
   }
 }