@guuey/mcp-apps-host 0.22.0 → 0.22.1

package/dist/action.d.ts

@@ -101,6 +101,15 @@ export interface CreateMcpUiActionRelayDeps {
      * treated as unavailable.
      */
     callTool: (uri: string, name: string, args: McpToolStructuredContent | undefined) => Promise<unknown>;
+    /**
+     * Fired ONCE when a card locator's `ggui_runtime_pull` circuit OPENS
+     * (guuey#1249 item 4) — the live session is unrestorable (N consecutive
+     * both-doors-gone pulls). The complement to leg 1's storm-break: the host
+     * surfaces a visible "this session ended — start a new chat" state and drops
+     * the stale thread, so a tripped circuit is never a silent frozen card.
+     * Optional: a host that only wants the storm bounded omits it.
+     */
+    onSessionUnrestorable?: (resourceUri: string) => void;
 }
 /** The request shape a mounted card's `onCallTool` bridge produces. */
 export interface UiActionRequest {
@@ -109,10 +118,37 @@ export interface UiActionRequest {
     name: string;
     arguments?: McpToolStructuredContent;
 }
+/**
+ * Consecutive `unavailable` pull results (per card locator) that OPEN the
+ * circuit (guuey#1235 leg 1). At the #1233 storm's ~12-18 pulls/min a 3-strike
+ * trip bounds the hammer in ~10-15s; a single good pull resets it, so a
+ * transient blip never trips.
+ */
+export declare const PULL_CIRCUIT_THRESHOLD = 3;
+/**
+ * Logged ONCE when a locator's pull circuit opens — the bounded-storm marker
+ * (sentry's readability ask; the #1233 next-incident is scopeable from it).
+ */
+export declare const UI_ACTION_PULL_CIRCUIT_OPEN = "UI_ACTION_PULL_CIRCUIT_OPEN";
 /**
  * Assemble the sandbox-facing action relay from a host transport. The
  * returned function is shaped for an `onCallTool` bridge: it always
  * resolves (never rejects), answering in-band.
+ *
+ * guuey#1235 leg 1 — the `ggui_runtime_pull` CIRCUIT BREAK. A card whose live
+ * session died keeps auto-polling on its own interval; each pull `tools/call`
+ * 404s at the pod door → `unavailable` → the sandbox polls again, hammering the
+ * door indefinitely (the #1233 prod storm: 57+ over 15 min). After
+ * {@link PULL_CIRCUIT_THRESHOLD} CONSECUTIVE `unavailable` pull results for a
+ * locator, the circuit OPENS: the relay stops calling the transport for that
+ * locator's pull (fail-fast, no network) — the server storm is bounded. A
+ * single non-`unavailable` pull result CLOSES it (the session recovered). Only
+ * the pull rung is counted — a failed user gesture (`submit_action`) or token
+ * refresh must never trip the auto-poll break, and never opens another rung.
+ *
+ * The complement — telling the USER the session is unrestorable so a tripped
+ * circuit is not a silent freeze — is the `onSessionUnrestorable` signal
+ * (guuey#1249 item 4); this leg only bounds the hammer.
  */
 export declare function createMcpUiActionRelay(deps: CreateMcpUiActionRelayDeps): (request: UiActionRequest) => Promise<McpToolCallResult>;
 //# sourceMappingURL=action.d.ts.map

package/dist/action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,CAC3C;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CACnB,CAAC;CACH,CAAC;AAEN;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAI9C,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAEvD,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,2CACG,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,iBAAiB,CAK7D;AAkCD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAgB9E;AAED,iFAAiF;AACjF,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,EAAE,CACR,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,wBAAwB,GAAG,SAAS,KACvC,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,wBAAwB,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,0BAA0B,GAC/B,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAa1D"}
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,CAC3C;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CACnB,CAAC;CACH,CAAC;AAEN;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAI9C,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAEvD,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,2CACG,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,iBAAiB,CAK7D;AAkCD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAgB9E;AAED,iFAAiF;AACjF,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,EAAE,CACR,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,wBAAwB,GAAG,SAAS,KACvC,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,wBAAwB,CAAC;CACtC;AAKD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,2BAA2B,gCAAgC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,0BAA0B,GAC/B,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAmD1D"}

package/dist/action.js

@@ -113,26 +113,91 @@ export function asToolCallResult(value) {
             : {}),
     };
 }
