@guuey/mcp-apps-host 0.30.0 → 0.31.0

package/dist/action.d.ts

@@ -137,8 +137,28 @@ export interface CreateMcpUiActionRelayDeps {
      * 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.
+     *
+     * Once per trip: it fires again only after {@link onSessionRestored} has
+     * cleared an earlier verdict for the same locator and the circuit trips anew.
      */
     onSessionUnrestorable?: (resourceUri: string) => void;
+    /**
+     * Fired when a locator whose pull circuit OPENED is seen live again on the
+     * pull rung itself, so the host can withdraw the "session ended" state it
+     * showed. Wiring it is what lets an open circuit recover in place at all:
+     * without it the circuit stays open for the mount (recovery is a fresh
+     * mount), exactly as a host that wires only {@link onSessionUnrestorable}
+     * expects.
+     *
+     * The recovery is evidence on the channel that tripped: a successful
+     * `ggui_runtime_refresh_ws_token` for the locator HALF-OPENS the circuit,
+     * which lets the view's next pull through as a single probe. A probe that
+     * the session answers closes the circuit and fires this, once per close; a
+     * probe that fails leaves it open, and the host hears nothing new (it
+     * already holds the verdict). A token refresh alone never reverses it: the
+     * token channel can work while pulls still fail.
+     */
+    onSessionRestored?: (resourceUri: string) => void;
 }
 /** The request shape a mounted card's `onCallTool` bridge produces. */
 export interface UiActionRequest {
@@ -165,6 +185,20 @@ export declare const PULL_CIRCUIT_THRESHOLD = 3;
  * and nothing retries unattended.
  */
 export declare const UI_ACTION_PULL_CIRCUIT_OPEN = "[guuey] card updates stopped \u2014 the session behind this card could not be restored; the widget reports it, and a new conversation starts fresh";
+/**
+ * Logged when an open circuit closes again: the probe pull a successful token
+ * refresh let through was answered, and the host was told
+ * (`onSessionRestored`). It can only happen for a host that wires that signal.
+ */
+export declare const UI_ACTION_PULL_CIRCUIT_CLOSED = "[guuey] card updates resumed \u2014 the session behind this card answered again";
+/**
+ * Logged when a host's `onSessionUnrestorable` or `onSessionRestored`
+ * callback throws. The relay never rejects into the card, so it goes on; this
+ * line is the page's only trace that its own "session ended" state may now be
+ * out of step with the card. It names the callback and the error's `name`,
+ * never the error's text, which is the host's and can carry anything.
+ */
+export declare const UI_ACTION_HOST_CALLBACK_THREW = "[guuey] the page's card-session handler threw \u2014 the card went on, but the page may not show its current state";
 /**
  * Assemble the sandbox-facing action relay from a host transport. The
  * returned function is shaped for an `onCallTool` bridge: it always
@@ -184,6 +218,11 @@ export declare const UI_ACTION_PULL_CIRCUIT_OPEN = "[guuey] card updates stopped
  * 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.
+ *
+ * An OPEN circuit is terminal for the mount unless the host wires
+ * `onSessionRestored`. Then a successful `ggui_runtime_refresh_ws_token` for
+ * the locator HALF-OPENS it: the next pull goes through as one probe, and only
+ * a probe the session answers closes it (see `onSessionRestored`).
  */
 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;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAK9C,CAAC;AAEH,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,mBAAmB,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,qBAAqB,CAYxE,CAAC;AAEH,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAmE1C;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,wBAAwB,GAAG,SAAS,GACzC,wBAAwB,GAAG,SAAS,CAatC;AAOD;;;;;;;;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;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,uJACyG,CAAC;AAElJ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,0BAA0B,GAC/B,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CA4D1D"}
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"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"}

package/dist/action.js

