@guuey/agent-client 0.3.1 → 0.5.0

package/dist/useAgentInvoke.js

@@ -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 }
@@ -23,8 +23,10 @@
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Reducer } from "@silverprotocol/core";
-import { parseConsentRequest, parseLinkRequest, parseSseEvents, reduceAssistantText, stringField, } from "./sse";
-import { ingestMessageFrame } from "./blocks";
+import { invokeTurn, toInvokeUrl } from "./invoke-turn.js";
+import { AgentResponseError } from "./errors.js";
+import { withActivityObserver } from "./transport.js";
+import { CLIENT_ERROR_CODES } from "./error-codes.js";
 function threadStorageKey(appId) {
     return `guuey:thread:${appId ?? "default"}`;
 }
@@ -42,6 +44,50 @@ export function applyHistoryResult(result, currentMessages) {
         return { kind: "skip" };
     return { kind: "seed", messages: result.messages };
 }
+/** The guuey#192 stall watchdog's resolved tuning (see {@link stallProbeDecision}). */
+export const STALL_RECOVERY_DEFAULTS = { windowMs: 25_000, probeAttempts: 4 };
+function resolveStallRecovery(option) {
+    if (option === false)
+        return null;
+    return {
+        windowMs: option?.windowMs ?? STALL_RECOVERY_DEFAULTS.windowMs,
+        probeAttempts: option?.probeAttempts ?? STALL_RECOVERY_DEFAULTS.probeAttempts,
+    };
+}
+/**
+ * Pure decision seam for the guuey#192 stall probe: does a freshly-loaded
+ * transcript already contain THIS turn's finished reply?
+ *
+ * `adopt` requires BOTH signals, because each alone lies in a real case:
+ *
+ *  - **user-count**: history must hold at least as many user turns as the
+ *    local transcript (which includes the just-sent optimistic one). Without
+ *    it, a thread whose PREVIOUS turn ended in a completed assistant reply
+ *    would adopt that OLD transcript and silently drop the in-flight turn.
+ *  - **finished tail**: history's last message must be a non-empty assistant
+ *    reply. Without it, a history read that caught the persisted user row
+ *    before the assistant row would adopt a reply-less transcript.
+ *
+ * KNOWN LIMIT (documented, accepted): the runtime persists a turn's rows at
+ * completion — the guuey#192 evidence (a reload mid-stall renders the FULL
+ * reply) is only possible under that model, and the read plane carries no
+ * per-row clientMessageId to match against. If persistence ever becomes
+ * progressive (partial assistant rows), this heuristic needs the read plane
+ * to grow a turn-completion marker — do not "fix" it client-side by text
+ * comparison, which cannot distinguish a partial row from a finished one.
+ */
+export function stallProbeDecision(history, localUserCount) {
+    let historyUserCount = 0;
+    for (const m of history)
+        if (m.role === "user")
+            historyUserCount += 1;
+    if (historyUserCount < localUserCount)
+        return "in-flight";
+    const last = history[history.length - 1];
+    if (!last || last.role !== "assistant" || last.text.trim() === "")
+        return "in-flight";
+    return "adopt";
+}
 export function useAgentInvoke(opts) {
     const { endpointUrl, appId } = opts;
     const [messages, setMessages] = useState([]);
@@ -51,6 +97,10 @@ export function useAgentInvoke(opts) {
     const [status, setStatus] = useState("ready");
     const [activeTool, setActiveTool] = useState(null);
     const [error, setError] = useState(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(null);
     const [threadId, setThreadId] = useState(null);
     // Opt-in block-preserving transcript. `reduceResult` follows the
     // null-until-first-valid-AgEvent contract documented on the return type: it
@@ -70,6 +120,13 @@ export function useAgentInvoke(opts) {
     // explicit dismiss, same lifecycle as `profileConsentRequest` — the two are
     // independent (an unlinked-invite vs an already-linked consent ask).
     const [profileLinkRequest, setProfileLinkRequest] = useState(null);
+    // The last turn's ending posture + the optimistic-send ledger — the
+    // transcript renderer's inputs (guuey#135 wave 3b; see the return-type
+    // contract for each). `aborted` is USER abort only — the #192 watchdog's
+    // internal stream abort never sets it.
+    const [aborted, setAborted] = useState(false);
+    const [adopted, setAdopted] = useState(false);
+    const [sendStates, setSendStates] = useState({});
     const abortRef = useRef(null);
     // Mirror the latest threadId + adapters into refs so `send` reads fresh
     // values without depending on them (keeps the callback identity stable and
@@ -77,6 +134,13 @@ export function useAgentInvoke(opts) {
     const threadIdRef = useRef(null);
     const adaptersRef = useRef(opts.adapters);
     adaptersRef.current = opts.adapters;
+    // The stall probe (guuey#192) needs the committed transcript's user-turn
+    // count long after `send`'s closures captured state — same render-time
+    // mirror idiom as `adaptersRef`.
+    const messagesRef = useRef(messages);
+    messagesRef.current = messages;
+    const stallRecoveryRef = useRef(opts.stallRecovery);
+    stallRecoveryRef.current = opts.stallRecovery;
     // The per-conversation AgJSON fold (only built when `preserveBlocks`).
     // Lazily (re)created on the first valid AgEvent after a fresh start / reset,
     // so an off run never constructs one and a bypass run never allocates.
@@ -102,6 +166,7 @@ export function useAgentInvoke(opts) {
         setThreadId(null);
         setMessages([]);
         setError(null);
+        setErrorCode(null);
         setStatus("ready");
         setActiveTool(null);
         // Fresh conversation → drop the old fold; the reducer is rebuilt lazily on
@@ -112,6 +177,9 @@ export function useAgentInvoke(opts) {
         // A prior app's consent ask must never leak into the new conversation.
         setProfileConsentRequest(null);
         setProfileLinkRequest(null);
+        setAborted(false);
+        setAdopted(false);
+        setSendStates({});
         let cancelled = false;
         const key = threadStorageKey(appId);
         const hydration = Promise.resolve(adaptersRef.current.storage.load(key))
@@ -192,6 +260,7 @@ export function useAgentInvoke(opts) {
         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
@@ -201,6 +270,9 @@ export function useAgentInvoke(opts) {
         setHistoryCards([]);
         setProfileConsentRequest(null);
         setProfileLinkRequest(null);
+        setAborted(false);
+        setAdopted(false);
+        setSendStates({});
     }, [appId]);
     const clearProfileConsentRequest = useCallback(() => {
         setProfileConsentRequest(null);
@@ -209,13 +281,49 @@ export function useAgentInvoke(opts) {
         setProfileLinkRequest(null);
     }, []);
     const send = useCallback(async (input) => {
-        if (!endpointUrl || !input.trim() || status !== "ready")
+        // An already-aborted external signal refuses the send outright —
+        // before the optimistic transcript push, so nothing is left to undo.
+        if (!endpointUrl || !input.trim() || status !== "ready" || opts.signal?.aborted)
             return;
         setError(null);
+        setErrorCode(null);
+        setAborted(false);
+        setAdopted(false);
         setStatus("connecting");
-        setMessages((prev) => [...prev, { role: "user", text: input }, { role: "assistant", text: "" }]);
+        // ONE id for the whole turn: the optimistic user entry, the send-state
+        // ledger, and the invoke body all carry it — the R0 lifecycle join.
+        const clientMessageId = adaptersRef.current.generateId();
+        /** Move this turn's ledger entry; `null` removes it (absent = sent). */
+        const markSend = (state) => {
+            setSendStates((prev) => {
+                if (state === null) {
+                    if (!(clientMessageId in prev))
+                        return prev;
+                    const next = { ...prev };
+                    delete next[clientMessageId];
+                    return next;
+                }
+                if (prev[clientMessageId] === state)
+                    return prev;
+                return { ...prev, [clientMessageId]: state };
+            });
+        };
+        markSend("sending");
+        let admitted = false;
+        setMessages((prev) => [
+            ...prev,
+            { role: "user", text: input, clientMessageId },
+            { role: "assistant", text: "" },
+        ]);
         const controller = new AbortController();
         abortRef.current = controller;
+        // Compose the host's external abort authority (opts.signal) with the
+        // per-turn controller: an external abort stops this turn exactly as
+        // `abort()` would. Listener removed in `finally` — the signal outlives
+        // the turn, the subscription must not.
+        const externalSignal = opts.signal;
+        const onExternalAbort = () => controller.abort();
+        externalSignal?.addEventListener("abort", onExternalAbort, { once: true });
         const adapters = adaptersRef.current;
         // Wait for the persisted threadId to load before deciding whether to
         // replay it — otherwise a fast first send mints a new orphan thread and
@@ -238,102 +346,193 @@ export function useAgentInvoke(opts) {
                 return next;
             });
         };
+        // ── guuey#192 stall watchdog ─────────────────────────────────────
+        // A half-dead connection (TCP alive, zero bytes, no error, no `done`)
+        // never resolves the read below, so a parallel clock watches byte
+        // activity: armed by the FIRST chunk (so a silent cold start never
+        // trips it), reset by every chunk, and on expiry it probes history
+        // WITHOUT touching the stream — killing a live-but-quiet stream on a
+        // timer would trade a frozen cursor for a lost turn. Only two things
+        // end the turn early: adoption (history already holds the finished
+        // reply — the reload the user would have done, minus the reload) and
+        // the bounded give-up (STREAM_STALLED after `probeAttempts` fruitless
+        // probes with still-zero bytes).
+        const stall = resolveStallRecovery(stallRecoveryRef.current);
+        let turnEnded = false;
+        let probeInFlight = false;
+        let fruitlessProbes = 0;
+        let activityCount = 0;
+        let stallTimer = null;
+        const clearStallTimer = () => {
+            if (stallTimer !== null) {
+                clearTimeout(stallTimer);
+                stallTimer = null;
+            }
+        };
+        const armStallTimer = () => {
+            if (!stall || turnEnded || controller.signal.aborted)
+                return;
+            clearStallTimer();
+            stallTimer = setTimeout(() => {
+                void onStallWindow();
+            }, stall.windowMs);
+        };
+        const endTurnWith = (apply) => {
+            turnEnded = true;
+            clearStallTimer();
+            apply();
+            // Unwinds the suspended read; the catch sees `aborted` and stays
+            // silent, so whatever `apply` decided IS the turn's outcome.
+            controller.abort();
+        };
+        const onStallWindow = async () => {
+            if (!stall || turnEnded || controller.signal.aborted || probeInFlight)
+                return;
+            const tid = threadIdRef.current;
+            const history = adaptersRef.current.history;
+            if (tid && history) {
+                probeInFlight = true;
+                const countAtProbe = activityCount;
+                let result = null;
+                try {
+                    result = await history.load(tid);
+                }
+                catch {
+                    result = null; // transient read failure = one fruitless probe
+                }
+                probeInFlight = false;
+                if (turnEnded || controller.signal.aborted)
+                    return;
+                // Bytes resumed while the probe was in flight: the stream is alive
+                // — discard the now-stale read; the chunk observer already reset
+                // the count and re-armed the clock.
+                if (activityCount !== countAtProbe)
+                    return;
+                if (result && !("gone" in result)) {
+                    let localUserCount = 0;
+                    for (const m of messagesRef.current)
+                        if (m.role === "user")
+                            localUserCount += 1;
+                    if (stallProbeDecision(result.messages, localUserCount) === "adopt") {
+                        const adoptedResult = result;
+                        endTurnWith(() => {
+                            setMessages(adoptedResult.messages);
+                            if ("cards" in adoptedResult && adoptedResult.cards && adoptedResult.cards.length > 0) {
+                                setHistoryCards(adoptedResult.cards);
+                            }
+                            // The renderer's #192 signal: calm renders the adopted turn
+                            // identically; debug may mark it (guuey#135 3b).
+                            setAdopted(true);
+                        });
+                        return;
+                    }
+                }
+            }
+            // No probe possible (no threadId yet / no history adapter), a failed
+            // read, or history says the turn is still in flight — all count the
+            // same: one fruitless window.
+            fruitlessProbes += 1;
+            if (fruitlessProbes >= stall.probeAttempts) {
+                endTurnWith(() => {
+                    setError("The response stream stalled and the finished reply was not found in history.");
+                    setErrorCode(CLIENT_ERROR_CODES.STREAM_STALLED);
+                });
+                return;
+            }
+            armStallTimer();
+        };
+        const transport = stall
+            ? withActivityObserver(adapters.transport, () => {
+                activityCount += 1;
+                fruitlessProbes = 0;
+                armStallTimer();
+            })
+            : adapters.transport;
         try {
-            // The endpointUrl may be a pod base (`https://host`) or the full
-            // invoke URL the deploy-controller records (`https://host/agent/invoke`).
-            // Normalize to exactly one `/agent/invoke`.
-            const base = endpointUrl.replace(/\/+$/, "");
-            const invokeUrl = base.endsWith("/agent/invoke") ? base : `${base}/agent/invoke`;
+            const invokeUrl = toInvokeUrl(endpointUrl);
             const body = {
                 input,
                 ...(threadIdRef.current ? { threadId: threadIdRef.current } : {}),
-                clientMessageId: adapters.generateId(),
+                clientMessageId,
             };
-            let buffer = "";
-            for await (const chunk of adapters.transport({ url: invokeUrl, body, signal: controller.signal })) {
-                buffer += chunk;
-                const { events, rest } = parseSseEvents(buffer);
-                buffer = rest;
-                for (const ev of events) {
-                    if (ev.event === "session") {
-                        // The pod is awake and the turn is admitted — 'connecting' ends
-                        // here (this frame arrives within ~1s of a warm pod; a cold
-                        // scale-to-zero start is exactly the long 'connecting' phase).
-                        setStatus("thinking");
-                        const tid = stringField(ev.data, "threadId");
-                        if (tid) {
-                            threadIdRef.current = tid;
-                            setThreadId(tid);
-                            void adapters.storage.save(threadStorageKey(appId), tid);
-                        }
-                    }
-                    else if (ev.event === "message") {
-                        // Status derivation (guuey#91) — read the frame's `type` before
-                        // the text fold. Silver frames announce tools + text explicitly;
-                        // bypass frames ('text' / 'assistant' SDKMessages) only ever
-                        // carry assistant text, so they map to 'responding'. Unknown
-                        // types deliberately leave the status untouched.
-                        const frameType = stringField(ev.data, "type");
-                        if (frameType === "tool.start") {
-                            setStatus("using-tool");
-                            setActiveTool(stringField(ev.data, "name") ?? null);
-                        }
-                        else if (frameType === "tool.done") {
-                            setStatus("thinking");
-                            setActiveTool(null);
-                        }
-                        else if (frameType === "text.start" ||
-                            frameType === "text.delta" ||
-                            frameType === "text" ||
-                            frameType === "assistant") {
-                            setStatus("responding");
-                        }
-                        renderAssistant(reduceAssistantText(assistantText, ev.data));
-                        // Additively fold the SAME frame into the AgJSON reducer when
-                        // opted in. The text surface above is untouched; only VALID
-                        // AgEvents advance the reducer (bypass frames ingest to [] and
-                        // leave `reduceResult` null — see the return-type contract).
-                        if (preserveBlocksRef.current) {
-                            const agEvents = ingestMessageFrame(ev.data);
-                            if (agEvents.length > 0) {
-                                if (!reducerRef.current)
-                                    reducerRef.current = new Reducer();
-                                for (const agEvent of agEvents)
-                                    reducerRef.current.push(agEvent);
-                                setReduceResult(reducerRef.current.result());
-                            }
-                        }
-                    }
-                    else if (ev.event === "error") {
-                        setError(stringField(ev.data, "message") ?? "agent error");
-                    }
-                    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
-                        // valid request untouched (never clobbered to null).
-                        const parsed = parseConsentRequest(ev.data);
-                        if (parsed)
-                            setProfileConsentRequest(parsed);
+            // The wire walk lives in `invokeTurn` (the pure per-turn generator —
+            // its docblock owns the switch semantics); this hook only maps each
+            // semantic event onto React state.
+            for await (const ev of invokeTurn({ url: invokeUrl, body, signal: controller.signal }, transport)) {
+                if (ev.kind === "session") {
+                    // The pod is awake and the turn is admitted — 'connecting' ends
+                    // here, and so does the R0 "sending" state (absent = sent).
+                    admitted = true;
+                    markSend(null);
+                    setStatus("thinking");
+                    if (ev.threadId) {
+                        threadIdRef.current = ev.threadId;
+                        setThreadId(ev.threadId);
+                        void adapters.storage.save(threadStorageKey(appId), ev.threadId);
                     }
-                    else if (ev.event === "profile-link-needed") {
-                        // Cross-app profile LINK invite (linkcoh T3) for an unlinked byo
-                        // caller. Same drop-if-malformed contract as consent above.
-                        const parsed = parseLinkRequest(ev.data);
-                        if (parsed)
-                            setProfileLinkRequest(parsed);
+                }
+                else if (ev.kind === "message") {
+                    // Absent status/activeTool mean "no change" — never touched, so
+                    // an unknown frame type leaves both standing (guuey#91 rule).
+                    if (ev.status !== undefined)
+                        setStatus(ev.status);
+                    if (ev.activeTool !== undefined)
+                        setActiveTool(ev.activeTool);
+                    renderAssistant(ev.assistantText);
+                    // Additively fold the frame's AgEvents into the AgJSON reducer
+                    // when opted in. The text surface above is untouched; only VALID
+                    // AgEvents advance the reducer (bypass frames carry [] and leave
+                    // `reduceResult` null — see the return-type contract).
+                    if (preserveBlocksRef.current && ev.agEvents.length > 0) {
+                        if (!reducerRef.current)
+                            reducerRef.current = new Reducer();
+                        for (const agEvent of ev.agEvents)
+                            reducerRef.current.push(agEvent);
+                        setReduceResult(reducerRef.current.result());
                     }
-                    // `done` needs no handling — the stream closes after it. Any other
-                    // (unknown) event falls through silently — there is no default
-                    // branch, so a consumer that never renders a field is unaffected.
                 }
+                else if (ev.kind === "error") {
+                    // In-band failure frame — the code moves in lockstep with the
+                    // message (an event without one carries null rather than leaving
+                    // a previous turn's code standing).
+                    setError(ev.message);
+                    setErrorCode(ev.code);
+                }
+                else if (ev.kind === "profile-consent") {
+                    setProfileConsentRequest(ev.request);
+                }
+                else if (ev.kind === "profile-link") {
+                    setProfileLinkRequest(ev.request);
+                }
+                // `done` needs no handling here — the stream closes after it.
             }
         }
         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);
+                // A failure BEFORE admission means the message never reached the
+                // agent — the R0 failed-to-send state. Post-admission failures
+                // leave the entry removed (the send itself succeeded).
+                if (!admitted)
+                    markSend("failed");
             }
         }
         finally {
+            // The turn is over however it ended — no probe may fire after this,
+            // and the pending timer must not leak past the turn. `turnEnded`
+            // already true here ⟺ the #192 watchdog ended the turn (adoption or
+            // stall give-up) — its internal `controller.abort()` must not read
+            // as a USER abort below.
+            const endedByWatchdog = turnEnded;
+            turnEnded = true;
+            clearStallTimer();
+            externalSignal?.removeEventListener("abort", onExternalAbort);
             setStatus("ready");
             setActiveTool(null);
             abortRef.current = null;
@@ -348,14 +547,23 @@ export function useAgentInvoke(opts) {
                         : prev;
                 });
             }
+            if (controller.signal.aborted && !endedByWatchdog) {
+                // USER abort (abort() or the external signal): surface it, and a
+                // pre-admission cancel clears the "sending" entry — a turn the
+                // user stopped is not a failed send.
+                setAborted(true);
+                if (!admitted)
+                    markSend(null);
+            }
         }
-    }, [endpointUrl, appId, status]);
+    }, [endpointUrl, appId, status, opts.signal]);
     return {
         messages,
         send,
         status,
         activeTool,
         error,
+        errorCode,
         threadId,
         abort,
         reset,
@@ -365,5 +573,8 @@ export function useAgentInvoke(opts) {
         clearProfileConsentRequest,
         profileLinkRequest,
         clearProfileLinkRequest,
+        aborted,
+        adopted,
+        sendStates,
     };
 }

package/dist/web-adapters.d.ts

@@ -6,44 +6,12 @@
  * functions — never at module load — so this file is import-safe under SSR
  * (the functions guard on `typeof window`).
  */
-import { type ResolvedViewMount } from "@guuey/mcp-apps-host";
-import type { AgentInvokeAdapters, InvokeRequest, ThreadIdStore } from "./types";
-/**
- * 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 declare class AgentResponseError extends Error {
-    readonly status: number;
-    readonly code?: string | undefined;
-    constructor(message: string, status: number, code?: string | undefined);
-}
+import { type McpToolCallResult, type ResolvedViewMount, type UiActionRequest } from "@guuey/mcp-apps-host";
+import type { AgentInvokeAdapters, ThreadIdStore } from "./types.js";
 /** Persists the threadId in `window.localStorage` (synchronously). */
 export declare const localStorageThreadStore: ThreadIdStore;
 /** Crypto-strong client-message id, with a non-crypto fallback. */
 export declare function webGenerateId(): string;
-/**
- * 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 declare function fetchStreamTransport(req: InvokeRequest, accessToken?: string | null, guestSecret?: string | null): AsyncGenerator<string>;
 export interface CreateWebAdaptersOptions {
     /**
      * Public read-plane base (ending in `/v1`) for transcript history. When
@@ -151,4 +119,32 @@ export interface CreateUiResourceReaderOptions {
  * 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. */
+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 declare function createUiActionRelay(options: CreateUiActionRelayOptions): (request: UiActionRequest) => Promise<McpToolCallResult>;
 //# sourceMappingURL=web-adapters.d.ts.map

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,EAGL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EAEb,aAAa,EACd,MAAM,SAAS,CAAC;AAGjB;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;gBAFtB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,YAAA;CAKzB;AAED,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,EAAE,aAiBrC,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAwCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAuB,oBAAoB,CACzC,GAAG,EAAE,aAAa,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,cAAc,CAAC,MAAM,CAAC,CA4CxB;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,CAwErB;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"}
+{"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"}