@guuey/agent-client 0.3.1 → 0.5.0

package/src/web-adapters.ts

@@ -7,35 +7,17 @@
  * (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";
-  }
-}
+import type { AgentInvokeAdapters, InvokeTransport, ThreadIdStore } from "./types.js";
+import { fetchThreadHistory, HistoryUnauthorizedError } from "./history.js";
+import { fetchStreamTransport, sendableGuestSecret, GUEST_HEADER } from "./transport.js";
 
 /** Persists the threadId in `window.localStorage` (synchronously). */
 export const localStorageThreadStore: ThreadIdStore = {
@@ -65,113 +47,6 @@ export function webGenerateId(): string {
   return `cmid-${Date.now()}-${Math.floor(Math.random() * 1e9)}`;
 }
 
-/**
- * Header carrying a caller-owned anonymous guest secret. A LOCAL MIRROR of the
- * two server-side constants — the pod's `GUEST_HEADER_NAME`
- * (`backend/services/nocode-runtime/src/identity.ts`) and the read plane's
- * `GUEST_HEADER` (`backend/amplify/functions/publicApi/identity.ts`) — because
- * this is a published npm package and cannot take a `@guuey-private` dep (same
- * arrangement as `@guuey/host`'s mirrored fs-contract constants). The string is
- * a wire contract: both planes already advertise it in
- * `Access-Control-Allow-Headers`, so changing it is a breaking protocol change,
- * not a rename.
- */
-const GUEST_HEADER = "x-guuey-guest";
-
-/**
- * A well-formed guest secret: exactly 32 bytes as 64 LOWERCASE hex chars —
- * the shape `crypto.getRandomValues` + hex-encoding mints.
- *
- * Deliberately stricter than the server's `/^[a-f0-9]{64}$/i` (pod
- * `identity.ts`, publicApi `identity.ts`): both sides lowercase before
- * hashing, so an uppercase secret would in fact be accepted, but the only
- * supported mint path emits lowercase and a non-canonical value means the
- * caller's storage is not what this adapter expects. Anything that fails is
- * IGNORED — the request falls through to cookie mode rather than sending a
- * secret the two identity planes might key differently.
- */
-const GUEST_SECRET_RE = /^[0-9a-f]{64}$/;
-
-/**
- * Narrow a caller-supplied guest secret to a value that is safe to put on the
- * wire, or `null`. The single gate for the header: every write of
- * {@link GUEST_HEADER} in this module goes through it, so a malformed secret
- * can never reach a request. The value is never logged (here or anywhere on
- * this path) — it IS the anonymous identity, so a leak is an impersonation.
- */
-function sendableGuestSecret(secret: string | null | undefined): string | null {
-  return typeof secret === "string" && GUEST_SECRET_RE.test(secret) ? secret : null;
-}
-
-/**
- * Web SSE transport. 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
- *     plane uses, so persisted threads round-trip on reload).
- *  2. a well-formed `guestSecret` → `x-guuey-guest` — the caller owns and
- *     persists its own anonymous secret. The path for hosts with no usable
- *     cookie jar: React-Native, and the embedded widget, whose third-party
- *     iframe cannot rely on the pod's cookie surviving browser partitioning.
- *     The pod never mints a cookie for a header client.
- *  3. neither → `credentials: "include"`, which round-trips the HttpOnly
- *     `guuey_guest` cookie the pod mints for anonymous browser callers.
- *
- * Never two at once: a bearer wins over a guest secret, and a request that
- * carries either header does NOT also send cookie credentials.
- *
- * Reads the body via `ReadableStream.getReader()` (browser).
- */
-export async function* fetchStreamTransport(
-  req: InvokeRequest,
-  accessToken?: string | null,
-  guestSecret?: string | null,
-): AsyncGenerator<string> {
-  const headers: Record<string, string> = {
-    "Content-Type": "application/json",
-    Accept: "text/event-stream",
-  };
-  const init: RequestInit = {
-    method: "POST",
-    signal: req.signal,
-    headers,
-    body: JSON.stringify(req.body),
-  };
-  const guest = sendableGuestSecret(guestSecret);
-  if (accessToken) {
-    headers.Authorization = `Bearer ${accessToken}`;
-  } else if (guest) {
-    headers[GUEST_HEADER] = guest;
-  } else {
-    init.credentials = "include";
-  }
-  const resp = await fetch(req.url, init);
-  if (!resp.ok || !resp.body) {
-    // Surface a structured pod error ({ code, message }) when present — e.g. a
-    // QUOTA_EXCEEDED 429 carries an upgrade message the UI should show. Fall
-    // back to the bare status for non-JSON failures.
-    const body: unknown = await resp.json().catch(() => null);
-    let message = `agent responded ${resp.status}`;
-    let code: string | undefined;
-    if (body !== null && typeof body === "object") {
-      if ("message" in body && typeof body.message === "string" && body.message) {
-        message = body.message;
-      }
-      if ("code" in body && typeof body.code === "string") {
-        code = body.code;
-      }
-    }
-    throw new AgentResponseError(message, resp.status, code);
-  }
-  const reader = resp.body.getReader();
-  const decoder = new TextDecoder();
-  for (;;) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    yield decoder.decode(value, { stream: true });
-  }
-}
-
 export interface CreateWebAdaptersOptions {
   /**
    * Public read-plane base (ending in `/v1`) for transcript history. When
@@ -253,10 +128,16 @@ export function createWebAdapters(
   const { apiBaseUrl, getAccessToken, getGuestSecret } = opts;
 
   const transport: InvokeTransport = async function* (req) {
-    const token = getAccessToken ? await getAccessToken() : null;
     // Both candidates go to the transport; it owns the precedence (and the
     // never-two-carriers rule) so there is exactly one place that decides.
-    yield* fetchStreamTransport(req, token, getGuestSecret ? getGuestSecret() : null);
+    // The bearer goes through as the PROVIDER, not a pre-resolved value:
+    // the transport re-asks it per attempt, so a cold-start retry after a
+    // backoff wait re-reads a fresh token instead of replaying one that may
+    // have expired during the wait (the same reason Portal's RN transport
+    // resolves inside its generator).
+    yield* fetchStreamTransport(req, null, getGuestSecret ? getGuestSecret() : null, {
+      getBearer: getAccessToken,
+    });
   };
 
   const adapters: AgentInvokeAdapters = {
@@ -406,3 +287,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 });
+}