@@ -229,6 +229,8 @@ 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";
+/** The live-channel token refresh: a success half-opens a tripped locator for a host that can hear a restore. */
+const REFRESH_WS_TOKEN_TOOL = "ggui_runtime_refresh_ws_token";
 /**
  * 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
@@ -247,6 +249,33 @@ export const PULL_CIRCUIT_THRESHOLD = 3;
  * and nothing retries unattended.
  */
 export const UI_ACTION_PULL_CIRCUIT_OPEN = "[guuey] card updates stopped — the session behind this card could not be restored; the widget reports it, and a new conversation starts fresh";
+/**
+ * Logged when an open circuit closes again: the probe pull a successful token
+ * refresh let through was answered, and the host was told
+ * (`onSessionRestored`). It can only happen for a host that wires that signal.
+ */
+export const UI_ACTION_PULL_CIRCUIT_CLOSED = "[guuey] card updates resumed — the session behind this card answered again";
+/**
+ * Logged when a host's `onSessionUnrestorable` or `onSessionRestored`
+ * callback throws. The relay never rejects into the card, so it goes on; this
+ * line is the page's only trace that its own "session ended" state may now be
+ * out of step with the card. It names the callback and the error's `name`,
+ * never the error's text, which is the host's and can carry anything.
+ */
+export const UI_ACTION_HOST_CALLBACK_THREW = "[guuey] the page's card-session handler threw — the card went on, but the page may not show its current state";
+/** Call a host's session callback; a throw is logged by name and never escapes the relay. */
+function callHostCallback(callback, fn, resourceUri) {
+    try {
+        fn?.(resourceUri);
+    }
+    catch (err) {
+        console.warn(UI_ACTION_HOST_CALLBACK_THREW, {
+            callback,
+            resourceUri,
+            name: err instanceof Error ? err.name : typeof err,
+        });
+    }
+}
 /**
  * Assemble the sandbox-facing action relay from a host transport. The
  * returned function is shaped for an `onCallTool` bridge: it always
@@ -266,14 +295,29 @@ export const UI_ACTION_PULL_CIRCUIT_OPEN = "[guuey] card updates stopped — the
  * 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.
+ *
+ * An OPEN circuit is terminal for the mount unless the host wires
+ * `onSessionRestored`. Then a successful `ggui_runtime_refresh_ws_token` for
+ * the locator HALF-OPENS it: the next pull goes through as one probe, and only
+ * a probe the session answers closes it (see `onSessionRestored`).
  */
 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();
