@guuey/agent-client 0.1.0 → 0.2.0

package/dist/sse.d.ts

@@ -3,6 +3,7 @@
  * platform dependencies — unit-tested in isolation (`sse.test.ts`) and shared
  * verbatim across web (Studio) and React-Native (Portal).
  */
+import type { ProfileConsentRequest, ProfileLinkRequest } from "./types";
 export interface ParsedSseEvent {
     event: string;
     data: unknown;
@@ -40,4 +41,22 @@ export declare function reduceAssistantText(current: string, data: unknown): str
 export declare function extractAssistantText(data: unknown): string;
 /** Read a string field off an SSE `data` object, or undefined. */
 export declare function stringField(data: unknown, key: string): string | undefined;
+/**
+ * Parse a `profile-consent-needed` SSE payload into a typed
+ * {@link ProfileConsentRequest}, or `null` if it does not conform. `appId`
+ * must be a non-empty string and `requested` exactly `"read"` or
+ * `"read-write"`; extra keys are tolerated (ignored). Returns a fresh
+ * normalized object so callers get exactly the typed shape, never the raw
+ * wire payload with unknown extras.
+ */
+export declare function parseConsentRequest(data: unknown): ProfileConsentRequest | null;
+/**
+ * Parse a `profile-link-needed` SSE payload into a typed
+ * {@link ProfileLinkRequest}, or `null` if it does not conform. Same shape +
+ * validation as {@link parseConsentRequest} (`appId` non-empty string,
+ * `requested` exactly `"read"` or `"read-write"`, extra keys tolerated) — the
+ * pod emits an identically-shaped payload for both events; only the event
+ * NAME (and what it means to the consumer) differs.
+ */
+export declare function parseLinkRequest(data: unknown): ProfileLinkRequest | null;
 //# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAqBzF;AAUD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAM1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAgC1D;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI1E"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAqBzF;AAUD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAM1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAgC1D;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI1E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,qBAAqB,GAAG,IAAI,CAO/E;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAOzE"}

package/dist/sse.js

@@ -105,3 +105,41 @@ export function stringField(data, key) {
     const v = data[key];
     return typeof v === "string" ? v : undefined;
 }
+/**
+ * Parse a `profile-consent-needed` SSE payload into a typed
+ * {@link ProfileConsentRequest}, or `null` if it does not conform. `appId`
+ * must be a non-empty string and `requested` exactly `"read"` or
+ * `"read-write"`; extra keys are tolerated (ignored). Returns a fresh
+ * normalized object so callers get exactly the typed shape, never the raw
+ * wire payload with unknown extras.
+ */
+export function parseConsentRequest(data) {
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return null;
+    const appId = data.appId;
+    const requested = data.requested;
+    if (typeof appId !== "string" || appId.length === 0)
+        return null;
+    if (requested !== "read" && requested !== "read-write")
+        return null;
+    return { appId, requested };
+}
+/**
+ * Parse a `profile-link-needed` SSE payload into a typed
+ * {@link ProfileLinkRequest}, or `null` if it does not conform. Same shape +
+ * validation as {@link parseConsentRequest} (`appId` non-empty string,
+ * `requested` exactly `"read"` or `"read-write"`, extra keys tolerated) — the
+ * pod emits an identically-shaped payload for both events; only the event
+ * NAME (and what it means to the consumer) differs.
+ */
+export function parseLinkRequest(data) {
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return null;
+    const appId = data.appId;
+    const requested = data.requested;
+    if (typeof appId !== "string" || appId.length === 0)
+        return null;
+    if (requested !== "read" && requested !== "read-write")
+        return null;
+    return { appId, requested };
+}

package/dist/types.d.ts

@@ -6,7 +6,10 @@
  * (which also carries anonymous identity) — are INJECTED by the consumer via
  * {@link AgentInvokeAdapters}. Web (Studio) passes localStorage / crypto /
  * credentialed-cookie fetch; React-Native (Portal) passes AsyncStorage /
- * getRandomValues / header-identity SSE fetch. This mirrors the ggui
+ * getRandomValues / header-identity SSE fetch. Anonymous identity is per-host,
+ * not per-platform: a web host with no usable cookie jar (an embedded
+ * third-party iframe) carries its own guest secret in a header too — see
+ * `createWebAdapters`'s `getGuestSecret`. This mirrors the ggui
  * `MessageStorageAdapter` injection pattern.
  */
 import type { AgReduceResult, JsonValue } from "@silverprotocol/core";
@@ -15,6 +18,33 @@ export interface AgentMessage {
     role: "user" | "assistant";
     text: string;
 }
+/**
+ * A cross-app profile consent request surfaced mid-stream by the pod's
+ * `profile-consent-needed` SSE event (nocode-runtime T6). Emitted when the
+ * agent declares a profile intent the caller has NOT yet granted for this app,
+ * so the consumer UI can prompt the user to authorize `read` or `read-write`
+ * access. `requested` mirrors the pod's `ProfileAccess` posture verbatim; the
+ * literal union is inlined rather than imported to keep this client SDK free of
+ * any backend-package dependency.
+ */
+export interface ProfileConsentRequest {
+    appId: string;
+    requested: "read" | "read-write";
+}
+/**
+ * A cross-app profile LINK invite surfaced mid-stream by the pod's
+ * `profile-link-needed` SSE event (nocode-runtime linkcoh T3). Emitted when an
+ * unlinked byo end-user's declared profile posture booted, inviting them to
+ * link their guuey account (via the named `/link` ceremony) so they earn the
+ * guuey-wide cross-app profile. `requested` mirrors the pod's `ProfileAccess`
+ * posture verbatim (the builder's declared access, not a live ask) — the
+ * literal union is inlined rather than imported, same rationale as
+ * {@link ProfileConsentRequest}.
+ */
+export interface ProfileLinkRequest {
+    appId: string;
+    requested: "read" | "read-write";
+}
 /**
  * A persisted generative-UI card rehydrated from thread history — the verbatim
  * `AgArtifact` snapshot the pod stored on a `kind: "card"` row, tagged with its
@@ -51,7 +81,7 @@ export interface InvokeRequest {
  * Opens an invoke request and yields decoded UTF-8 text chunks of the SSE
  * stream (the hook accumulates + parses frames itself). MUST throw on a
  * non-OK response or network failure. Owns headers + identity entirely, so
- * the hook never sees cookies or bearer tokens.
+ * the hook never sees cookies, bearer tokens, or guest secrets.
  */
 export type InvokeTransport = (req: InvokeRequest) => AsyncIterable<string>;
 /**
@@ -102,10 +132,35 @@ export interface UseAgentInvokeOptions {
      */
     preserveBlocks?: boolean;
 }
