@guuey/agent-client 0.3.1 → 0.5.0

package/dist/web-adapters.js

@@ -6,25 +6,9 @@
  * functions — never at module load — so this file is import-safe under SSR
  * (the functions guard on `typeof window`).
  */
-import { createMcpUiResourceReader, } from "@guuey/mcp-apps-host";
-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 {
-    status;
-    code;
-    constructor(message, status, code) {
-        super(message);
-        this.status = status;
-        this.code = code;
-        this.name = "AgentResponseError";
-    }
-}
+import { createMcpUiActionRelay, createMcpUiResourceReader, } from "@guuey/mcp-apps-host";
+import { fetchThreadHistory, HistoryUnauthorizedError } from "./history.js";
+import { fetchStreamTransport, sendableGuestSecret, GUEST_HEADER } from "./transport.js";
 /** Persists the threadId in `window.localStorage` (synchronously). */
 export const localStorageThreadStore = {
     load(key) {
@@ -55,108 +39,6 @@ export function webGenerateId() {
     }
     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) {
-    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, accessToken, guestSecret) {
-    const headers = {
-        "Content-Type": "application/json",
-        Accept: "text/event-stream",
-    };
-    const init = {
-        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 = await resp.json().catch(() => null);
-        let message = `agent responded ${resp.status}`;
-        let code;
-        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 });
-    }
-}
 /**
  * Build the web host-adapter bundle for {@link useAgentInvoke}. Pass an
  * access-token resolver and/or a guest-secret resolver (plus the read-plane
@@ -167,10 +49,16 @@ export async function* fetchStreamTransport(req, accessToken, guestSecret) {
 export function createWebAdapters(opts = {}) {
     const { apiBaseUrl, getAccessToken, getGuestSecret } = opts;
     const transport = 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 = {
         storage: localStorageThreadStore,
@@ -310,3 +198,64 @@ export function createUiResourceReader(options) {
     };
     return createMcpUiResourceReader({ readResource });
 }
+/**
+ * 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) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const callTool = async (uri, name, args) => {
+        const headers = { "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;
+        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());
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return createMcpUiActionRelay({ callTool });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/agent-client",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "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",
@@ -25,11 +25,17 @@
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js",
       "default": "./dist/react.js"
+    },
+    "./transport": {
+      "react-native": "./src/transport.ts",
+      "types": "./dist/transport.d.ts",
+      "import": "./dist/transport.js",
+      "default": "./dist/transport.js"
     }
   },
   "dependencies": {
     "@silverprotocol/core": "0.4.1",
-    "@guuey/mcp-apps-host": "0.3.1"
+    "@guuey/mcp-apps-host": "0.5.0"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -56,14 +62,14 @@
     "client"
   ],
   "homepage": "https://guuey.com",
-  "bugs": {
-    "url": "https://github.com/loqu-co/guuey/issues"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/withguuey/guuey-sdks.git",
     "directory": "packages/agent-client"
   },
+  "bugs": {
+    "url": "https://github.com/withguuey/guuey-sdks/issues"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc --watch",

package/src/error-codes.ts

@@ -0,0 +1,89 @@
+/**
+ * The pod's error-envelope wire codes, TRANSCRIBED.
+ *
+ * The source of truth is the runtime's own private module
+ * (`backend/services/nocode-runtime/src/error-codes.ts`). This package is
+ * published to npm and cannot take a `@guuey-private` dependency, so it keeps
+ * its own copy — the same arrangement as {@link GUEST_HEADER} in
+ * `./web-adapters.ts` and `@guuey/host`'s mirrored fs-contract constants. The
+ * copies are not trusted to prose alone: `agent-client-codes.sync.test.ts` in
+ * the runtime package (which can import BOTH) asserts they stay identical, so
+ * renaming a code on either side fails that test rather than silently breaking
+ * a client branch.
+ *
+ * WIRE CONTRACT (what these codes appear in):
+ *
+ *  - a pre-stream refusal — `{ "code": …, "message": … }` with an HTTP status,
+ *    parsed into {@link AgentResponseError};
+ *  - an in-band failure — `event: error` / `data: { code, message }`, surfaced
+ *    as `useAgentInvoke`'s `errorCode`.
+ *
+ * Both channels carry the SAME vocabulary, which is why one mirror serves them.
+ */
+export const AGENT_ERROR_CODES = {
+  /** No usable identity on a surface that requires one. */
+  UNAUTHORIZED: "UNAUTHORIZED",
+  /** The invoke body did not parse / validate. */
+  INVALID_REQUEST: "INVALID_REQUEST",
+  /** The builder turned anonymous access off for this agent. */
+  GUEST_ACCESS_DISABLED: "GUEST_ACCESS_DISABLED",
+  /**
+   * The agent's own definition declares `auth: 'required'` and the caller is
+   * anonymous — sign in and retry with a bearer. The snapshot-declared twin of
+   * {@link AGENT_ERROR_CODES.GUEST_ACCESS_DISABLED} (the app-record runtime
+   * override); either gate can refuse.
+   */
+  AUTH_REQUIRED: "AUTH_REQUIRED",
+  /** The caller (or the app) is out of plan allowance — the upgrade prompt. */
+  QUOTA_EXCEEDED: "QUOTA_EXCEEDED",
+  /** The app hit its builder-set managed spend cap. */
+  MANAGED_SPEND_CAP: "MANAGED_SPEND_CAP",
+  /**
+   * The pod is at its concurrent-turn cap (scaling S1-F3). A 503 carrying a
+   * `Retry-After` hint, and the ONE code {@link fetchStreamTransport} retries
+   * by itself — see its docblock for the single-attempt rule.
+   */
+  POD_SATURATED: "POD_SATURATED",
+  /**
+   * The pod took SIGTERM and refuses NEW turns while in-flight ones finish.
+   * Also a 503 + `Retry-After`, but deliberately NOT auto-retried (the
+   * endpoint pull re-routes the next request; retrying into the same pod is
+   * the one thing guaranteed not to help).
+   */
+  DRAINING: "DRAINING",
+  /** Refused for this caller — e.g. the link-prompt dismiss route's byo-only rule. */
+  FORBIDDEN: "FORBIDDEN",
+  /** The turn ran past the pod's wall-clock budget. */
+  TIMEOUT: "TIMEOUT",
+  /** A guuey-side dependency failed (not the agent's own code). */
+  PLATFORM_ERROR: "PLATFORM_ERROR",
+  /** Unclassified pod failure. */
+  INTERNAL: "INTERNAL",
+} as const;
+
+/** One of the pod's wire codes — see {@link AGENT_ERROR_CODES}. */
+export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[keyof typeof AGENT_ERROR_CODES];
+
+/**
+ * CLIENT-originated failure codes — minted by THIS SDK, never by the pod.
+ *
+ * Deliberately a SEPARATE constant from {@link AGENT_ERROR_CODES}: that
+ * object is a transcribed mirror of the runtime's wire vocabulary, guarded by
+ * the runtime-side `agent-client-codes.sync.test.ts` — adding a code the pod
+ * never emits there would both break the sync guard and lie about the wire.
+ * These codes surface through the SAME `errorCode` channel (it is a plain
+ * `string` for exactly this kind of growth), so consumers branch the same
+ * way; the split exists so each vocabulary keeps one honest owner.
+ */
+export const CLIENT_ERROR_CODES = {
+  /**
+   * The SSE stream went byte-silent mid-turn and bounded history probes never
+   * found the finished reply (guuey#192's stall watchdog giving up). The turn
+   * is over (`status` returns to `ready`); a retry or a reload may still find
+   * the reply if the backend completes later.
+   */
+  STREAM_STALLED: "STREAM_STALLED",
+} as const;
+
+/** One of this SDK's client-originated codes — see {@link CLIENT_ERROR_CODES}. */
+export type ClientErrorCode = (typeof CLIENT_ERROR_CODES)[keyof typeof CLIENT_ERROR_CODES];

