@guuey/agent-client 0.3.1 → 0.4.0

package/src/saturation-retry.ts

@@ -0,0 +1,150 @@
+/**
+ * The single `POD_SATURATED` auto-retry, as a transport-agnostic wrapper.
+ *
+ * Its own module — rather than living inside `./web-adapters.ts`, where it was
+ * born — because the behaviour is a property of the POD's refusal vocabulary,
+ * not of `fetch`. Every host that speaks `/agent/invoke` wants it, including
+ * the ones that cannot import the web adapter bundle: Portal's React-Native
+ * transport wraps its own `fetch` call with {@link withSaturationRetry} the
+ * same way `fetchStreamTransport` wraps its browser streaming reader, so the
+ * two wear byte-identical retry semantics instead of two hand-written copies
+ * that drift.
+ *
+ * This module imports only `./types.js`, `./errors.js` and `./error-codes.js`
+ * — all pure — so pulling it in costs a React-Native build nothing.
+ */
+import { AGENT_ERROR_CODES } from "./error-codes.js";
+import { AgentResponseError } from "./errors.js";
+import type { InvokeRequest, InvokeTransport } from "./types.js";
+
+/**
+ * Fallback wait before the saturation retry when the pod sent no usable
+ * `Retry-After` — the same 15s the pod's governor hints today
+ * (`GOVERNOR_RETRY_AFTER_SECONDS`), so a stripped header behaves like the
+ * normal case rather than hammering.
+ */
+const SATURATION_FALLBACK_DELAY_SECONDS = 15;
+
+/**
+ * Ceiling on the honoured hint. A pod that (mis)configures a multi-minute
+ * `Retry-After` must not park a chat UI in `connecting` for that long — past
+ * this the user is better served by the visible failure they can act on.
+ */
+const SATURATION_MAX_DELAY_SECONDS = 30;
+
+/**
+ * Read `Retry-After` as WHOLE SECONDS, or `undefined`.
+ *
+ * HTTP also allows an absolute HTTP-date, which is deliberately NOT parsed:
+ * the pod only ever emits a delta-seconds integer, and silently mis-reading a
+ * date as `NaN` seconds is worse than falling back to the fixed delay.
+ *
+ * Exported because every transport that builds an {@link AgentResponseError}
+ * has to fill `retryAfterSeconds` the same way for {@link withSaturationRetry}
+ * to honour the same hint — a second hand-rolled regex in a host adapter is
+ * exactly the drift this module exists to prevent.
+ */
+export function parseRetryAfterSeconds(header: string | null): number | undefined {
+  if (header === null) return undefined;
+  const trimmed = header.trim();
+  if (!/^\d+$/.test(trimmed)) return undefined;
+  const seconds = Number(trimmed);
+  return Number.isSafeInteger(seconds) ? seconds : undefined;
+}
+
+/** How long to wait before the single saturation retry, in milliseconds. */
+function saturationDelayMs(retryAfterSeconds: number | undefined): number {
+  const hinted = retryAfterSeconds ?? SATURATION_FALLBACK_DELAY_SECONDS;
+  return Math.min(hinted, SATURATION_MAX_DELAY_SECONDS) * 1000;
+}
+
+/**
+ * Wait `ms`, or resolve early if the turn is aborted — a user who hits stop
+ * must not sit through the remainder of a 15s backoff before the UI settles.
+ */
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const finish = (): void => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", finish);
+      resolve();
+    };
+    const timer = setTimeout(finish, ms);
+    signal.addEventListener("abort", finish, { once: true });
+  });
+}
+
+/** Options for {@link withSaturationRetry}. */
+export interface SaturationRetryOptions {
+  /**
+   * The saturation-retry wait. Injectable so tests drive the retry without a
+   * real 15s timer; production uses an abort-aware `setTimeout`.
+   */
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+
+/**
+ * Wrap an invoke transport with ONE automatic retry on a saturated pod.
+ *
+ * ## What retries, and what deliberately does not
+ *
+ * `POD_SATURATED` (503) means the pod is at its concurrent-turn cap right now
+ * — a transient queue state that clears as in-flight turns finish, so a single
+ * delayed re-send usually just works. The wait is the pod's own `Retry-After`
+ * hint (via {@link AgentResponseError.retryAfterSeconds}), defaulting to 15s
+ * when it sent none and capped at 30s.
+ *
+ * `DRAINING` (also 503 + `Retry-After`) is NOT retried in v1. The refusing pod
+ * is shutting down: its readiness probe is already failing and the endpoint
+ * pull is in flight, so the useful retry is the one that reaches a DIFFERENT
+ * pod — and a wrapped transport re-sends to the same URL. Retrying here would
+ * spend the user's 15s to arrive back at the same draining pod (or at a fresh
+ * one by luck), which is not a guarantee worth building on. When the retry can
+ * be made routing-aware, this is the code to revisit.
+ *
+ * Exactly ONE retry: a second saturation propagates as
+ * {@link AgentResponseError}, so a genuinely overloaded agent surfaces instead
+ * of looping. Nothing is retried once a chunk has been yielded — replaying
+ * mid-stream would duplicate a partial assistant turn (the same `yielded`
+ * guard the widget's `withIdentifiedToken` 401-retry uses). An abort during
+ * the wait skips the retry and surfaces the original refusal.
+ *
+ * The retry is INVISIBLE to `useAgentInvoke`: no frames were yielded, so the
+ * turn simply stays in `connecting` for the duration of the wait. There is no
+ * `retrying` status by design — the hook's state machine describes the pod's
+ * turn lifecycle, not the transport's plumbing.
+ *
+ * The wrapped transport is re-invoked from scratch for the retry, so a host
+ * that resolves identity inside its own generator (Portal's RN transport reads
+ * the bearer bridge per attempt) re-reads it on the second try rather than
+ * replaying a token that may have expired during the wait.
+ */
+export function withSaturationRetry(
+  transport: InvokeTransport,
+  options: SaturationRetryOptions = {},
+): InvokeTransport {
+  return async function* retrying(req: InvokeRequest): AsyncGenerator<string> {
+    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) 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/sse.ts

@@ -4,7 +4,7 @@
  * verbatim across web (Studio) and React-Native (Portal).
  */
 
-import type { ProfileConsentRequest, ProfileLinkRequest } from "./types";
+import type { ProfileConsentRequest, ProfileLinkRequest } from "./types.js";
 
 export interface ParsedSseEvent {
   event: string;

package/src/types.ts

@@ -159,9 +159,16 @@ export interface UseAgentInvokeOptions {
  *  - `responding` — assistant text is arriving (`text.start`/`text.delta`
  *    silver frames, or bypass text/assistant frames).
  *
- * Failure keeps its own channel ({@link UseAgentInvokeReturn.error}) — there
- * is deliberately no `error` status: after any terminal outcome the status
- * returns to `ready` so the composer re-enables.
+ * Failure keeps its own channel ({@link UseAgentInvokeReturn.error} +
+ * {@link UseAgentInvokeReturn.errorCode}) — there is deliberately no `error`
+ * status: after any terminal outcome the status returns to `ready` so the
+ * composer re-enables.
+ *
+ * There is likewise no `retrying` state. `fetchStreamTransport` retries a
+ * `POD_SATURATED` refusal once by itself, but that happens before any frame is
+ * yielded, so the turn stays in `connecting` for the backoff and the hook never
+ * learns it happened. This union describes the POD's turn lifecycle; transport
+ * plumbing does not belong in it.
  */
 export type AgentInvokeStatus = "ready" | "connecting" | "thinking" | "using-tool" | "responding";
 
@@ -174,6 +181,25 @@ export interface UseAgentInvokeReturn {
   /** The active tool's wire name while `status === 'using-tool'`, else null. */
   activeTool: string | null;
   error: string | null;
+  /**
+   * The pod's wire code for the failure in {@link error}, when it carried one
+   * — `QUOTA_EXCEEDED`, `POD_SATURATED`, `GUEST_ACCESS_DISABLED`, … (see
+   * `AGENT_ERROR_CODES`, and branch on those constants rather than re-typing
+   * the literals). `null` when there is no error, or when the failure had no
+   * code: a network drop, a host-adapter throw, or an `event: error` frame
+   * without one.
+   *
+   * Both failure channels feed it — the pre-stream refusal (thrown as
+   * `AgentResponseError`) and the in-band `event: error` frame — because the
+   * two carry the SAME vocabulary; a consumer branches once, not per channel.
+   * Set and cleared in lockstep with {@link error}: a new `send()`, `reset()`,
+   * or an app switch clears both.
+   *
+   * It is a `string`, not the `AgentErrorCode` union: the pod may ship a new
+   * code before a consumer upgrades this SDK, and a narrowed type would make
+   * that unrepresentable rather than merely unhandled.
+   */
+  errorCode: string | null;
   threadId: string | null;
   /** Abort the in-flight turn (the stream stops; partial text is kept). */
   abort: () => void;

package/src/useAgentInvoke.ts

@@ -2,7 +2,7 @@
  * useAgentInvoke — the base-platform chat client.
  *
  * Speaks the nocode-runtime pod's Bedrock-style SSE contract (NOT the parked
- * ggui generative-UI protocol that `@ggui-ai/react`'s useInvoke targets):
+ * ggui generative-UI protocol that `@ggui-ai/mcp-apps-react`'s useInvoke targets):
  *
  *   POST {endpointUrl}/agent/invoke
  *     body: { input, threadId?, clientMessageId }
@@ -29,8 +29,9 @@ import {
   parseSseEvents,
   reduceAssistantText,
   stringField,
-} from "./sse";
-import { ingestMessageFrame } from "./blocks";
+} from "./sse.js";
+import { ingestMessageFrame } from "./blocks.js";
+import { AgentResponseError } from "./errors.js";
 import type {
   AgentInvokeAdapters,
   AgentInvokeStatus,
@@ -41,7 +42,7 @@ import type {
   ProfileLinkRequest,
   UseAgentInvokeOptions,
   UseAgentInvokeReturn,
-} from "./types";
+} from "./types.js";
 
 function threadStorageKey(appId: string | undefined): string {
   return `guuey:thread:${appId ?? "default"}`;
@@ -78,6 +79,10 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
   const [status, setStatus] = useState<AgentInvokeStatus>("ready");
   const [activeTool, setActiveTool] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
+  // The pod's wire code for whatever put `error` there, when the failure
+  // carried one (see the return-type contract). Moves in lockstep with
+  // `error` — every set/clear of one touches the other.
+  const [errorCode, setErrorCode] = useState<string | null>(null);
   const [threadId, setThreadId] = useState<string | null>(null);
   // Opt-in block-preserving transcript. `reduceResult` follows the
   // null-until-first-valid-AgEvent contract documented on the return type: it
@@ -131,6 +136,7 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     setThreadId(null);
     setMessages([]);
     setError(null);
+    setErrorCode(null);
     setStatus("ready");
     setActiveTool(null);
     // Fresh conversation → drop the old fold; the reducer is rebuilt lazily on
@@ -221,6 +227,7 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     void adaptersRef.current.storage.save(threadStorageKey(appId), "");
     setMessages([]);
     setError(null);
+    setErrorCode(null);
     setStatus("ready");
     setActiveTool(null);
     // Re-create the reducer for the new conversation (rebuilt lazily on the
@@ -244,6 +251,7 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     async (input: string) => {
       if (!endpointUrl || !input.trim() || status !== "ready") return;
       setError(null);
+      setErrorCode(null);
       setStatus("connecting");
       setMessages((prev) => [...prev, { role: "user", text: input }, { role: "assistant", text: "" }]);
 
@@ -336,7 +344,12 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
                 }
               }
             } else if (ev.event === "error") {
+              // In-band failure frame — one of the two channels that carry the
+              // pod's wire code (the other is the pre-stream refusal caught
+              // below). A frame without a `code` clears it rather than leaving
+              // a previous turn's code standing beside a new message.
               setError(stringField(ev.data, "message") ?? "agent error");
+              setErrorCode(stringField(ev.data, "code") ?? null);
             } else if (ev.event === "profile-consent-needed") {
               // Cross-app profile consent ask (T6). Only a well-formed payload
               // updates state; a malformed one is dropped, leaving any prior
@@ -357,6 +370,12 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
       } catch (e) {
         if (!controller.signal.aborted) {
           setError(e instanceof Error ? e.message : "failed to reach agent");
+          // Pre-stream refusals arrive as a thrown AgentResponseError carrying
+          // the pod's structured code (a transport-level saturation retry has
+          // already happened and failed by the time one surfaces here). Any
+          // other throw — a network drop, a host-adapter failure — has no wire
+          // code, so the field stays null beside the message.
+          setErrorCode(e instanceof AgentResponseError ? (e.code ?? null) : null);
         }
       } finally {
         setStatus("ready");
@@ -384,6 +403,7 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     status,
     activeTool,
     error,
+    errorCode,
     threadId,
     abort,
     reset,

package/src/web-adapters.ts

@@ -7,35 +7,27 @@
  * (the functions guard on `typeof window`).
  */
 import {
+  createMcpUiActionRelay,
   createMcpUiResourceReader,
   type McpResourceReadResult,
+  type McpToolCallResult,
+  type McpToolStructuredContent,
   type ResolvedViewMount,
+  type UiActionRequest,
 } from "@guuey/mcp-apps-host";
 import type {
   AgentInvokeAdapters,
   InvokeRequest,
   InvokeTransport,
   ThreadIdStore,
-} from "./types";
-import { fetchThreadHistory, HistoryUnauthorizedError } from "./history";
-
-/**
- * Thrown when the pod returns a non-2xx status on `/agent/invoke` (before any
- * SSE stream opens). Carries the pod's structured `{ code, message }` when
- * present — e.g. a `QUOTA_EXCEEDED` 429 whose message ("…reached its plan
- * generation limit…") the chat UI should surface — falling back to the bare
- * status for non-JSON failures.
- */
-export class AgentResponseError extends Error {
-  constructor(
-    message: string,
-    readonly status: number,
-    readonly code?: string,
-  ) {
-    super(message);
-    this.name = "AgentResponseError";
-  }
-}
+} from "./types.js";
+import { fetchThreadHistory, HistoryUnauthorizedError } from "./history.js";
+import { AgentResponseError } from "./errors.js";
+import {
+  parseRetryAfterSeconds,
+  withSaturationRetry,
+  type SaturationRetryOptions,
+} from "./saturation-retry.js";
 
 /** Persists the threadId in `window.localStorage` (synchronously). */
 export const localStorageThreadStore: ThreadIdStore = {
@@ -104,7 +96,11 @@ function sendableGuestSecret(secret: string | null | undefined): string | null {
 }
 
 /**
- * Web SSE transport. Exactly ONE identity carrier per request, in order:
+ * One invoke attempt: opens the request and yields decoded SSE chunks.
+ * {@link fetchStreamTransport} wraps this with the shared saturation retry —
+ * every behaviour below is per-attempt.
+ *
+ * Exactly ONE identity carrier per request, in order:
  *
  *  1. `accessToken` → `Authorization: Bearer` — the pod identifies the caller
  *     by their verified access token (the same identity the history read
@@ -122,7 +118,7 @@ function sendableGuestSecret(secret: string | null | undefined): string | null {
  *
  * Reads the body via `ReadableStream.getReader()` (browser).
  */
-export async function* fetchStreamTransport(
+async function* streamInvokeOnce(
   req: InvokeRequest,
   accessToken?: string | null,
   guestSecret?: string | null,
@@ -161,7 +157,12 @@ export async function* fetchStreamTransport(
         code = body.code;
       }
     }
-    throw new AgentResponseError(message, resp.status, code);
+    throw new AgentResponseError(
+      message,
+      resp.status,
+      code,
+      parseRetryAfterSeconds(resp.headers.get("Retry-After")),
+    );
   }
   const reader = resp.body.getReader();
   const decoder = new TextDecoder();
@@ -172,6 +173,26 @@ export async function* fetchStreamTransport(
   }
 }
 
+/**
+ * The web SSE transport: {@link streamInvokeOnce} under the shared
+ * {@link withSaturationRetry} wrapper. Every consumer of this transport
+ * (Studio, the widget, anything built on {@link createWebAdapters}) therefore
+ * inherits the single `POD_SATURATED` retry, and inherits the SAME one Portal's
+ * React-Native transport wears — see that wrapper's docblock for which refusals
+ * retry, which deliberately do not, and why the retry is invisible to the hook.
+ */
+export function fetchStreamTransport(
+  req: InvokeRequest,
+  accessToken?: string | null,
+  guestSecret?: string | null,
+  options: SaturationRetryOptions = {},
+): AsyncIterable<string> {
+  return withSaturationRetry(
+    (attempt) => streamInvokeOnce(attempt, accessToken, guestSecret),
+    options,
+  )(req);
+}
+
 export interface CreateWebAdaptersOptions {
   /**
    * Public read-plane base (ending in `/v1`) for transcript history. When
@@ -406,3 +427,80 @@ export function createUiResourceReader(
   };
   return createMcpUiResourceReader({ readResource });
 }
+
+/** Options for {@link createUiActionRelay} — same credential surface as the reader. */
+export interface CreateUiActionRelayOptions {
+  /** The guuey public API base (`…/v1`). */
+  apiBaseUrl: string;
+  /** The thread whose persisted cards this relay may act for. */
+  threadId: string;
+  /** Signed-in bearer — wins over the guest secret (same rule as the transport). */
+  getAccessToken?: (opts?: { forceRefresh?: boolean }) => Promise<string | null>;
+  /** Caller-owned anonymous guest secret (widget / guest chat). */
+  guestSecret?: string | null;
+  /** Injectable for tests. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Build the card action relay over guuey's authenticated `tools/call` proxy
+ * (guuey#158: `POST /v1/threads/:threadId/ui-action`) — the mirror of
+ * {@link createUiResourceReader}. Allowlisting, arm narrowing, and the
+ * never-reject contract live in `@guuey/mcp-apps-host`'s
+ * `createMcpUiActionRelay`; only the transport is guuey-shaped. The proxy
+ * owns EVERYTHING trust-shaped (identity, thread ownership, the
+ * locator-to-thread guard, its own server-side allowlist, the per-user
+ * federation mint) — and every non-OK here collapses to `undefined`, which
+ * the host relay answers in-band as an `isError` result, never a thrown
+ * error into the sandbox bridge.
+ */
+export function createUiActionRelay(
+  options: CreateUiActionRelayOptions,
+): (request: UiActionRequest) => Promise<McpToolCallResult> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const callTool = async (
+    uri: string,
+    name: string,
+    args: McpToolStructuredContent | undefined,
+  ): Promise<unknown> => {
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    const token = options.getAccessToken ? await options.getAccessToken() : null;
+    const guest = sendableGuestSecret(options.guestSecret);
+    if (token) {
+      headers["authorization"] = `Bearer ${token}`;
+    } else if (guest) {
+      headers[GUEST_HEADER] = guest;
+    }
+    const requestUrl = `${options.apiBaseUrl}/threads/${encodeURIComponent(options.threadId)}/ui-action`;
+    const body = JSON.stringify({ uri, name, ...(args !== undefined ? { arguments: args } : {}) });
+    let res: Response;
+    try {
+      res = await fetchImpl(requestUrl, { method: "POST", headers, body });
+    } catch {
+      return undefined; // transport failure — the host relay answers in-band
+    }
+    // One forceRefresh retry on 401 with a bearer in play — the same
+    // expired-but-refreshable recovery the reader performs.
+    if (res.status === 401 && options.getAccessToken) {
+      const fresh = await options.getAccessToken({ forceRefresh: true }).catch(() => null);
+      if (fresh) {
+        try {
+          res = await fetchImpl(requestUrl, {
+            method: "POST",
+            headers: { ...headers, authorization: `Bearer ${fresh}` },
+            body,
+          });
+        } catch {
+          return undefined;
+        }
+      }
+    }
+    if (!res.ok) return undefined;
+    try {
+      return (await res.json()) as unknown;
+    } catch {
+      return undefined;
+    }
+  };
+  return createMcpUiActionRelay({ callTool });
+}