@guuey/agent-client 0.6.0 → 0.7.0

package/dist/web-adapters.d.ts

@@ -95,6 +95,27 @@ export interface CreateUiResourceReaderOptions {
     apiBaseUrl: string;
     /** The thread whose persisted locators this reader may resolve. */
     threadId: string;
+    /**
+     * The pod base (or full invoke URL — same normalization as the invoke
+     * transport). When set, the reader tries the POD door first
+     * (`GET <base>/agent/ui-resource`, guuey#209 C1): the pod is the only
+     * party that can vouch for a locator whose turn is still streaming —
+     * persisted `kind:'card'` rows land at turn COMPLETION, so the platform
+     * door 404s mid-turn by construction. Completed turns 404 on the pod
+     * (past its grace window) and resolve on the platform door instead: one
+     * authority per lifecycle phase, and this reader tries both in that
+     * order. Absent → platform door only (pre-#209 behavior) — which means
+     * **a card produced mid-turn cannot resolve until its turn completes**:
+     * under a producer that inlines no mount material (any plain-locator MCP
+     * server, ggui's read-plane-only posture) every fresh card renders
+     * "expired" until reload. A live surface that holds an invoke endpoint
+     * MUST pass it here; omitting it is only correct for a pure history
+     * viewer with no pod (SelfHostedThreadViewer). The reader warns once at
+     * construction when a platform door is configured without a pod door,
+     * because the failure it prevents is silent by nature (guuey#209 /
+     * ggui cac966a2d — both first external embeds shipped without it).
+     */
+    endpointUrl?: string | null;
     /** Signed-in bearer — wins over the guest secret (same rule as the transport). */
     getAccessToken?: (opts?: {
         forceRefresh?: boolean;
@@ -104,19 +125,29 @@ export interface CreateUiResourceReaderOptions {
     /** Injectable for tests. */
     fetchImpl?: typeof fetch;
 }
+/** @internal test seam — the once-flag is module state; suites reset it between cases. */
+export declare function __resetReaderEndpointWarning(): void;
 /**
- * Build a `UiResourceReader` over guuey's authenticated resources/read proxy
- * (guuey#122 Gap 1: `GET /v1/threads/:threadId/ui-resource?uri=…`).
+ * Build a `UiResourceReader` over guuey's authenticated resources/read
+ * doors — the pod door for LIVE turns (guuey#209 C1:
+ * `GET <pod>/agent/ui-resource?uri=…`, when {@link CreateUiResourceReaderOptions.endpointUrl}
+ * is set) and the platform proxy for persisted locators (guuey#122 Gap 1:
+ * `GET /v1/threads/:threadId/ui-resource?uri=…`). Both doors answer the
+ * same body and speak the same identity (bearer wins, guest header
+ * otherwise — the pod's `resolveIdentity` and the proxy's identity chain
+ * accept the identical carriers), so one parse serves both.
  *
  * This is `@guuey/mcp-apps-host`'s `createMcpUiResourceReader` assembly over
  * a guuey-platform transport (guuey#127) — channel resolution and payload
  * narrowing live in the host package; only the transport is guuey-shaped.
- * The proxy owns EVERYTHING trust-shaped: caller identity (the same three
- * families as the history read), thread ownership, the locator-to-thread
- * scope guard, and the per-user federation mint. This transport only carries
- * the surface's existing credential and maps EVERY non-OK — 401/403/404/502
- * alike — to `undefined`: deny is byte-identical to a miss, and a miss
- * renders the host's placeholder, never an error surface.
+ * The doors own EVERYTHING trust-shaped: caller identity (the same three
+ * families as the history read), tenancy (the pod's live-card ledger; the
+ * proxy's thread-ownership + locator-to-thread scope guard), and the
+ * per-user federation mint. This transport only carries the surface's
+ * existing credential and maps EVERY non-OK — 401/403/404/502 alike — to
+ * "try the next door", and a miss on the last door to `undefined`: deny is
+ * byte-identical to a miss, and a miss renders the host's placeholder,
+ * never an error surface.
  */
 export declare function createUiResourceReader(options: CreateUiResourceReaderOptions): (resourceUri: string) => Promise<ResolvedViewMount | undefined>;
 /** Options for {@link createUiActionRelay} — same credential surface as the reader. */

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

@@ -1 +1 @@
-{"version":3,"file":"web-adapters.d.ts","sourceRoot":"","sources":["../src/web-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAIL,KAAK,iBAAiB,EAEtB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAmB,aAAa,EAAE,MAAM,YAAY,CAAC;AAItF,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,EAAE,aAiBrC,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE,wBAA6B,GAClC,mBAAmB,CA8ErB;AAED,mGAAmG;AACnG,MAAM,WAAW,6BAA6B;IAC5C,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAoDjE;AAED,uFAAuF;AACvF,MAAM,WAAW,0BAA0B;IACzC,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CA+C1D"}
+{"version":3,"file":"web-adapters.d.ts","sourceRoot":"","sources":["../src/web-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAIL,KAAK,iBAAiB,EAEtB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,mBAAmB,EAAmB,aAAa,EAAE,MAAM,YAAY,CAAC;AAKtF,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,EAAE,aAiBrC,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE,wBAA6B,GAClC,mBAAmB,CA8ErB;AAED,mGAAmG;AACnG,MAAM,WAAW,6BAA6B;IAC5C,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kFAAkF;IAClF,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAID,0FAA0F;AAC1F,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAOD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAsFjE;AAED,uFAAuF;AACvF,MAAM,WAAW,0BAA0B;IACzC,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CA+C1D"}

package/dist/web-adapters.js

@@ -9,6 +9,7 @@
 import { createMcpUiActionRelay, createMcpUiResourceReader, } from "@guuey/mcp-apps-host";
 import { fetchThreadHistory, HistoryUnauthorizedError } from "./history.js";
 import { fetchStreamTransport, sendableGuestSecret, GUEST_HEADER } from "./transport.js";
+import { toInvokeUrl } from "./invoke-turn.js";
 /** Persists the threadId in `window.localStorage` (synchronously). */
 export const localStorageThreadStore = {
     load(key) {
@@ -124,24 +125,59 @@ export function createWebAdapters(opts = {}) {
     }
     return adapters;
 }
+/** Warn once per module load — the misconfiguration is per-surface, not per-read. */
+let readerEndpointWarned = false;
+/** @internal test seam — the once-flag is module state; suites reset it between cases. */
+export function __resetReaderEndpointWarning() {
+    readerEndpointWarned = false;
+}
+/** `<pod base>/agent/ui-resource` from whatever endpoint shape the surface holds. */
+function toUiResourceUrl(endpointUrl) {
+    return toInvokeUrl(endpointUrl).replace(/\/agent\/invoke$/, "/agent/ui-resource");
+}
 /**
- * Build a `UiResourceReader` over guuey's authenticated resources/read proxy
- * (guuey#122 Gap 1: `GET /v1/threads/:threadId/ui-resource?uri=…`).
+ * Build a `UiResourceReader` over guuey's authenticated resources/read
+ * doors — the pod door for LIVE turns (guuey#209 C1:
+ * `GET <pod>/agent/ui-resource?uri=…`, when {@link CreateUiResourceReaderOptions.endpointUrl}
+ * is set) and the platform proxy for persisted locators (guuey#122 Gap 1:
+ * `GET /v1/threads/:threadId/ui-resource?uri=…`). Both doors answer the
+ * same body and speak the same identity (bearer wins, guest header
+ * otherwise — the pod's `resolveIdentity` and the proxy's identity chain
+ * accept the identical carriers), so one parse serves both.
  *
  * This is `@guuey/mcp-apps-host`'s `createMcpUiResourceReader` assembly over
  * a guuey-platform transport (guuey#127) — channel resolution and payload
  * narrowing live in the host package; only the transport is guuey-shaped.
- * The proxy owns EVERYTHING trust-shaped: caller identity (the same three
- * families as the history read), thread ownership, the locator-to-thread
- * scope guard, and the per-user federation mint. This transport only carries
- * the surface's existing credential and maps EVERY non-OK — 401/403/404/502
- * alike — to `undefined`: deny is byte-identical to a miss, and a miss
- * renders the host's placeholder, never an error surface.
+ * The doors own EVERYTHING trust-shaped: caller identity (the same three
+ * families as the history read), tenancy (the pod's live-card ledger; the
+ * proxy's thread-ownership + locator-to-thread scope guard), and the
+ * per-user federation mint. This transport only carries the surface's
+ * existing credential and maps EVERY non-OK — 401/403/404/502 alike — to
+ * "try the next door", and a miss on the last door to `undefined`: deny is
+ * byte-identical to a miss, and a miss renders the host's placeholder,
+ * never an error surface.
  */
 export function createUiResourceReader(options) {
     const fetchImpl = options.fetchImpl ?? fetch;
-    const readResource = async (resourceUri) => {
+    // A platform door without a pod door is almost always a live surface
+    // that forgot `endpointUrl` — its cards would die silently for the whole
+    // mid-turn window. `null` is the explicit "I am a history-only viewer,
+    // there is no pod" opt-out; `undefined` is the forgotten case.
+    if (options.endpointUrl === undefined && !readerEndpointWarned) {
+        readerEndpointWarned = true;
+        console.warn("createUiResourceReader: no `endpointUrl` — cards produced mid-turn cannot resolve until the turn completes (the pod door is the only authority while a turn streams). Pass the surface's invoke endpoint, or `endpointUrl: null` to declare a history-only viewer.");
+    }
+    /** One door: fetch + the history adapter's 401-forceRefresh recovery + parse. */
+    const readDoor = async (requestUrl) => {
+        // Exactly ONE identity carrier per read, the invoke transport's rule
+        // (`streamInvokeOnce`): bearer → guest header → else cookie credentials,
+        // which round-trip the HttpOnly `guuey_guest` cookie the pod mints for
+        // anonymous browser callers. Without the third arm a cookie-mode guest
+        // sent an identity-less read and every locator rendered as expired
+        // (guuey#221). Never two at once: a request carrying either header does
+        // NOT also send cookies.
         const headers = {};
+        const init = { headers };
         const token = options.getAccessToken ? await options.getAccessToken() : null;
         const guest = sendableGuestSecret(options.guestSecret);
         if (token) {
@@ -150,17 +186,20 @@ export function createUiResourceReader(options) {
         else if (guest) {
             headers[GUEST_HEADER] = guest;
         }
-        const requestUrl = `${options.apiBaseUrl}/threads/${encodeURIComponent(options.threadId)}/ui-resource?uri=${encodeURIComponent(resourceUri)}`;
+        else {
+            init.credentials = "include";
+        }
         let res;
         try {
-            res = await fetchImpl(requestUrl, { headers });
+            res = await fetchImpl(requestUrl, init);
         }
         catch {
-            return undefined; // transport failure == miss == placeholder
+            return undefined; // transport failure == miss (the next door may still answer)
         }
         // One forceRefresh retry on 401 with a bearer in play — the same
         // expired-but-refreshable recovery the history adapter performs;
-        // without it a stale token degrades to a permanent placeholder.
+        // without it a stale token degrades to a permanent placeholder. The
+        // retry carries the fresh bearer and nothing else (same one-carrier rule).
         if (res.status === 401 && options.getAccessToken) {
             const fresh = await options.getAccessToken({ forceRefresh: true }).catch(() => null);
             if (fresh) {
@@ -183,8 +222,8 @@ export function createUiResourceReader(options) {
         catch {
             return undefined;
         }
-        // The proxy passes the blob arm through (a blob-only resource is not
-        // silently a miss — its route contract); mirror that here.
+        // Both doors pass the blob arm through (a blob-only resource is not
+        // silently a miss — the route contract); mirror that here.
         if (typeof body.uri !== "string")
             return undefined;
         if (typeof body.text !== "string" && typeof body.blob !== "string")
@@ -196,6 +235,16 @@ export function createUiResourceReader(options) {
             ...(typeof body.blob === "string" ? { blob: body.blob } : {}),
         };
     };
+    const podUrl = options.endpointUrl ? toUiResourceUrl(options.endpointUrl) : null;
+    const readResource = async (resourceUri) => {
+        const query = `?uri=${encodeURIComponent(resourceUri)}`;
+        if (podUrl !== null) {
+            const live = await readDoor(`${podUrl}${query}`);
+            if (live !== undefined)
+                return live;
+        }
+        return readDoor(`${options.apiBaseUrl}/threads/${encodeURIComponent(options.threadId)}/ui-resource${query}`);
+    };
     return createMcpUiResourceReader({ readResource });
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/agent-client",
-  "version": "0.6.0",
+  "version": "0.7.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",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@silverprotocol/core": "0.5.0",
-    "@guuey/mcp-apps-host": "0.6.0"
+    "@guuey/mcp-apps-host": "0.7.0"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/web-adapters.ts

@@ -18,6 +18,7 @@ import {
 import type { AgentInvokeAdapters, InvokeTransport, ThreadIdStore } from "./types.js";
 import { fetchThreadHistory, HistoryUnauthorizedError } from "./history.js";
 import { fetchStreamTransport, sendableGuestSecret, GUEST_HEADER } from "./transport.js";
+import { toInvokeUrl } from "./invoke-turn.js";
 
 /** Persists the threadId in `window.localStorage` (synchronously). */
 export const localStorageThreadStore: ThreadIdStore = {
@@ -210,6 +211,27 @@ export interface CreateUiResourceReaderOptions {
   apiBaseUrl: string;
   /** The thread whose persisted locators this reader may resolve. */
   threadId: string;
+  /**
+   * The pod base (or full invoke URL — same normalization as the invoke
+   * transport). When set, the reader tries the POD door first
+   * (`GET <base>/agent/ui-resource`, guuey#209 C1): the pod is the only
+   * party that can vouch for a locator whose turn is still streaming —
+   * persisted `kind:'card'` rows land at turn COMPLETION, so the platform
+   * door 404s mid-turn by construction. Completed turns 404 on the pod
+   * (past its grace window) and resolve on the platform door instead: one
+   * authority per lifecycle phase, and this reader tries both in that
+   * order. Absent → platform door only (pre-#209 behavior) — which means
+   * **a card produced mid-turn cannot resolve until its turn completes**:
+   * under a producer that inlines no mount material (any plain-locator MCP
+   * server, ggui's read-plane-only posture) every fresh card renders
+   * "expired" until reload. A live surface that holds an invoke endpoint
+   * MUST pass it here; omitting it is only correct for a pure history
+   * viewer with no pod (SelfHostedThreadViewer). The reader warns once at
+   * construction when a platform door is configured without a pod door,
+   * because the failure it prevents is silent by nature (guuey#209 /
+   * ggui cac966a2d — both first external embeds shipped without it).
+   */
+  endpointUrl?: string | null;
   /** 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). */
@@ -218,43 +240,85 @@ export interface CreateUiResourceReaderOptions {
   fetchImpl?: typeof fetch;
 }
 
+/** Warn once per module load — the misconfiguration is per-surface, not per-read. */
+let readerEndpointWarned = false;
+/** @internal test seam — the once-flag is module state; suites reset it between cases. */
+export function __resetReaderEndpointWarning(): void {
+  readerEndpointWarned = false;
+}
+
+/** `<pod base>/agent/ui-resource` from whatever endpoint shape the surface holds. */
+function toUiResourceUrl(endpointUrl: string): string {
+  return toInvokeUrl(endpointUrl).replace(/\/agent\/invoke$/, "/agent/ui-resource");
+}
+
 /**
- * Build a `UiResourceReader` over guuey's authenticated resources/read proxy
- * (guuey#122 Gap 1: `GET /v1/threads/:threadId/ui-resource?uri=…`).
+ * Build a `UiResourceReader` over guuey's authenticated resources/read
+ * doors — the pod door for LIVE turns (guuey#209 C1:
+ * `GET <pod>/agent/ui-resource?uri=…`, when {@link CreateUiResourceReaderOptions.endpointUrl}
+ * is set) and the platform proxy for persisted locators (guuey#122 Gap 1:
+ * `GET /v1/threads/:threadId/ui-resource?uri=…`). Both doors answer the
+ * same body and speak the same identity (bearer wins, guest header
+ * otherwise — the pod's `resolveIdentity` and the proxy's identity chain
+ * accept the identical carriers), so one parse serves both.
  *
  * This is `@guuey/mcp-apps-host`'s `createMcpUiResourceReader` assembly over
  * a guuey-platform transport (guuey#127) — channel resolution and payload
  * narrowing live in the host package; only the transport is guuey-shaped.
- * The proxy owns EVERYTHING trust-shaped: caller identity (the same three
- * families as the history read), thread ownership, the locator-to-thread
- * scope guard, and the per-user federation mint. This transport only carries
- * the surface's existing credential and maps EVERY non-OK — 401/403/404/502
- * alike — to `undefined`: deny is byte-identical to a miss, and a miss
- * renders the host's placeholder, never an error surface.
+ * The doors own EVERYTHING trust-shaped: caller identity (the same three
+ * families as the history read), tenancy (the pod's live-card ledger; the
+ * proxy's thread-ownership + locator-to-thread scope guard), and the
+ * per-user federation mint. This transport only carries the surface's
+ * existing credential and maps EVERY non-OK — 401/403/404/502 alike — to
+ * "try the next door", and a miss on the last door to `undefined`: deny is
+ * byte-identical to a miss, and a miss renders the host's placeholder,
+ * never an error surface.
  */
 export function createUiResourceReader(
   options: CreateUiResourceReaderOptions,
 ): (resourceUri: string) => Promise<ResolvedViewMount | undefined> {
   const fetchImpl = options.fetchImpl ?? fetch;
-  const readResource = async (resourceUri: string): Promise<McpResourceReadResult | undefined> => {
+  // A platform door without a pod door is almost always a live surface
+  // that forgot `endpointUrl` — its cards would die silently for the whole
+  // mid-turn window. `null` is the explicit "I am a history-only viewer,
+  // there is no pod" opt-out; `undefined` is the forgotten case.
+  if (options.endpointUrl === undefined && !readerEndpointWarned) {
+    readerEndpointWarned = true;
+    console.warn(
+      "createUiResourceReader: no `endpointUrl` — cards produced mid-turn cannot resolve until the turn completes (the pod door is the only authority while a turn streams). Pass the surface's invoke endpoint, or `endpointUrl: null` to declare a history-only viewer.",
+    );
+  }
+
+  /** One door: fetch + the history adapter's 401-forceRefresh recovery + parse. */
+  const readDoor = async (requestUrl: string): Promise<McpResourceReadResult | undefined> => {
+    // Exactly ONE identity carrier per read, the invoke transport's rule
+    // (`streamInvokeOnce`): bearer → guest header → else cookie credentials,
+    // which round-trip the HttpOnly `guuey_guest` cookie the pod mints for
+    // anonymous browser callers. Without the third arm a cookie-mode guest
+    // sent an identity-less read and every locator rendered as expired
+    // (guuey#221). Never two at once: a request carrying either header does
+    // NOT also send cookies.
     const headers: Record<string, string> = {};
+    const init: RequestInit = { headers };
     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;
+    } else {
+      init.credentials = "include";
     }
-    const requestUrl = `${options.apiBaseUrl}/threads/${encodeURIComponent(options.threadId)}/ui-resource?uri=${encodeURIComponent(resourceUri)}`;
     let res: Response;
     try {
-      res = await fetchImpl(requestUrl, { headers });
+      res = await fetchImpl(requestUrl, init);
     } catch {
-      return undefined; // transport failure == miss == placeholder
+      return undefined; // transport failure == miss (the next door may still answer)
     }
     // One forceRefresh retry on 401 with a bearer in play — the same
     // expired-but-refreshable recovery the history adapter performs;
-    // without it a stale token degrades to a permanent placeholder.
+    // without it a stale token degrades to a permanent placeholder. The
+    // retry carries the fresh bearer and nothing else (same one-carrier rule).
     if (res.status === 401 && options.getAccessToken) {
       const fresh = await options.getAccessToken({ forceRefresh: true }).catch(() => null);
       if (fresh) {
@@ -274,8 +338,8 @@ export function createUiResourceReader(
     } catch {
       return undefined;
     }
-    // The proxy passes the blob arm through (a blob-only resource is not
-    // silently a miss — its route contract); mirror that here.
+    // Both doors pass the blob arm through (a blob-only resource is not
+    // silently a miss — the route contract); mirror that here.
     if (typeof body.uri !== "string") return undefined;
     if (typeof body.text !== "string" && typeof body.blob !== "string") return undefined;
     return {
@@ -285,6 +349,18 @@ export function createUiResourceReader(
       ...(typeof body.blob === "string" ? { blob: body.blob } : {}),
     };
   };
+
+  const podUrl = options.endpointUrl ? toUiResourceUrl(options.endpointUrl) : null;
+  const readResource = async (resourceUri: string): Promise<McpResourceReadResult | undefined> => {
+    const query = `?uri=${encodeURIComponent(resourceUri)}`;
+    if (podUrl !== null) {
+      const live = await readDoor(`${podUrl}${query}`);
+      if (live !== undefined) return live;
+    }
+    return readDoor(
+      `${options.apiBaseUrl}/threads/${encodeURIComponent(options.threadId)}/ui-resource${query}`,
+    );
+  };
   return createMcpUiResourceReader({ readResource });
 }