package/src/errors.ts

@@ -0,0 +1,35 @@
+/**
+ * Error types the transports throw and the hook branches on.
+ *
+ * Its own module (rather than living in `./web-adapters.ts`) so `useAgentInvoke`
+ * — which must stay platform-agnostic — can `instanceof`-narrow a caught error
+ * without pulling the web adapter bundle (`fetch`, the history reader,
+ * `@guuey/mcp-apps-host`) into a React-Native build.
+ */
+
+/**
+ * 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. See `AGENT_ERROR_CODES` for the vocabulary.
+ */
+export class AgentResponseError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code?: string,
+    /**
+     * The response's `Retry-After` hint in whole seconds, when it sent a
+     * parseable one. The pod attaches it to its two 503 refusals
+     * (`POD_SATURATED`, `DRAINING`) and exposes the header across origins via
+     * `Access-Control-Expose-Headers`, so a browser client can actually read
+     * it. `undefined` when the header was absent, malformed, or in the
+     * HTTP-date form the pod never emits.
+     */
+    readonly retryAfterSeconds?: number,
+  ) {
+    super(message);
+    this.name = "AgentResponseError";
+  }
+}

package/src/history.ts

@@ -11,7 +11,7 @@
  * has its own copy today and can migrate onto this later.
  */
 import type { AgMessage, JsonValue } from "@silverprotocol/core";
