@guuey/agent-client 0.13.0 → 0.14.1

package/dist/saturation-retry.d.ts

@@ -19,6 +19,26 @@ export interface SaturationRetryOptions {
      * real 15s timer; production uses an abort-aware `setTimeout`.
      */
     sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    /**
+     * Total send attempts on a saturated pod (guuey#406). Default 1 retry
+     * (2 attempts) — the historical behavior; capped at 5. A capacity-1 pod
+     * (demo fixtures, xs plans) refuses the SECOND simultaneous visitor, so
+     * end-user surfaces budget higher and pair it with `onSaturationWait` so
+     * the wait is a visible busy state, never a silent hang or a generic
+     * error boundary (the 2026-08-24 standalone incident).
+     */
+    attempts?: number;
+    /**
+     * Fired before each saturation wait — the surface's hook for an honest
+     * "the agent is helping someone else" state. Never fired for other error
+     * classes; the turn stays `connecting` throughout (the hook's state
+     * machine deliberately has no `retrying` status).
+     */
+    onSaturationWait?: (info: {
+        attempt: number;
+        totalAttempts: number;
+        waitMs: number;
+    }) => void;
 }
 /**
  * Wrap an invoke transport with ONE automatic retry on a saturated pod.

package/dist/saturation-retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"saturation-retry.d.ts","sourceRoot":"","sources":["../src/saturation-retry.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,YAAY,CAAC;AAiBjE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAMhF;AA4BD,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,eAAe,EAC1B,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAqBjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAkBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,EAC1B,OAAO,GAAE,qBAA0B,GAClC,eAAe,CA0BjB"}
+{"version":3,"file":"saturation-retry.d.ts","sourceRoot":"","sources":["../src/saturation-retry.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,YAAY,CAAC;AAiBjE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAMhF;AA4BD,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC/F;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,eAAe,EAC1B,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAyBjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAkBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,EAC1B,OAAO,GAAE,qBAA0B,GAClC,eAAe,CA0BjB"}

package/dist/saturation-retry.js

@@ -82,6 +82,8 @@ function delay(ms, signal) {
         signal.addEventListener("abort", finish, { once: true });
     });
 }
+/** Hard ceiling on {@link SaturationRetryOptions.attempts} retries. */
+const MAX_SATURATION_RETRIES = 5;
 /**
  * Wrap an invoke transport with ONE automatic retry on a saturated pod.
  *
@@ -119,27 +121,31 @@ function delay(ms, signal) {
  * replaying a token that may have expired during the wait.
  */
 export function withSaturationRetry(transport, options = {}) {
+    const retries = Math.min(Math.max(options.attempts ?? 1, 1), MAX_SATURATION_RETRIES);
     return async function* retrying(req) {
-        let yielded = false;
-        try {
-            for await (const chunk of transport(req)) {
-                yielded = true;
-                yield chunk;
+        for (let attempt = 1;; attempt += 1) {
+            let yielded = false;
+            try {
+                for await (const chunk of transport(req)) {
+                    yielded = true;
+                    yield chunk;
+                }
+                return;
+            }
+            catch (err) {
+                const saturated = err instanceof AgentResponseError && err.code === AGENT_ERROR_CODES.POD_SATURATED;
+                if (!saturated || yielded || attempt > retries)
+                    throw err;
+                const waitMs = saturationDelayMs(err.retryAfterSeconds);
+                options.onSaturationWait?.({ attempt, totalAttempts: retries + 1, waitMs });
+                await (options.sleep ?? delay)(waitMs, req.signal);
+                // Aborted mid-wait: the user is done with this turn. Surface the
+                // refusal that caused the wait rather than spending a request that
+                // `fetch` would reject on the signal anyway.
+                if (req.signal.aborted)
+                    throw err;
             }
-            return;
-        }
-        catch (err) {
-            const saturated = err instanceof AgentResponseError && err.code === AGENT_ERROR_CODES.POD_SATURATED;
-            if (!saturated || yielded)
-                throw err;
-            await (options.sleep ?? delay)(saturationDelayMs(err.retryAfterSeconds), req.signal);
-            // Aborted mid-wait: the user is done with this turn. Surface the refusal
-            // that caused the wait rather than spending a request that `fetch` would
-            // reject on the signal anyway.
-            if (req.signal.aborted)
-                throw err;
         }
-        yield* transport(req);
     };
 }
 const COLD_START_DEFAULT_ATTEMPTS = 3;

package/dist/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAgB5C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAEpF;AAoHD,gDAAgD;AAChD,MAAM,WAAW,2BAA4B,SAAQ,sBAAsB;IACzE;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAC/C;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,aAAa,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,OAAO,GAAE,2BAAgC,GACxC,aAAa,CAAC,MAAM,CAAC,CAcvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,IAAI,GAClB,eAAe,CAOjB"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAgB5C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAEpF;AAoHD,gDAAgD;AAChD,MAAM,WAAW,2BAA4B,SAAQ,sBAAsB;IACzE;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAC/C;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,aAAa,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,OAAO,GAAE,2BAAgC,GACxC,aAAa,CAAC,MAAM,CAAC,CAoBvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,IAAI,GAClB,eAAe,CAOjB"}

package/dist/transport.js

@@ -160,7 +160,13 @@ export function fetchStreamTransport(req, accessToken, guestSecret, options = {}
         const bearer = getBearer ? await getBearer() : accessToken;
         yield* streamInvokeOnce(attempt, bearer, guestSecret);
     };
-    const saturated = withSaturationRetry(once, { sleep: options.sleep });
+    const saturated = withSaturationRetry(once, {
+        sleep: options.sleep,
+        ...(options.attempts !== undefined ? { attempts: options.attempts } : {}),
+        ...(options.onSaturationWait !== undefined
+            ? { onSaturationWait: options.onSaturationWait }
+            : {}),
+    });
     if (options.coldStartRetry === false)
         return saturated(req);
     return withColdStartRetry(saturated, {

package/dist/types.d.ts

@@ -116,12 +116,20 @@ export interface AgentInvokeAdapters {
 /** Tuning for the guuey#192 stall watchdog — see {@link UseAgentInvokeOptions.stallRecovery}. */
 export interface StallRecoveryOptions {
     /**
-     * Byte-inactivity window (ms) before a history probe fires. Armed only
-     * AFTER the first byte of the turn — pre-first-byte silence is a legitimate
-     * cold start and never triggers. Every received chunk resets it.
-     * Default 25000.
+     * Byte-inactivity window (ms) before a history probe fires. Armed with
+     * {@link preFirstByteWindowMs} at turn start, re-armed with THIS window by
+     * every received chunk. Default 25000.
      */
     windowMs?: number;
+    /**
+     * The PRE-first-byte window (ms) — guuey#409: a turn that never receives
+     * ANY byte (an invoke-rail death upstream of the pod, or an in-pod
+     * pre-spawn hang) previously showed "Thinking…" forever with no error
+     * item; this window bounds it. Much longer than `windowMs` on purpose —
+     * the transport's cold-start retries legitimately spend up to ~90s before
+     * the first byte. Default 120000.
+     */
+    preFirstByteWindowMs?: number;
     /**
      * Fruitless probes (history shows the turn still in flight, or no probe is
      * possible) before the turn fails with `CLIENT_ERROR_CODES.STREAM_STALLED`.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5F,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,YAAY,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,SAAS,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC;AAEtC,kDAAkD;AAClD,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,IAAI,EAAE,OAAO,CAAC;IACd,mCAAmC;IACnC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,aAAa,CAAC,MAAM,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,EAAE,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAEnB;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,sFAAsF;IACtF,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACpD;AAED,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,eAAe,CAAC;IAC3B,yGAAyG;IACzG,OAAO,CAAC,EAAE,yBAAyB,CAAC;CACrC;AAED,iGAAiG;AACjG,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,6FAA6F;IAC7F,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,EAAE,mBAAmB,CAAC;IAC9B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,KAAK,GAAG,oBAAoB,CAAC;IAC7C;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,CAAC;AAElG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC;mFAC+E;IAC/E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,8EAA8E;IAC9E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yEAAyE;IACzE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,EAAE,cAAc,GAAG,IAAI,CAAC;IACpC;;;;;;;;OAQG;IACH,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,kBAAkB,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC9C,uEAAuE;IACvE,uBAAuB,EAAE,MAAM,IAAI,CAAC;IACpC;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC;CAC5D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5F,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,YAAY,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,SAAS,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC;AAEtC,kDAAkD;AAClD,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,IAAI,EAAE,OAAO,CAAC;IACd,mCAAmC;IACnC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,aAAa,CAAC,MAAM,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,EAAE,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAEnB;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,sFAAsF;IACtF,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACpD;AAED,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,eAAe,CAAC;IAC3B,yGAAyG;IACzG,OAAO,CAAC,EAAE,yBAAyB,CAAC;CACrC;AAED,iGAAiG;AACjG,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,6FAA6F;IAC7F,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,EAAE,mBAAmB,CAAC;IAC9B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,KAAK,GAAG,oBAAoB,CAAC;IAC7C;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,CAAC;AAElG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC;mFAC+E;IAC/E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,8EAA8E;IAC9E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yEAAyE;IACzE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,EAAE,cAAc,GAAG,IAAI,CAAC;IACpC;;;;;;;;OAQG;IACH,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,kBAAkB,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC9C,uEAAuE;IACvE,uBAAuB,EAAE,MAAM,IAAI,CAAC;IACpC;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC;CAC5D"}

package/dist/useAgentInvoke.d.ts

@@ -28,6 +28,15 @@ export declare function applyHistoryResult(result: HistoryLoadResult, currentMes
 export declare const STALL_RECOVERY_DEFAULTS: {
     readonly windowMs: 25000;
     readonly probeAttempts: 4;
+    /**
+     * guuey#409: the PRE-first-byte watchdog window. The #192 clock arms only
+     * on the first chunk (so a silent cold start never trips it) — which left
+     * a turn that never receives ANY byte with no watchdog at all: the
+     * eternal-"Thinking…" face of the 2026-08-22 invoke-rail turn death.
+     * Deliberately much longer than `windowMs`: the transport's cold-start
+     * retries legitimately spend up to ~90s before the first byte.
+     */
+    readonly preFirstByteWindowMs: 120000;
 };
 /**
  * Pure decision seam for the guuey#192 stall probe: does a freshly-loaded

package/dist/useAgentInvoke.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAgentInvoke.d.ts","sourceRoot":"","sources":["../src/useAgentInvoke.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAW,KAAK,oBAAoB,EAAuB,MAAM,sBAAsB,CAAC;AAK/F,OAAO,KAAK,EAGV,YAAY,EAEZ,iBAAiB,EAGjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAMpB;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC,EAAE,oBAEnD,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,eAAe,EAAE,YAAY,EAAE,GAC9B,kBAAkB,CAIpB;AAED,uFAAuF;AACvF,eAAO,MAAM,uBAAuB;;;CAAkD,CAAC;AAYvF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EAAE,EACvB,cAAc,EAAE,MAAM,GACrB,OAAO,GAAG,WAAW,CAOvB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CA6dhF"}
+{"version":3,"file":"useAgentInvoke.d.ts","sourceRoot":"","sources":["../src/useAgentInvoke.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAW,KAAK,oBAAoB,EAAuB,MAAM,sBAAsB,CAAC;AAK/F,OAAO,KAAK,EAGV,YAAY,EAEZ,iBAAiB,EAGjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAMpB;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC,EAAE,oBAEnD,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,eAAe,EAAE,YAAY,EAAE,GAC9B,kBAAkB,CAIpB;AAED,uFAAuF;AACvF,eAAO,MAAM,uBAAuB;;;IAGlC;;;;;;;OAOG;;CAEK,CAAC;AAcX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EAAE,EACvB,cAAc,EAAE,MAAM,GACrB,OAAO,GAAG,WAAW,CAOvB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CAoehF"}

package/dist/useAgentInvoke.js

@@ -54,13 +54,26 @@ export function applyHistoryResult(result, currentMessages) {
     return { kind: "seed", messages: result.messages };
 }
 /** The guuey#192 stall watchdog's resolved tuning (see {@link stallProbeDecision}). */
-export const STALL_RECOVERY_DEFAULTS = { windowMs: 25_000, probeAttempts: 4 };
+export const STALL_RECOVERY_DEFAULTS = {
+    windowMs: 25_000,
+    probeAttempts: 4,
+    /**
+     * guuey#409: the PRE-first-byte watchdog window. The #192 clock arms only
+     * on the first chunk (so a silent cold start never trips it) — which left
+     * a turn that never receives ANY byte with no watchdog at all: the
+     * eternal-"Thinking…" face of the 2026-08-22 invoke-rail turn death.
+     * Deliberately much longer than `windowMs`: the transport's cold-start
+     * retries legitimately spend up to ~90s before the first byte.
+     */
+    preFirstByteWindowMs: 120_000,
+};
 function resolveStallRecovery(option) {
     if (option === false)
         return null;
     return {
         windowMs: option?.windowMs ?? STALL_RECOVERY_DEFAULTS.windowMs,
         probeAttempts: option?.probeAttempts ?? STALL_RECOVERY_DEFAULTS.probeAttempts,
+        preFirstByteWindowMs: option?.preFirstByteWindowMs ?? STALL_RECOVERY_DEFAULTS.preFirstByteWindowMs,
     };
 }
 /**
@@ -370,14 +383,21 @@ export function useAgentInvoke(opts) {
                 stallTimer = null;
             }
         };
-        const armStallTimer = () => {
+        const armStallTimer = (windowMs) => {
             if (!stall || turnEnded || controller.signal.aborted)
                 return;
             clearStallTimer();
             stallTimer = setTimeout(() => {
                 void onStallWindow();
-            }, stall.windowMs);
+            }, windowMs ?? stall.windowMs);
         };
+        // guuey#409: arm BEFORE the first byte — a turn that never receives
+        // any chunk (rail death upstream of the pod, or an in-pod pre-spawn
+        // hang) otherwise shows "Thinking…" forever with no error item. The
+        // long window keeps silent cold starts un-tripped; expiry runs the
+        // SAME probe-then-adopt-or-STREAM_STALLED machinery as mid-stream
+        // stalls — one face fix for both mechanisms.
+        armStallTimer(stall?.preFirstByteWindowMs);
         const endTurnWith = (apply) => {
             turnEnded = true;
             clearStallTimer();

package/dist/web-adapters.d.ts

@@ -9,6 +9,7 @@
 import { type McpToolCallResult, type ResolvedViewMount, type UiActionRequest } from "@guuey/mcp-apps-host";
 import type { AgHitlAnswer } from "@silverprotocol/core";
 import type { AgentInvokeAdapters, ThreadIdStore } from "./types.js";
+import type { SaturationRetryOptions } from "./saturation-retry.js";
 /** Persists the threadId in `window.localStorage` (synchronously). */
 export declare const localStorageThreadStore: ThreadIdStore;
 /** Crypto-strong client-message id, with a non-crypto fallback. */
@@ -19,6 +20,16 @@ export interface CreateWebAdaptersOptions {
      * omitted, no history adapter is installed and reloads start empty.
      */
     apiBaseUrl?: string;
+    /**
+     * Total send attempts on a saturated pod (guuey#406) — forwarded to
+     * {@link SaturationRetryOptions.attempts}. End-user surfaces facing
+     * capacity-1 pods (demo fixtures, xs plans) budget higher than the
+     * 2-attempt default and pair it with {@link onSaturationWait} so the
+     * wait is a visible busy state.
+     */
+    saturationAttempts?: number;
+    /** Forwarded to {@link SaturationRetryOptions.onSaturationWait}. */
+    onSaturationWait?: SaturationRetryOptions["onSaturationWait"];
     /**
      * Resolve the caller's Cognito access token (fresh), or `null` when signed
      * out. When a token is present the chat transport AND the history read

package/dist/web-adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web-adapters.d.ts","sourceRoot":"","sources":["../src/web-adapters.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"web-adapters.d.ts","sourceRoot":"","sources":["../src/web-adapters.ts"],"names":[],"mappings":"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"}

package/dist/web-adapters.js

@@ -59,6 +59,10 @@ export function createWebAdapters(opts = {}) {
         // resolves inside its generator).
         yield* fetchStreamTransport(req, null, getGuestSecret ? getGuestSecret() : null, {
             getBearer: getAccessToken,
+            ...(opts.saturationAttempts !== undefined ? { attempts: opts.saturationAttempts } : {}),
+            ...(opts.onSaturationWait !== undefined
+                ? { onSaturationWait: opts.onSaturationWait }
+                : {}),
         });
     };
     const adapters = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/agent-client",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Client SDK for Guuey's agent runtime: the `useAgentInvoke` React hook + pure SSE helpers that speak the /agent/invoke streaming contract, plus the paginated thread-history read plane. Host adapters (storage / id / transport) are injected, so it runs on web (Next) and React Native alike.",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@silverprotocol/core": "0.5.1",
-    "@guuey/mcp-apps-host": "0.13.0"
+    "@guuey/mcp-apps-host": "0.14.1"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -48,7 +48,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.2.7"
   },
   "publishConfig": {
     "access": "public"

package/src/saturation-retry.ts

@@ -94,8 +94,27 @@ export interface SaturationRetryOptions {
    * real 15s timer; production uses an abort-aware `setTimeout`.
    */
   sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+  /**
+   * Total send attempts on a saturated pod (guuey#406). Default 1 retry
+   * (2 attempts) — the historical behavior; capped at 5. A capacity-1 pod
+   * (demo fixtures, xs plans) refuses the SECOND simultaneous visitor, so
+   * end-user surfaces budget higher and pair it with `onSaturationWait` so
+   * the wait is a visible busy state, never a silent hang or a generic
+   * error boundary (the 2026-08-24 standalone incident).
+   */
+  attempts?: number;
+  /**
+   * Fired before each saturation wait — the surface's hook for an honest
+   * "the agent is helping someone else" state. Never fired for other error
+   * classes; the turn stays `connecting` throughout (the hook's state
+   * machine deliberately has no `retrying` status).
+   */
+  onSaturationWait?: (info: { attempt: number; totalAttempts: number; waitMs: number }) => void;
 }
 
+/** Hard ceiling on {@link SaturationRetryOptions.attempts} retries. */
+const MAX_SATURATION_RETRIES = 5;
+
 /**
  * Wrap an invoke transport with ONE automatic retry on a saturated pod.
  *
@@ -136,25 +155,29 @@ export function withSaturationRetry(
   transport: InvokeTransport,
   options: SaturationRetryOptions = {},
 ): InvokeTransport {
+  const retries = Math.min(Math.max(options.attempts ?? 1, 1), MAX_SATURATION_RETRIES);
   return async function* retrying(req: InvokeRequest): AsyncGenerator<string> {
-    let yielded = false;
-    try {
-      for await (const chunk of transport(req)) {
-        yielded = true;
-        yield chunk;
+    for (let attempt = 1; ; attempt += 1) {
+      let yielded = false;
+      try {
+        for await (const chunk of transport(req)) {
+          yielded = true;
+          yield chunk;
+        }
+        return;
+      } catch (err) {
+        const saturated =
+          err instanceof AgentResponseError && err.code === AGENT_ERROR_CODES.POD_SATURATED;
+        if (!saturated || yielded || attempt > retries) throw err;
+        const waitMs = saturationDelayMs(err.retryAfterSeconds);
+        options.onSaturationWait?.({ attempt, totalAttempts: retries + 1, waitMs });
+        await (options.sleep ?? delay)(waitMs, req.signal);
+        // Aborted mid-wait: the user is done with this turn. Surface the
+        // refusal that caused the wait rather than spending a request that
+        // `fetch` would reject on the signal anyway.
+        if (req.signal.aborted) throw err;
       }
-      return;
-    } catch (err) {
-      const saturated =
-        err instanceof AgentResponseError && err.code === AGENT_ERROR_CODES.POD_SATURATED;
-      if (!saturated || yielded) throw err;
-      await (options.sleep ?? delay)(saturationDelayMs(err.retryAfterSeconds), req.signal);
-      // Aborted mid-wait: the user is done with this turn. Surface the refusal
-      // that caused the wait rather than spending a request that `fetch` would
-      // reject on the signal anyway.
-      if (req.signal.aborted) throw err;
     }
-    yield* transport(req);
   };
 }
 

package/src/transport.ts

@@ -228,7 +228,13 @@ export function fetchStreamTransport(
     const bearer = getBearer ? await getBearer() : accessToken;
     yield* streamInvokeOnce(attempt, bearer, guestSecret);
   };
-  const saturated = withSaturationRetry(once, { sleep: options.sleep });
+  const saturated = withSaturationRetry(once, {
+    sleep: options.sleep,
+    ...(options.attempts !== undefined ? { attempts: options.attempts } : {}),
+    ...(options.onSaturationWait !== undefined
+      ? { onSaturationWait: options.onSaturationWait }
+      : {}),
+  });
   if (options.coldStartRetry === false) return saturated(req);
   return withColdStartRetry(saturated, {
     sleep: options.sleep,

package/src/types.ts

@@ -125,12 +125,20 @@ export interface AgentInvokeAdapters {
 /** Tuning for the guuey#192 stall watchdog — see {@link UseAgentInvokeOptions.stallRecovery}. */
 export interface StallRecoveryOptions {
   /**
-   * Byte-inactivity window (ms) before a history probe fires. Armed only
-   * AFTER the first byte of the turn — pre-first-byte silence is a legitimate
-   * cold start and never triggers. Every received chunk resets it.
-   * Default 25000.
+   * Byte-inactivity window (ms) before a history probe fires. Armed with
+   * {@link preFirstByteWindowMs} at turn start, re-armed with THIS window by
+   * every received chunk. Default 25000.
    */
   windowMs?: number;
+  /**
+   * The PRE-first-byte window (ms) — guuey#409: a turn that never receives
+   * ANY byte (an invoke-rail death upstream of the pod, or an in-pod
+   * pre-spawn hang) previously showed "Thinking…" forever with no error
+   * item; this window bounds it. Much longer than `windowMs` on purpose —
+   * the transport's cold-start retries legitimately spend up to ~90s before
+   * the first byte. Default 120000.
+   */
+  preFirstByteWindowMs?: number;
   /**
    * Fruitless probes (history shows the turn still in flight, or no probe is
    * possible) before the turn fails with `CLIENT_ERROR_CODES.STREAM_STALLED`.

package/src/useAgentInvoke.ts

@@ -76,15 +76,29 @@ export function applyHistoryResult(
 }
 
 /** The guuey#192 stall watchdog's resolved tuning (see {@link stallProbeDecision}). */
-export const STALL_RECOVERY_DEFAULTS = { windowMs: 25_000, probeAttempts: 4 } as const;
+export const STALL_RECOVERY_DEFAULTS = {
+  windowMs: 25_000,
+  probeAttempts: 4,
+  /**
+   * guuey#409: the PRE-first-byte watchdog window. The #192 clock arms only
+   * on the first chunk (so a silent cold start never trips it) — which left
+   * a turn that never receives ANY byte with no watchdog at all: the
+   * eternal-"Thinking…" face of the 2026-08-22 invoke-rail turn death.
+   * Deliberately much longer than `windowMs`: the transport's cold-start
+   * retries legitimately spend up to ~90s before the first byte.
+   */
+  preFirstByteWindowMs: 120_000,
+} as const;
 
 function resolveStallRecovery(
   option: false | StallRecoveryOptions | undefined,
-): { windowMs: number; probeAttempts: number } | null {
+): { windowMs: number; probeAttempts: number; preFirstByteWindowMs: number } | null {
   if (option === false) return null;
   return {
     windowMs: option?.windowMs ?? STALL_RECOVERY_DEFAULTS.windowMs,
     probeAttempts: option?.probeAttempts ?? STALL_RECOVERY_DEFAULTS.probeAttempts,
+    preFirstByteWindowMs:
+      option?.preFirstByteWindowMs ?? STALL_RECOVERY_DEFAULTS.preFirstByteWindowMs,
   };
 }
 
@@ -399,13 +413,20 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
           stallTimer = null;
         }
       };
-      const armStallTimer = (): void => {
+      const armStallTimer = (windowMs?: number): void => {
         if (!stall || turnEnded || controller.signal.aborted) return;
         clearStallTimer();
         stallTimer = setTimeout(() => {
           void onStallWindow();
-        }, stall.windowMs);
+        }, windowMs ?? stall.windowMs);
       };
+      // guuey#409: arm BEFORE the first byte — a turn that never receives
+      // any chunk (rail death upstream of the pod, or an in-pod pre-spawn
+      // hang) otherwise shows "Thinking…" forever with no error item. The
+      // long window keeps silent cold starts un-tripped; expiry runs the
+      // SAME probe-then-adopt-or-STREAM_STALLED machinery as mid-stream
+      // stalls — one face fix for both mechanisms.
+      armStallTimer(stall?.preFirstByteWindowMs);
       const endTurnWith = (apply: () => void): void => {
         turnEnded = true;
         clearStallTimer();

package/src/web-adapters.ts

@@ -18,7 +18,9 @@ import {
 import type { AgHitlAnswer } from "@silverprotocol/core";
 import type { AgentInvokeAdapters, InvokeTransport, ThreadIdStore } from "./types.js";
 import { fetchThreadHistory, HistoryUnauthorizedError } from "./history.js";
-import { fetchStreamTransport, sendableGuestSecret, GUEST_HEADER } from "./transport.js";
+import {
+fetchStreamTransport, sendableGuestSecret, GUEST_HEADER } from "./transport.js";
+import type { SaturationRetryOptions } from "./saturation-retry.js";
 import { toInvokeUrl } from "./invoke-turn.js";
 
 /** Persists the threadId in `window.localStorage` (synchronously). */
@@ -55,6 +57,16 @@ export interface CreateWebAdaptersOptions {
    * omitted, no history adapter is installed and reloads start empty.
    */
   apiBaseUrl?: string;
+  /**
+   * Total send attempts on a saturated pod (guuey#406) — forwarded to
+   * {@link SaturationRetryOptions.attempts}. End-user surfaces facing
+   * capacity-1 pods (demo fixtures, xs plans) budget higher than the
+   * 2-attempt default and pair it with {@link onSaturationWait} so the
+   * wait is a visible busy state.
+   */
+  saturationAttempts?: number;
+  /** Forwarded to {@link SaturationRetryOptions.onSaturationWait}. */
+  onSaturationWait?: SaturationRetryOptions["onSaturationWait"];
   /**
    * Resolve the caller's Cognito access token (fresh), or `null` when signed
    * out. When a token is present the chat transport AND the history read
@@ -139,6 +151,10 @@ export function createWebAdapters(
     // resolves inside its generator).
     yield* fetchStreamTransport(req, null, getGuestSecret ? getGuestSecret() : null, {
       getBearer: getAccessToken,
+      ...(opts.saturationAttempts !== undefined ? { attempts: opts.saturationAttempts } : {}),
+      ...(opts.onSaturationWait !== undefined
+        ? { onSaturationWait: opts.onSaturationWait }
+        : {}),
     });
   };