+    // Open locators a successful token refresh has half-opened: the next pull is
+    // let through as the probe. Only ever filled when the host wires the restore.
+    const halfOpen = new Set();
+    const isOpen = (uri) => (pullFailures.get(uri) ?? 0) >= PULL_CIRCUIT_THRESHOLD;
     const recordPull = (uri, unavailable) => {
         if (!unavailable) {
+            const wasOpen = isOpen(uri);
             pullFailures.delete(uri); // the session answered → close the circuit
+            if (wasOpen) {
+                console.warn(UI_ACTION_PULL_CIRCUIT_CLOSED, { resourceUri: uri });
+                // The circuit is closed either way: a throwing host callback is logged, never rethrown.
+                callHostCallback("onSessionRestored", deps.onSessionRestored, uri);
+            }
             return;
         }
         const next = (pullFailures.get(uri) ?? 0) + 1;
@@ -287,13 +331,8 @@ export function createMcpUiActionRelay(deps) {
             // 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.
-            }
+            // The storm is bounded either way: a throwing host callback is logged, never rethrown.
+            callHostCallback("onSessionUnrestorable", deps.onSessionUnrestorable, uri);
         }
     };
     return async (request) => {
@@ -311,9 +350,11 @@ export function createMcpUiActionRelay(deps) {
                 return telemetryNothingToRelayResult();
         }
         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();
+        // Circuit OPEN for this locator's pull → fail-fast, never touch the door,
+        // unless a token refresh half-opened it: then this one pull is the probe.
+        if (isPull && isOpen(request.resourceUri)) {
+            if (!halfOpen.delete(request.resourceUri))
+                return unavailableToolCallResult();
         }
         let raw;
         try {
@@ -327,6 +368,16 @@ export function createMcpUiActionRelay(deps) {
         const result = raw === undefined ? undefined : asToolCallResult(raw);
         if (isPull)
             recordPull(request.resourceUri, result === undefined);
+        // A refresh the session granted is fresh evidence it is live, but on the
+        // token channel, not the pull channel that tripped: it half-opens, and the
+        // probe pull decides. Only for a host that can withdraw its verdict.
+        if (request.name === REFRESH_WS_TOKEN_TOOL &&
+            deps.onSessionRestored !== undefined &&
+            result !== undefined &&
+            result.isError !== true &&
+            isOpen(request.resourceUri)) {
+            halfOpen.add(request.resourceUri);
+        }
         return result ?? unavailableToolCallResult();
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/mcp-apps-host",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "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",
@@ -12,6 +12,9 @@
     "!src/**/*.test.ts",
     "README.md"
   ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "exports": {
     ".": {
       "react-native": "./src/index.ts",
@@ -35,7 +38,7 @@
   "dependencies": {
     "@ggui-ai/protocol": "0.24.0",
     "@modelcontextprotocol/ext-apps": "^1.7.5",
-    "@silverprotocol/core": "0.11.0"
+    "@silverprotocol/core": "0.12.1"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/action.ts

@@ -305,8 +305,28 @@ export interface CreateMcpUiActionRelayDeps {
    * 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.
+   *
+   * Once per trip: it fires again only after {@link onSessionRestored} has
+   * cleared an earlier verdict for the same locator and the circuit trips anew.
    */
   onSessionUnrestorable?: (resourceUri: string) => void;
+  /**
+   * Fired when a locator whose pull circuit OPENED is seen live again on the
+   * pull rung itself, so the host can withdraw the "session ended" state it
+   * showed. Wiring it is what lets an open circuit recover in place at all:
+   * without it the circuit stays open for the mount (recovery is a fresh
+   * mount), exactly as a host that wires only {@link onSessionUnrestorable}
+   * expects.
+   *
+   * The recovery is evidence on the channel that tripped: a successful
+   * `ggui_runtime_refresh_ws_token` for the locator HALF-OPENS the circuit,
+   * which lets the view's next pull through as a single probe. A probe that
+   * the session answers closes the circuit and fires this, once per close; a
+   * probe that fails leaves it open, and the host hears nothing new (it
+   * already holds the verdict). A token refresh alone never reverses it: the
+   * token channel can work while pulls still fail.
+   */
+  onSessionRestored?: (resourceUri: string) => void;
 }
 
 /** The request shape a mounted card's `onCallTool` bridge produces. */
@@ -320,6 +340,9 @@ export interface UiActionRequest {
 /** The host-relayed auto-poll rung (guuey#1235). A dead session's pull is the storm. */
 const PULL_TOOL = "ggui_runtime_pull";
 
+/** The live-channel token refresh: a success half-opens a tripped locator for a host that can hear a restore. */
+const REFRESH_WS_TOKEN_TOOL = "ggui_runtime_refresh_ws_token";
+
 /**
  * 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
@@ -341,6 +364,41 @@ export const PULL_CIRCUIT_THRESHOLD = 3;
 export const UI_ACTION_PULL_CIRCUIT_OPEN =
   "[guuey] card updates stopped — the session behind this card could not be restored; the widget reports it, and a new conversation starts fresh";
 
+/**
+ * Logged when an open circuit closes again: the probe pull a successful token
+ * refresh let through was answered, and the host was told
+ * (`onSessionRestored`). It can only happen for a host that wires that signal.
+ */
+export const UI_ACTION_PULL_CIRCUIT_CLOSED =
+  "[guuey] card updates resumed — the session behind this card answered again";
+
+/**
+ * Logged when a host's `onSessionUnrestorable` or `onSessionRestored`
+ * callback throws. The relay never rejects into the card, so it goes on; this
+ * line is the page's only trace that its own "session ended" state may now be
+ * out of step with the card. It names the callback and the error's `name`,
+ * never the error's text, which is the host's and can carry anything.
+ */
+export const UI_ACTION_HOST_CALLBACK_THREW =
+  "[guuey] the page's card-session handler threw — the card went on, but the page may not show its current state";
+
+/** Call a host's session callback; a throw is logged by name and never escapes the relay. */
+function callHostCallback(
+  callback: "onSessionUnrestorable" | "onSessionRestored",
+  fn: ((resourceUri: string) => void) | undefined,
+  resourceUri: string,
+): void {
+  try {
+    fn?.(resourceUri);
+  } catch (err) {
+    console.warn(UI_ACTION_HOST_CALLBACK_THREW, {
+      callback,
+      resourceUri,
+      name: err instanceof Error ? err.name : typeof err,
+    });
+  }
+}
+
 /**
  * Assemble the sandbox-facing action relay from a host transport. The
  * returned function is shaped for an `onCallTool` bridge: it always
@@ -360,6 +418,11 @@ export const UI_ACTION_PULL_CIRCUIT_OPEN =
  * 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.
+ *
+ * An OPEN circuit is terminal for the mount unless the host wires
+ * `onSessionRestored`. Then a successful `ggui_runtime_refresh_ws_token` for
+ * the locator HALF-OPENS it: the next pull goes through as one probe, and only
+ * a probe the session answers closes it (see `onSessionRestored`).
  */
 export function createMcpUiActionRelay(
   deps: CreateMcpUiActionRelayDeps,
@@ -367,10 +430,21 @@ export function createMcpUiActionRelay(
   // 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>();
+  // Open locators a successful token refresh has half-opened: the next pull is
+  // let through as the probe. Only ever filled when the host wires the restore.
+  const halfOpen = new Set<string>();
+
+  const isOpen = (uri: string): boolean => (pullFailures.get(uri) ?? 0) >= PULL_CIRCUIT_THRESHOLD;
 
   const recordPull = (uri: string, unavailable: boolean): void => {
     if (!unavailable) {
+      const wasOpen = isOpen(uri);
       pullFailures.delete(uri); // the session answered → close the circuit
+      if (wasOpen) {
+        console.warn(UI_ACTION_PULL_CIRCUIT_CLOSED, { resourceUri: uri });
+        // The circuit is closed either way: a throwing host callback is logged, never rethrown.
+        callHostCallback("onSessionRestored", deps.onSessionRestored, uri);
+      }
       return;
     }
     const next = (pullFailures.get(uri) ?? 0) + 1;
@@ -384,12 +458,8 @@ export function createMcpUiActionRelay(
       // 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.
-      }
+      // The storm is bounded either way: a throwing host callback is logged, never rethrown.
+      callHostCallback("onSessionUnrestorable", deps.onSessionUnrestorable, uri);
     }
   };
 
@@ -407,9 +477,10 @@ export function createMcpUiActionRelay(
     }
 
     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();
+    // Circuit OPEN for this locator's pull → fail-fast, never touch the door,
+    // unless a token refresh half-opened it: then this one pull is the probe.
+    if (isPull && isOpen(request.resourceUri)) {
+      if (!halfOpen.delete(request.resourceUri)) return unavailableToolCallResult();
     }
 
     let raw: unknown;
@@ -421,6 +492,18 @@ export function createMcpUiActionRelay(
     }
     const result = raw === undefined ? undefined : asToolCallResult(raw);
     if (isPull) recordPull(request.resourceUri, result === undefined);
+    // A refresh the session granted is fresh evidence it is live, but on the
+    // token channel, not the pull channel that tripped: it half-opens, and the
+    // probe pull decides. Only for a host that can withdraw its verdict.
+    if (
+      request.name === REFRESH_WS_TOKEN_TOOL &&
+      deps.onSessionRestored !== undefined &&
+      result !== undefined &&
+      result.isError !== true &&
+      isOpen(request.resourceUri)
+    ) {
+      halfOpen.add(request.resourceUri);
+    }
     return result ?? unavailableToolCallResult();
   };
 }