-import type { AgentMessage, HistoryCard, HistoryLoadResult } from "./types";
+import type { AgentMessage, HistoryCard, HistoryLoadResult } from "./types.js";
 
 /** One row of `GET /v1/threads/:id/messages`. */
 export interface ThreadHistoryRow {

package/src/index.ts

@@ -6,18 +6,54 @@ export {
   parseConsentRequest,
   parseLinkRequest,
   type ParsedSseEvent,
-} from "./sse";
-export { dismissLinkPrompt } from "./link-prompt";
+} from "./sse.js";
+export { dismissLinkPrompt } from "./link-prompt.js";
+// One agent turn as a pure async generator — the wire walk `useAgentInvoke`
+// wraps, for hosts that drive their own turn state machine (guuey#186 G5).
+export { invokeTurn, toInvokeUrl, type InvokeTurnEvent } from "./invoke-turn.js";
 export {
+  createUiActionRelay,
+  type CreateUiActionRelayOptions,
   createUiResourceReader,
   type CreateUiResourceReaderOptions,
   createWebAdapters,
   localStorageThreadStore,
   webGenerateId,
-  fetchStreamTransport,
-  AgentResponseError,
   type CreateWebAdaptersOptions,
-} from "./web-adapters";
+} from "./web-adapters.js";
+// The invoke transport + guest-identity wire pieces, in their own
+// mcp-apps-host-free module. Consumers that want ONLY this graph (no
+// host-role card layer riding along) import `@guuey/agent-client/transport`
+// instead of the barrel — see that module's docblock (guuey#186 G2).
+export {
+  fetchStreamTransport,
+  sendableGuestSecret,
+  GUEST_HEADER,
+  withActivityObserver,
+  type FetchStreamTransportOptions,
+} from "./transport.js";
+// The invoke-refusal retry wrappers, transport-agnostic: a host that brings
+// its own `fetch` (Portal's React-Native transport) wraps them to wear the
+// same semantics as the web transport instead of hand-rolling second copies.
+// `parseRetryAfterSeconds` ships with them because filling
+// `AgentResponseError.retryAfterSeconds` the same way is what makes the
+// wrappers honour the pod's hint.
+export {
+  withSaturationRetry,
+  withColdStartRetry,
+  parseRetryAfterSeconds,
+  type SaturationRetryOptions,
+  type ColdStartRetryOptions,
+} from "./saturation-retry.js";
+export { AgentResponseError } from "./errors.js";
+// The pod's wire-code vocabulary, mirrored — branch on these instead of
+// re-typing the string literals (see the module docblock for the sync guard).
+export {
+  AGENT_ERROR_CODES,
+  type AgentErrorCode,
+  CLIENT_ERROR_CODES,
+  type ClientErrorCode,
+} from "./error-codes.js";
 export {
   fetchThreadHistory,
   threadHistoryRowsToMessages,
@@ -25,16 +61,19 @@ export {
   HistoryUnauthorizedError,
   type ThreadHistoryRow,
   type ThreadHistoryFetchOptions,
-} from "./history";
-export { ingestMessageFrame } from "./blocks";
+} from "./history.js";
+export { ingestMessageFrame } from "./blocks.js";
 // Pure block-walk / resource-narrowing helpers for a block-preserving renderer
 // (shared by Studio's `AgentBlocks` and Portal-web's agent chat). React-free.
 // Transcript labeling/ordering helpers (mount narrowing itself moved to
 // @guuey/mcp-apps-host — the SEP-1865 Host role package; import it directly).
-export { sortHistoryCards, toolNameFor } from "./history";
+export { sortHistoryCards, toolNameFor } from "./history.js";
 // Re-export the AgJSON types the block-preserving transcript surfaces, so
 // consumers can name `reduceResult` / block types without a direct
-// `@silverprotocol/core` import.
+// `@silverprotocol/core` import — and the `Reducer` CLASS beside them, so a
+// host folding `invokeTurn`'s agEvents outside the hook builds its transcript
+// on the same terms (the types alone forced the direct dep back, guuey#186 G4).
+export { Reducer } from "@silverprotocol/core";
 export type { AgEvent, AgReduceResult, AgMessage, AgBlock } from "@silverprotocol/core";
 export type {
   AgentMessage,
@@ -49,6 +88,7 @@ export type {
   AgentInvokeHistoryAdapter,
   AgentInvokeStatus,
   HistoryLoadResult,
+  StallRecoveryOptions,
   UseAgentInvokeOptions,
   UseAgentInvokeReturn,
-} from "./types";
+} from "./types.js";