@guuey/agent-client 0.6.1 → 0.7.0

package/dist/web-adapters.d.ts

@@ -104,7 +104,16 @@ export interface CreateUiResourceReaderOptions {
      * 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).
+     * 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). */
@@ -116,6 +125,8 @@ 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
  * doors — the pod door for LIVE turns (guuey#209 C1:

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;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;;;;;;;;;;OAUG;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;AAOD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CA4EjE;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

@@ -125,6 +125,12 @@ 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");
@@ -153,6 +159,14 @@ function toUiResourceUrl(endpointUrl) {
  */
 export function createUiResourceReader(options) {
     const fetchImpl = options.fetchImpl ?? fetch;
+    // 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

package/package.json

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

package/src/web-adapters.ts

@@ -220,7 +220,16 @@ export interface CreateUiResourceReaderOptions {
    * 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).
+   * 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). */
@@ -231,6 +240,13 @@ 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");
@@ -262,6 +278,16 @@ export function createUiResourceReader(
   options: CreateUiResourceReaderOptions,
 ): (resourceUri: string) => Promise<ResolvedViewMount | undefined> {
   const fetchImpl = options.fetchImpl ?? fetch;
+  // 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> => {