+/**
+ * The per-turn lifecycle (guuey#91), derived ENTIRELY from frames the pod
+ * already emits — no protocol addition:
+ *
+ *  - `ready`      — no turn in flight (initial, after `done`/failure/abort).
+ *  - `connecting` — `send()` fired, no `session` frame yet. With
+ *    scale-to-zero pods this phase can span a cold start, so hosts typically
+ *    swap to "waking your agent" copy after a few seconds.
+ *  - `thinking`   — the pod is awake and the turn is running, but no text is
+ *    flowing and no tool is announced (between `session` and the first
+ *    content, and between a `tool.done` and whatever follows it).
+ *  - `using-tool` — a `tool.start` frame arrived; {@link UseAgentInvokeReturn.activeTool}
+ *    carries the wire tool name until the matching `tool.done`.
+ *  - `responding` — assistant text is arriving (`text.start`/`text.delta`
+ *    silver frames, or bypass text/assistant frames).
+ *
+ * Failure keeps its own channel ({@link UseAgentInvokeReturn.error}) — there
+ * is deliberately no `error` status: after any terminal outcome the status
+ * returns to `ready` so the composer re-enables.
+ */
+export type AgentInvokeStatus = "ready" | "connecting" | "thinking" | "using-tool" | "responding";
 export interface UseAgentInvokeReturn {
     messages: AgentMessage[];
     send: (input: string) => Promise<void>;
-    isStreaming: boolean;
+    /** The per-turn lifecycle — see {@link AgentInvokeStatus}. Anything other
+     *  than `ready` means a turn is in flight (the old `isStreaming === true`). */
+    status: AgentInvokeStatus;
+    /** The active tool's wire name while `status === 'using-tool'`, else null. */
+    activeTool: string | null;
     error: string | null;
     threadId: string | null;
     /** Abort the in-flight turn (the stream stops; partial text is kept). */
@@ -141,5 +196,29 @@ export interface UseAgentInvokeReturn {
      * `reset()` clears it back to `[]`.
      */
     historyCards: HistoryCard[];
+    /**
+     * The latest cross-app profile consent request the pod asked for on THIS
+     * conversation, or `null`. Set from a well-formed `profile-consent-needed`
+     * SSE event (see {@link ProfileConsentRequest}); malformed payloads are
+     * dropped and leave the field untouched. `reset()` and an app switch clear
+     * it back to `null`. Consumers that never render a consent prompt (e.g.
+     * Studio) simply ignore this field.
+     */
+    profileConsentRequest: ProfileConsentRequest | null;
+    /** Dismiss the pending {@link profileConsentRequest} (back to `null`). */
+    clearProfileConsentRequest: () => void;
+    /**
+     * The latest cross-app profile LINK invite the pod asked for on THIS
+     * conversation, or `null`. Set from a well-formed `profile-link-needed`
+     * SSE event (see {@link ProfileLinkRequest}); malformed payloads are
+     * dropped and leave the field untouched. `reset()` and an app switch clear
+     * it back to `null`. Consumers that never render a link prompt simply
+     * ignore this field. Distinct from {@link profileConsentRequest}: this one
+     * invites an UNLINKED byo user to link their account; consent asks an
+     * already-linked user to grant an app read/read-write access.
+     */
+    profileLinkRequest: ProfileLinkRequest | null;
+    /** Dismiss the pending {@link profileLinkRequest} (back to `null`). */
+    clearProfileLinkRequest: () => void;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtE,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,SAAS,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC;AAEtC,kDAAkD;AAClD,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,IAAI,EAAE,OAAO,CAAC;IACd,mCAAmC;IACnC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,aAAa,CAAC,MAAM,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,EAAE,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAEnB;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,sFAAsF;IACtF,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACpD;AAED,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,eAAe,CAAC;IAC3B,yGAAyG;IACzG,OAAO,CAAC,EAAE,yBAAyB,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,6FAA6F;IAC7F,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,EAAE,mBAAmB,CAAC;IAC9B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yEAAyE;IACzE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,EAAE,cAAc,GAAG,IAAI,CAAC;IACpC;;;;;;;;OAQG;IACH,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -6,7 +6,10 @@
  * (which also carries anonymous identity) — are INJECTED by the consumer via
  * {@link AgentInvokeAdapters}. Web (Studio) passes localStorage / crypto /
  * credentialed-cookie fetch; React-Native (Portal) passes AsyncStorage /
- * getRandomValues / header-identity SSE fetch. This mirrors the ggui
+ * getRandomValues / header-identity SSE fetch. Anonymous identity is per-host,
+ * not per-platform: a web host with no usable cookie jar (an embedded
+ * third-party iframe) carries its own guest secret in a header too — see
+ * `createWebAdapters`'s `getGuestSecret`. This mirrors the ggui
  * `MessageStorageAdapter` injection pattern.
  */
 export {};

package/dist/useAgentInvoke.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAgentInvoke.d.ts","sourceRoot":"","sources":["../src/useAgentInvoke.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAEV,YAAY,EAEZ,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAMjB,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,eAAe,EAAE,YAAY,EAAE,GAC9B,kBAAkB,CAIpB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CAgPhF"}
+{"version":3,"file":"useAgentInvoke.d.ts","sourceRoot":"","sources":["../src/useAgentInvoke.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAGV,YAAY,EAEZ,iBAAiB,EAGjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAMjB,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,eAAe,EAAE,YAAY,EAAE,GAC9B,kBAAkB,CAIpB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CAqUhF"}

package/dist/useAgentInvoke.js

@@ -23,7 +23,7 @@
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Reducer } from "@silverprotocol/core";
-import { parseSseEvents, reduceAssistantText, stringField } from "./sse";
+import { parseConsentRequest, parseLinkRequest, parseSseEvents, reduceAssistantText, stringField, } from "./sse";
 import { ingestMessageFrame } from "./blocks";
 function threadStorageKey(appId) {
     return `guuey:thread:${appId ?? "default"}`;
@@ -45,7 +45,11 @@ export function applyHistoryResult(result, currentMessages) {
 export function useAgentInvoke(opts) {
     const { endpointUrl, appId } = opts;
     const [messages, setMessages] = useState([]);
-    const [isStreaming, setIsStreaming] = useState(false);
+    // Per-turn lifecycle (guuey#91) — derived purely from the frames below; see
+    // the `AgentInvokeStatus` doc for the state meanings. `activeTool` carries
+    // the wire tool name only while status is 'using-tool'.
+    const [status, setStatus] = useState("ready");
+    const [activeTool, setActiveTool] = useState(null);
     const [error, setError] = useState(null);
     const [threadId, setThreadId] = useState(null);
     // Opt-in block-preserving transcript. `reduceResult` follows the
@@ -57,6 +61,15 @@ export function useAgentInvoke(opts) {
     // contract). Independent of the live `reduceResult` fold — populated only
     // when a card-carrying history load seeds the transcript.
     const [historyCards, setHistoryCards] = useState([]);
+    // The pod's latest cross-app profile consent ask on this conversation (T6's
+    // `profile-consent-needed` SSE event), or null. Cleared on app switch /
+    // reset / explicit dismiss. Consumers with no consent UI just ignore it.
+    const [profileConsentRequest, setProfileConsentRequest] = useState(null);
+    // The pod's latest cross-app profile LINK invite on this conversation (T3's
+    // `profile-link-needed` SSE event), or null. Cleared on app switch / reset /
+    // explicit dismiss, same lifecycle as `profileConsentRequest` — the two are
+    // independent (an unlinked-invite vs an already-linked consent ask).
+    const [profileLinkRequest, setProfileLinkRequest] = useState(null);
     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
@@ -64,9 +77,13 @@ export function useAgentInvoke(opts) {
     const threadIdRef = useRef(null);
     const adaptersRef = useRef(opts.adapters);
     adaptersRef.current = opts.adapters;
-    // The per-conversation AgJSON reducer (only built when `preserveBlocks`).
+    // 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.
+    // The core Reducer carries `_meta` onto tool-result blocks as of
+    // `@silverprotocol/core` 0.4.1 (workspace#9), so BOTH generative-UI channels
+    // (MCP-Apps `_meta.ui`, ggui's render bootstrap) survive the fold natively —
+    // the old guuey-side `BlockFold` carriage wrapper is deleted.
     const reducerRef = useRef(null);
     const preserveBlocksRef = useRef(opts.preserveBlocks ?? false);
     preserveBlocksRef.current = opts.preserveBlocks ?? false;
@@ -85,12 +102,16 @@ export function useAgentInvoke(opts) {
         setThreadId(null);
         setMessages([]);
         setError(null);
-        setIsStreaming(false);
+        setStatus("ready");
+        setActiveTool(null);
         // Fresh conversation → drop the old fold; the reducer is rebuilt lazily on
         // the next valid AgEvent. Persisted cards are re-seeded below from history.
         reducerRef.current = null;
         setReduceResult(null);
         setHistoryCards([]);
+        // A prior app's consent ask must never leak into the new conversation.
+        setProfileConsentRequest(null);
+        setProfileLinkRequest(null);
         let cancelled = false;
         const key = threadStorageKey(appId);
         const hydration = Promise.resolve(adaptersRef.current.storage.load(key))
@@ -171,18 +192,27 @@ export function useAgentInvoke(opts) {
         void adaptersRef.current.storage.save(threadStorageKey(appId), "");
         setMessages([]);
         setError(null);
-        setIsStreaming(false);
+        setStatus("ready");
+        setActiveTool(null);
         // Re-create the reducer for the new conversation (rebuilt lazily on the
         // next valid AgEvent) and clear the exposed fold + any rehydrated cards.
         reducerRef.current = null;
         setReduceResult(null);
         setHistoryCards([]);
+        setProfileConsentRequest(null);
+        setProfileLinkRequest(null);
     }, [appId]);
+    const clearProfileConsentRequest = useCallback(() => {
+        setProfileConsentRequest(null);
+    }, []);
+    const clearProfileLinkRequest = useCallback(() => {
+        setProfileLinkRequest(null);
+    }, []);
     const send = useCallback(async (input) => {
-        if (!endpointUrl || !input.trim() || isStreaming)
+        if (!endpointUrl || !input.trim() || status !== "ready")
             return;
         setError(null);
-        setIsStreaming(true);
+        setStatus("connecting");
         setMessages((prev) => [...prev, { role: "user", text: input }, { role: "assistant", text: "" }]);
         const controller = new AbortController();
         abortRef.current = controller;
@@ -194,7 +224,7 @@ export function useAgentInvoke(opts) {
             await hydrationRef.current;
         }
         if (controller.signal.aborted) {
-            setIsStreaming(false);
+            setStatus("ready");
             abortRef.current = null;
             return;
         }
@@ -226,6 +256,10 @@ export function useAgentInvoke(opts) {
                 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;
@@ -234,6 +268,26 @@ export function useAgentInvoke(opts) {
                         }
                     }
                     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
@@ -253,7 +307,24 @@ export function useAgentInvoke(opts) {
                     else if (ev.event === "error") {
                         setError(stringField(ev.data, "message") ?? "agent error");
                     }
-                    // `done` needs no handling — the stream closes after it.
+                    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);
+                    }
+                    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);
+                    }
+                    // `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.
                 }
             }
         }
@@ -263,7 +334,8 @@ export function useAgentInvoke(opts) {
             }
         }
         finally {
-            setIsStreaming(false);
+            setStatus("ready");
+            setActiveTool(null);
             abortRef.current = null;
             // A turn aborted before any assistant text streamed leaves an empty
             // placeholder bubble — drop it so a stopped turn doesn't linger as a
@@ -277,6 +349,21 @@ export function useAgentInvoke(opts) {
                 });
             }
         }
