@guuey/agent-client 0.1.0 → 0.2.1

package/src/index.ts

@@ -3,8 +3,11 @@ export {
   extractAssistantText,
   reduceAssistantText,
   stringField,
+  parseConsentRequest,
+  parseLinkRequest,
   type ParsedSseEvent,
 } from "./sse";
+export { dismissLinkPrompt } from "./link-prompt";
 export {
   createWebAdapters,
   localStorageThreadStore,
@@ -17,6 +20,7 @@ export {
   fetchThreadHistory,
   threadHistoryRowsToMessages,
   threadHistoryRowsToCards,
+  HistoryUnauthorizedError,
   type ThreadHistoryRow,
   type ThreadHistoryFetchOptions,
 } from "./history";
@@ -36,6 +40,26 @@ export {
   toolResultUiResource,
   type McpUiResourcePayload,
 } from "./block-ui";
+// The ggui render channel (`uiData.resourceUri` + the `_meta["ai.ggui/render"]`
+// bootstrap) and the dispatcher that mounts EITHER channel through the same
+// second-origin sandbox path.
+export {
+  asGguiRender,
+  asGguiRenderBootstrap,
+  blockGguiRender,
+  gguiRenderResource,
+  gguiShellHtml,
+  toolResultGguiRender,
+  GGUI_RENDER_META_KEY,
+  type GguiRenderBootstrap,
+  type GguiRenderDescriptor,
+} from "./ggui-render";
+export {
+  cardCardMount,
+  toolResultCardMount,
+  type CardMount,
+  type CardMountChannel,
+} from "./card-mount";
 // Re-export the AgJSON types the block-preserving transcript surfaces, so
 // consumers can name `reduceResult` / block types without a direct
 // `@silverprotocol/core` import.
@@ -43,12 +67,15 @@ export type { AgEvent, AgReduceResult, AgMessage, AgBlock } from "@silverprotoco
 export type {
   AgentMessage,
   HistoryCard,
+  ProfileConsentRequest,
+  ProfileLinkRequest,
   ThreadIdStore,
   GenerateId,
   InvokeRequest,
   InvokeTransport,
   AgentInvokeAdapters,
   AgentInvokeHistoryAdapter,
+  AgentInvokeStatus,
   HistoryLoadResult,
   UseAgentInvokeOptions,
   UseAgentInvokeReturn,

package/src/link-prompt.ts

@@ -0,0 +1,34 @@
+/**
+ * Client for the pod's `POST /v1/link-prompt/dismiss` route (nocode-runtime
+ * linkcoh T4) — the "don't ask again" action on the
+ * {@link ProfileLinkRequest} prompt (see `./sse`'s `parseLinkRequest` and
+ * `useAgentInvoke`'s `profileLinkRequest` state). Host-agnostic like
+ * {@link fetchThreadHistory} in `./history`: takes a bearer directly (the
+ * route authenticates ONLY off the verified bearer — the request body is
+ * never read server-side, so there is nothing else to send) and an
+ * injectable `fetchImpl` for tests, defaulting to the global `fetch`.
+ */
+
+/**
+ * Dismiss the pending cross-app profile link prompt for the calling byo
+ * end-user. `baseUrl` is the public read-plane base already ending in `/v1`
+ * (same convention as {@link fetchThreadHistory}'s `baseUrl`); `bearer` is the
+ * caller's byo access token, sent as `Authorization: Bearer <bearer>` — the
+ * ONLY thing the pod's route reads to determine the dismissal subject.
+ *
+ * Resolves on a 204 (the route's only success response); throws on any
+ * non-2xx status (401 unauthenticated, 403 non-byo caller, 500 write failure).
+ */
+export async function dismissLinkPrompt(
+  baseUrl: string,
+  bearer: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  const res = await fetchImpl(`${baseUrl}/link-prompt/dismiss`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${bearer}` },
+  });
+  if (!res.ok) {
+    throw new Error(`link prompt dismiss failed: ${res.status}`);
+  }
+}

package/src/sse.ts

@@ -4,6 +4,8 @@
  * verbatim across web (Studio) and React-Native (Portal).
  */
 
+import type { ProfileConsentRequest, ProfileLinkRequest } from "./types";
+
 export interface ParsedSseEvent {
   event: string;
   data: unknown;
@@ -113,3 +115,37 @@ export function stringField(data: unknown, key: string): string | undefined {
   const v = (data as Record<string, unknown>)[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: unknown): ProfileConsentRequest | null {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return null;
+  const appId = (data as { appId?: unknown }).appId;
+  const requested = (data as { requested?: unknown }).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: unknown): ProfileLinkRequest | null {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return null;
+  const appId = (data as { appId?: unknown }).appId;
+  const requested = (data as { requested?: unknown }).requested;
+  if (typeof appId !== "string" || appId.length === 0) return null;
+  if (requested !== "read" && requested !== "read-write") return null;
+  return { appId, requested };
+}

package/src/types.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.
  */
 
@@ -18,6 +21,35 @@ export interface AgentMessage {
   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
@@ -58,7 +90,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>;
 
@@ -111,10 +143,36 @@ 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). */
@@ -150,4 +208,28 @@ 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;
 }

package/src/useAgentInvoke.ts

@@ -23,13 +23,22 @@
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Reducer, type AgReduceResult } from "@silverprotocol/core";
-import { parseSseEvents, reduceAssistantText, stringField } from "./sse";
+import {
+  parseConsentRequest,
+  parseLinkRequest,
+  parseSseEvents,
+  reduceAssistantText,
+  stringField,
+} from "./sse";
 import { ingestMessageFrame } from "./blocks";
 import type {
   AgentInvokeAdapters,
+  AgentInvokeStatus,
   AgentMessage,
   HistoryCard,
   HistoryLoadResult,
+  ProfileConsentRequest,
+  ProfileLinkRequest,
   UseAgentInvokeOptions,
   UseAgentInvokeReturn,
 } from "./types";
@@ -63,7 +72,11 @@ export function applyHistoryResult(
 export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeReturn {
   const { endpointUrl, appId } = opts;
   const [messages, setMessages] = useState<AgentMessage[]>([]);
-  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<AgentInvokeStatus>("ready");
+  const [activeTool, setActiveTool] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [threadId, setThreadId] = useState<string | null>(null);
   // Opt-in block-preserving transcript. `reduceResult` follows the
@@ -75,6 +88,15 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
   // contract). Independent of the live `reduceResult` fold — populated only
   // when a card-carrying history load seeds the transcript.
   const [historyCards, setHistoryCards] = useState<HistoryCard[]>([]);
+  // 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<ProfileConsentRequest | null>(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<ProfileLinkRequest | null>(null);
 
   const abortRef = useRef<AbortController | null>(null);
   // Mirror the latest threadId + adapters into refs so `send` reads fresh
@@ -83,9 +105,13 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
   const threadIdRef = useRef<string | null>(null);
   const adaptersRef = useRef<AgentInvokeAdapters>(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<Reducer | null>(null);
   const preserveBlocksRef = useRef<boolean>(opts.preserveBlocks ?? false);
   preserveBlocksRef.current = opts.preserveBlocks ?? false;
@@ -105,12 +131,16 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     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);
@@ -191,19 +221,30 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     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: string) => {
-      if (!endpointUrl || !input.trim() || isStreaming) return;
+      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();
@@ -216,7 +257,7 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
         await hydrationRef.current;
       }
       if (controller.signal.aborted) {
-        setIsStreaming(false);
+        setStatus("ready");
         abortRef.current = null;
         return;
       }
@@ -250,6 +291,10 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
           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;
@@ -257,6 +302,26 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
                 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
@@ -272,8 +337,21 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
               }
             } 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);
+            } 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.
+            // `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.
           }
         }
       } catch (e) {
@@ -281,7 +359,8 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
           setError(e instanceof Error ? e.message : "failed to reach agent");
         }
       } 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
@@ -296,8 +375,23 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
         }
       }
     },
-    [endpointUrl, appId, isStreaming],
+    [endpointUrl, appId, status],
   );
 
-  return { messages, send, isStreaming, error, threadId, abort, reset, reduceResult, historyCards };
+  return {
+    messages,
+    send,
+    status,
+    activeTool,
+    error,
+    threadId,
+    abort,
+    reset,
+    reduceResult,
+    historyCards,
+    profileConsentRequest,
+    clearProfileConsentRequest,
+    profileLinkRequest,
+    clearProfileLinkRequest,
+  };
 }