+/** The host-relayed auto-poll rung (guuey#1235). A dead session's pull is the storm. */
+const PULL_TOOL = "ggui_runtime_pull";
+/**
+ * Consecutive `unavailable` pull results (per card locator) that OPEN the
+ * circuit (guuey#1235 leg 1). At the #1233 storm's ~12-18 pulls/min a 3-strike
+ * trip bounds the hammer in ~10-15s; a single good pull resets it, so a
+ * transient blip never trips.
+ */
+export const PULL_CIRCUIT_THRESHOLD = 3;
+/**
+ * Logged ONCE when a locator's pull circuit opens — the bounded-storm marker
+ * (sentry's readability ask; the #1233 next-incident is scopeable from it).
+ */
+export const UI_ACTION_PULL_CIRCUIT_OPEN = "UI_ACTION_PULL_CIRCUIT_OPEN";
 /**
  * Assemble the sandbox-facing action relay from a host transport. The
  * returned function is shaped for an `onCallTool` bridge: it always
  * resolves (never rejects), answering in-band.
+ *
+ * guuey#1235 leg 1 — the `ggui_runtime_pull` CIRCUIT BREAK. A card whose live
+ * session died keeps auto-polling on its own interval; each pull `tools/call`
+ * 404s at the pod door → `unavailable` → the sandbox polls again, hammering the
+ * door indefinitely (the #1233 prod storm: 57+ over 15 min). After
+ * {@link PULL_CIRCUIT_THRESHOLD} CONSECUTIVE `unavailable` pull results for a
+ * locator, the circuit OPENS: the relay stops calling the transport for that
+ * locator's pull (fail-fast, no network) — the server storm is bounded. A
+ * single non-`unavailable` pull result CLOSES it (the session recovered). Only
+ * the pull rung is counted — a failed user gesture (`submit_action`) or token
+ * refresh must never trip the auto-poll break, and never opens another rung.
+ *
+ * The complement — telling the USER the session is unrestorable so a tripped
+ * circuit is not a silent freeze — is the `onSessionUnrestorable` signal
+ * (guuey#1249 item 4); this leg only bounds the hammer.
  */
 export function createMcpUiActionRelay(deps) {
+    // Per-relay-instance (one card mount). A recovered/absent locator is deleted,
+    // so this stays as small as the mounted cards; the mount tears it down.
+    const pullFailures = new Map();
+    const recordPull = (uri, unavailable) => {
+        if (!unavailable) {
+            pullFailures.delete(uri); // the session answered → close the circuit
+            return;
+        }
+        const next = (pullFailures.get(uri) ?? 0) + 1;
+        pullFailures.set(uri, next);
+        if (next === PULL_CIRCUIT_THRESHOLD) {
+            // Once, at the trip — not per subsequent short-circuited poll.
+            console.warn(UI_ACTION_PULL_CIRCUIT_OPEN, {
+                resourceUri: uri,
+                consecutiveUnavailable: next,
+            });
+            // guuey#1249 item 4: tell the host the session is unrestorable so the
+            // bounded circuit isn't a silent freeze. A throw from the host callback
+            // must never break the relay's never-reject contract.
+            try {
+                deps.onSessionUnrestorable?.(uri);
+            }
+            catch {
+                // A host-supplied callback that throws is the host's bug, not the
+                // relay's — the storm is already bounded either way.
+            }
+        }
+    };
     return async (request) => {
         if (!UI_ACTION_TOOLS.has(request.name))
             return unavailableToolCallResult();
         if (!request.resourceUri.startsWith("ui://"))
             return unavailableToolCallResult();
+        const isPull = request.name === PULL_TOOL;
+        // Circuit OPEN for this locator's pull → fail-fast, never touch the door.
+        if (isPull && (pullFailures.get(request.resourceUri) ?? 0) >= PULL_CIRCUIT_THRESHOLD) {
+            return unavailableToolCallResult();
+        }
         let raw;
         try {
             raw = await deps.callTool(request.resourceUri, request.name, request.arguments);
         }
         catch {
-            return unavailableToolCallResult(); // transport failure == unavailable, in-band
+            if (isPull)
+                recordPull(request.resourceUri, true); // transport failure == unavailable
+            return unavailableToolCallResult(); // in-band
         }
-        if (raw === undefined)
-            return unavailableToolCallResult();
-        return asToolCallResult(raw) ?? unavailableToolCallResult();
+        const result = raw === undefined ? undefined : asToolCallResult(raw);
+        if (isPull)
+            recordPull(request.resourceUri, result === undefined);
+        return result ?? unavailableToolCallResult();
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/mcp-apps-host",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "The MCP Apps (SEP-1865) Host role for guuey's chat surfaces — view-mount narrowing across UI channels, ui:// locator rehydration by resources/read, and the sandbox-trust channel contract. Vendor-neutral: any spec-following MCP App mounts through it.",
   "license": "MIT",
   "type": "module",

package/src/action.ts

@@ -166,6 +166,15 @@ export interface CreateMcpUiActionRelayDeps {
     name: string,
     args: McpToolStructuredContent | undefined,
   ) => Promise<unknown>;
+  /**
+   * Fired ONCE when a card locator's `ggui_runtime_pull` circuit OPENS
+   * (guuey#1249 item 4) — the live session is unrestorable (N consecutive
+   * both-doors-gone pulls). The complement to leg 1's storm-break: the host
+   * surfaces a visible "this session ended — start a new chat" state and drops
+   * the stale thread, so a tripped circuit is never a silent frozen card.
+   * Optional: a host that only wants the storm bounded omits it.
+   */
+  onSessionUnrestorable?: (resourceUri: string) => void;
 }
 
 /** The request shape a mounted card's `onCallTool` bridge produces. */
@@ -176,24 +185,94 @@ export interface UiActionRequest {
   arguments?: McpToolStructuredContent;
 }
 
+/** The host-relayed auto-poll rung (guuey#1235). A dead session's pull is the storm. */
+const PULL_TOOL = "ggui_runtime_pull";
+
+/**
+ * Consecutive `unavailable` pull results (per card locator) that OPEN the
+ * circuit (guuey#1235 leg 1). At the #1233 storm's ~12-18 pulls/min a 3-strike
+ * trip bounds the hammer in ~10-15s; a single good pull resets it, so a
+ * transient blip never trips.
+ */
+export const PULL_CIRCUIT_THRESHOLD = 3;
+
+/**
+ * Logged ONCE when a locator's pull circuit opens — the bounded-storm marker
+ * (sentry's readability ask; the #1233 next-incident is scopeable from it).
+ */
+export const UI_ACTION_PULL_CIRCUIT_OPEN = "UI_ACTION_PULL_CIRCUIT_OPEN";
+
 /**
  * Assemble the sandbox-facing action relay from a host transport. The
  * returned function is shaped for an `onCallTool` bridge: it always
  * resolves (never rejects), answering in-band.
+ *
+ * guuey#1235 leg 1 — the `ggui_runtime_pull` CIRCUIT BREAK. A card whose live
+ * session died keeps auto-polling on its own interval; each pull `tools/call`
+ * 404s at the pod door → `unavailable` → the sandbox polls again, hammering the
+ * door indefinitely (the #1233 prod storm: 57+ over 15 min). After
+ * {@link PULL_CIRCUIT_THRESHOLD} CONSECUTIVE `unavailable` pull results for a
+ * locator, the circuit OPENS: the relay stops calling the transport for that
+ * locator's pull (fail-fast, no network) — the server storm is bounded. A
+ * single non-`unavailable` pull result CLOSES it (the session recovered). Only
+ * the pull rung is counted — a failed user gesture (`submit_action`) or token
+ * refresh must never trip the auto-poll break, and never opens another rung.
+ *
+ * The complement — telling the USER the session is unrestorable so a tripped
+ * circuit is not a silent freeze — is the `onSessionUnrestorable` signal
+ * (guuey#1249 item 4); this leg only bounds the hammer.
  */
 export function createMcpUiActionRelay(
   deps: CreateMcpUiActionRelayDeps,
 ): (request: UiActionRequest) => Promise<McpToolCallResult> {
+  // Per-relay-instance (one card mount). A recovered/absent locator is deleted,
+  // so this stays as small as the mounted cards; the mount tears it down.
+  const pullFailures = new Map<string, number>();
+
+  const recordPull = (uri: string, unavailable: boolean): void => {
+    if (!unavailable) {
+      pullFailures.delete(uri); // the session answered → close the circuit
+      return;
+    }
+    const next = (pullFailures.get(uri) ?? 0) + 1;
+    pullFailures.set(uri, next);
+    if (next === PULL_CIRCUIT_THRESHOLD) {
+      // Once, at the trip — not per subsequent short-circuited poll.
+      console.warn(UI_ACTION_PULL_CIRCUIT_OPEN, {
+        resourceUri: uri,
+        consecutiveUnavailable: next,
+      });
+      // guuey#1249 item 4: tell the host the session is unrestorable so the
+      // bounded circuit isn't a silent freeze. A throw from the host callback
+      // must never break the relay's never-reject contract.
+      try {
+        deps.onSessionUnrestorable?.(uri);
+      } catch {
+        // A host-supplied callback that throws is the host's bug, not the
+        // relay's — the storm is already bounded either way.
+      }
+    }
+  };
+
   return async (request) => {
     if (!UI_ACTION_TOOLS.has(request.name)) return unavailableToolCallResult();
     if (!request.resourceUri.startsWith("ui://")) return unavailableToolCallResult();
+
+    const isPull = request.name === PULL_TOOL;
+    // Circuit OPEN for this locator's pull → fail-fast, never touch the door.
+    if (isPull && (pullFailures.get(request.resourceUri) ?? 0) >= PULL_CIRCUIT_THRESHOLD) {
+      return unavailableToolCallResult();
+    }
+
     let raw: unknown;
     try {
       raw = await deps.callTool(request.resourceUri, request.name, request.arguments);
     } catch {
-      return unavailableToolCallResult(); // transport failure == unavailable, in-band
+      if (isPull) recordPull(request.resourceUri, true); // transport failure == unavailable
+      return unavailableToolCallResult(); // in-band
     }
-    if (raw === undefined) return unavailableToolCallResult();
-    return asToolCallResult(raw) ?? unavailableToolCallResult();
+    const result = raw === undefined ? undefined : asToolCallResult(raw);
+    if (isPull) recordPull(request.resourceUri, result === undefined);
+    return result ?? unavailableToolCallResult();
   };
 }