-    }, [endpointUrl, appId, isStreaming]);
-    return { messages, send, isStreaming, error, threadId, abort, reset, reduceResult, historyCards };
+    }, [endpointUrl, appId, status]);
+    return {
+        messages,
+        send,
+        status,
+        activeTool,
+        error,
+        threadId,
+        abort,
+        reset,
+        reduceResult,
+        historyCards,
+        profileConsentRequest,
+        clearProfileConsentRequest,
+        profileLinkRequest,
+        clearProfileLinkRequest,
+    };
 }

package/dist/web-adapters.d.ts

@@ -24,14 +24,25 @@ export declare const localStorageThreadStore: ThreadIdStore;
 /** Crypto-strong client-message id, with a non-crypto fallback. */
 export declare function webGenerateId(): string;
 /**
- * Web SSE transport. When `accessToken` is present the pod identifies the
- * caller by their verified Cognito access token (the same identity the
- * history read plane uses, so persisted threads round-trip on reload).
- * Otherwise it falls back to `credentials: "include"`, which round-trips the
- * HttpOnly `guuey_guest` cookie the pod mints for anonymous browser callers.
+ * 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): AsyncGenerator<string>;
+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
@@ -42,18 +53,71 @@ export interface CreateWebAdaptersOptions {
      * Resolve the caller's Cognito access token (fresh), or `null` when signed
      * out. When a token is present the chat transport AND the history read
      * authenticate as that user, so a reload restores the transcript. Without
-     * a token the transport falls back to the guest cookie and history is
-     * skipped — the read plane can't identify a cookie-only browser caller
-     * (it reads the `x-guuey-guest` header or a Bearer, not the HttpOnly
-     * guest cookie), so there is no identity to replay.
+     * a token, identity falls to {@link getGuestSecret} (if supplied) and then
+     * to the guest cookie.
+     *
+     * Called with `{ forceRefresh: true }` exactly once: when the history read
+     * gets a 401 on a token this resolver already returned (a token cached
+     * before the mount-time history read fired can be stale by the time it
+     * runs — the same window the send path's own 401-retry closes). A resolver
+     * that caches (Amplify's `fetchAuthSession` does, and so does the widget's
+     * `createHostTokenProvider`) MUST bypass that cache for a forced call and
+     * obtain a genuinely fresh token — returning the SAME stale value would
+     * make the retry indistinguishable from not retrying at all. A resolver
+     * with nothing fresher to offer returns `null`, and the read surfaces the
+     * ORIGINAL 401 rather than replaying the value that just failed.
+     */
+    getAccessToken?: (opts?: {
+        forceRefresh?: boolean;
+    }) => Promise<string | null>;
+    /**
+     * Resolve the caller's own persisted anonymous guest secret (64 lowercase
+     * hex chars), or `null` when there is none. Supply this on hosts whose
+     * cookie jar can't carry the pod's HttpOnly `guuey_guest` — notably the
+     * embedded widget, a third-party iframe whose cookies browsers partition
+     * or block outright.
+     *
+     * With a secret, BOTH the chat transport and the history read send
+     * `x-guuey-guest`, so an anonymous transcript replays on reload the same
+     * way a signed-in one does — the read plane identifies a guest by that
+     * header (it cannot see the HttpOnly cookie, which is why a cookie-only
+     * caller still gets no history).
+     *
+     * Called once per request, so a rotated secret takes effect immediately.
+     * A value that isn't 64 lowercase hex is ignored (never sent) and the
+     * request falls through to cookie mode.
+     *
+     * **Supply at most ONE identity resolver per mode.** Anonymous hosts pass
+     * this one; identified hosts pass {@link getAccessToken} and surface a token
+     * failure rather than continuing. Passing BOTH is a hazard, not a fallback
+     * chain: `getAccessToken` resolving `null` is indistinguishable here from
+     * "signed out on purpose", so a merely *expired or unavailable* token
+     * silently downgrades the caller to the anonymous identity. The request then
+     * SUCCEEDS — the pod accepts anonymous invokes unconditionally — but the
+     * turns land in a different thread (the pod forks on an owner mismatch
+     * rather than appending), unreachable from the identified session, which
+     * gets its own transcript back minus those turns on the next good load. A
+     * 401-then-re-request-token retry loop is exactly this window.
+     *
+     * MUST be synchronous and MUST NOT throw: a throw propagates and fails the
+     * invoke. This is a real hazard for the widget, not a formality —
+     * `localStorage` access raises `SecurityError` in a third-party iframe with
+     * storage blocked (Safari's default for embedded content), which is normal
+     * operation here. A host reading storage owns that handling and MUST return
+     * `null` on a blocked read, the way {@link localStorageThreadStore} does for
+     * the threadId; `null` degrades to cookie mode, whereas a throw takes the
+     * chat down. Deliberately NOT caught at this seam: catching a host-supplied
+     * callback would also swallow ordinary host bugs into a silent anonymous
+     * downgrade — the same failure this docblock warns about above.
      */
-    getAccessToken?: () => Promise<string | null>;
+    getGuestSecret?: () => string | null;
 }
 /**
  * Build the web host-adapter bundle for {@link useAgentInvoke}. Pass an
- * access-token resolver (and the read-plane base) to authenticate the chat
- * transport and enable transcript restore on reload; omit them for an
- * anonymous, history-less bundle.
+ * access-token resolver and/or a guest-secret resolver (plus the read-plane
+ * base) to give the chat transport an identity the read plane can also see,
+ * which is what enables transcript restore on reload; omit both for a
+ * cookie-only, history-less bundle.
  */
 export declare function createWebAdapters(opts?: CreateWebAdaptersOptions): AgentInvokeAdapters;
 //# 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,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;AAED;;;;;;;GAOG;AACH,wBAAuB,oBAAoB,CACzC,GAAG,EAAE,aAAa,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,cAAc,CAAC,MAAM,CAAC,CAyCxB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC/C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE,wBAA6B,GAClC,mBAAmB,CA+BrB"}
+{"version":3,"file":"web-adapters.d.ts","sourceRoot":"","sources":["../src/web-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,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,CAqErB"}