@guuey/agent-client 0.1.0

package/dist/sse.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure SSE helpers for the base-platform invoke contract. Zero React / DOM /
+ * platform dependencies — unit-tested in isolation (`sse.test.ts`) and shared
+ * verbatim across web (Studio) and React-Native (Portal).
+ */
+export interface ParsedSseEvent {
+    event: string;
+    data: unknown;
+}
+/**
+ * Parse complete `event:`/`data:` frames out of an SSE buffer. Returns the
+ * parsed events plus the unparsed remainder (a partial trailing frame). Frames
+ * are separated by a blank line; `data:` JSON is parsed best-effort.
+ */
+export declare function parseSseEvents(buffer: string): {
+    events: ParsedSseEvent[];
+    rest: string;
+};
+/**
+ * Fold one `message` SSE payload into the running assistant text. `assistant`
+ * messages APPEND (streaming). The success `result` message carries the SAME
+ * final text, so it REPLACES rather than appends — otherwise the answer renders
+ * twice. The result is also the fallback for result-only turns.
+ */
+export declare function reduceAssistantText(current: string, data: unknown): string;
+/**
+ * Best-effort assistant text from one `message` payload — BOTH protocols:
+ *
+ *  - **silver (the pod default)**: AgJSON events — `text.delta` carries the
+ *    streamed text in `.delta`; every other event family (turn/message/tool
+ *    lifecycle) contributes "". AgJSON never resends the final text, so
+ *    deltas are append-only (no result-replacement leg).
+ *  - **bypass**: SDKMessage shapes — text blocks off an `assistant` message;
+ *    the success `result` string as fallback/replacement.
+ *
+ * The silver arm was MISSING while silver became the pod default — live
+ * portal/studio chat rendered EMPTY assistant messages (0.3.2 coverage
+ * audit G14, confirmed by reducing a live wire capture to "").
+ */
+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;
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -0,0 +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"}

package/dist/sse.js

@@ -0,0 +1,107 @@
+/**
+ * Pure SSE helpers for the base-platform invoke contract. Zero React / DOM /
+ * platform dependencies — unit-tested in isolation (`sse.test.ts`) and shared
+ * verbatim across web (Studio) and React-Native (Portal).
+ */
+/**
+ * Parse complete `event:`/`data:` frames out of an SSE buffer. Returns the
+ * parsed events plus the unparsed remainder (a partial trailing frame). Frames
+ * are separated by a blank line; `data:` JSON is parsed best-effort.
+ */
+export function parseSseEvents(buffer) {
+    const events = [];
+    const parts = buffer.split("\n\n");
+    const rest = parts.pop() ?? "";
+    for (const block of parts) {
+        let event = "message";
+        const dataLines = [];
+        for (const line of block.split("\n")) {
+            if (line.startsWith("event:"))
+                event = line.slice(6).trim();
+            else if (line.startsWith("data:"))
+                dataLines.push(line.slice(5).trim());
+        }
+        if (dataLines.length === 0)
+            continue;
+        let data = dataLines.join("\n");
+        try {
+            data = JSON.parse(dataLines.join("\n"));
+        }
+        catch {
+            /* leave as raw string */
+        }
+        events.push({ event, data });
+    }
+    return { events, rest };
+}
+function isResultMessage(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        data.type === "result");
+}
+/**
+ * Fold one `message` SSE payload into the running assistant text. `assistant`
+ * messages APPEND (streaming). The success `result` message carries the SAME
+ * final text, so it REPLACES rather than appends — otherwise the answer renders
+ * twice. The result is also the fallback for result-only turns.
+ */
+export function reduceAssistantText(current, data) {
+    if (isResultMessage(data)) {
+        const result = extractAssistantText(data);
+        return result || current;
+    }
+    return current + extractAssistantText(data);
+}
+/**
+ * Best-effort assistant text from one `message` payload — BOTH protocols:
+ *
+ *  - **silver (the pod default)**: AgJSON events — `text.delta` carries the
+ *    streamed text in `.delta`; every other event family (turn/message/tool
+ *    lifecycle) contributes "". AgJSON never resends the final text, so
+ *    deltas are append-only (no result-replacement leg).
+ *  - **bypass**: SDKMessage shapes — text blocks off an `assistant` message;
+ *    the success `result` string as fallback/replacement.
+ *
+ * The silver arm was MISSING while silver became the pod default — live
+ * portal/studio chat rendered EMPTY assistant messages (0.3.2 coverage
+ * audit G14, confirmed by reducing a live wire capture to "").
+ */
+export function extractAssistantText(data) {
+    if (typeof data !== "object" || data === null)
+        return "";
+    const type = data.type;
+    if (type === "text.delta") {
+        const delta = data.delta;
+        return typeof delta === "string" ? delta : "";
+    }
+    if (type === "assistant") {
+        const message = data.message;
+        if (typeof message === "object" && message !== null && "content" in message) {
+            const content = message.content;
+            if (Array.isArray(content)) {
+                return content
+                    .filter((b) => typeof b === "object" &&
+                    b !== null &&
+                    b.type === "text" &&
+                    typeof b.text === "string")
+                    .map((b) => b.text)
+                    .join("");
+            }
+        }
+        return "";
+    }
+    if (type === "result") {
+        const subtype = data.subtype;
+        const result = data.result;
+        if (subtype === "success" && typeof result === "string")
+            return result;
+    }
+    return "";
+}
+/** Read a string field off an SSE `data` object, or undefined. */
+export function stringField(data, key) {
+    if (typeof data !== "object" || data === null)
+        return undefined;
+    const v = data[key];
+    return typeof v === "string" ? v : undefined;
+}

package/dist/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Public types for the base-platform chat client.
+ *
+ * The hook's behaviour is platform-agnostic; its three host couplings —
+ * thread-id storage, client-message-id generation, and the network transport
+ * (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
+ * `MessageStorageAdapter` injection pattern.
+ */
+import type { AgReduceResult, JsonValue } from "@silverprotocol/core";
+/** A flat chat turn as rendered by the consumer UI. */
+export interface AgentMessage {
+    role: "user" | "assistant";
+    text: string;
+}
+/**
+ * A persisted generative-UI card rehydrated from thread history — the verbatim
+ * `AgArtifact` snapshot the pod stored on a `kind: "card"` row, tagged with its
+ * transcript position. A block-preserving renderer interleaves these with
+ * {@link AgentMessage}s (and the live {@link UseAgentInvokeReturn.reduceResult}
+ * fold) by ascending `seq`. `cardSnapshot` is forwarded opaquely from the read
+ * plane — the SDK does not re-parse it into AgEvents.
+ */
+export interface HistoryCard {
+    seq: number;
+    at: string;
+    cardSnapshot: JsonValue;
+}
+/**
+ * Persists the durable `threadId` per app so a reload continues the same
+ * conversation. `load` may be sync (localStorage) or async (AsyncStorage).
+ */
+export interface ThreadIdStore {
+    load(key: string): string | null | Promise<string | null>;
+    save(key: string, threadId: string): void | Promise<void>;
+}
+/** Generates a fresh client-message id (idempotency key for B1 dedup). */
+export type GenerateId = () => string;
+/** One invoke request handed to the transport. */
+export interface InvokeRequest {
+    /** Fully-resolved POST target (already normalised to end in `/agent/invoke`). */
+    url: string;
+    /** JSON request body: `{ input, threadId?, clientMessageId }`. */
+    body: unknown;
+    /** Aborts the in-flight stream. */
+    signal: AbortSignal;
+}
+/**
+ * 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.
+ */
+export type InvokeTransport = (req: InvokeRequest) => AsyncIterable<string>;
+/**
+ * The persisted transcript for a thread, or a signal that it no longer exists.
+ *
+ * `cards` is populated ONLY when the loader opts in (see
+ * `fetchThreadHistory`'s `includeCards`); the default text-only mapping omits
+ * it so existing text-only consumers (portal-native) are unaffected. When
+ * present it carries the thread's persisted {@link HistoryCard}s for a
+ * block-preserving renderer to interleave by `seq`.
+ */
+export type HistoryLoadResult = {
+    messages: AgentMessage[];
+    cards?: HistoryCard[];
+} | {
+    gone: true;
+};
+/**
+ * Optional seam for rehydrating a chat transcript from a server-side read
+ * after the persisted `threadId` hydrates (see `useAgentInvoke`'s mount
+ * effect). Best-effort: a rejected `load` is logged and skipped, never
+ * blocks chat.
+ */
+export interface AgentInvokeHistoryAdapter {
+    /** Fetch the persisted transcript for a thread. `gone` = 403/404 (stale local id). */
+    load(threadId: string): Promise<HistoryLoadResult>;
+}
+/** The host couplings the hook needs, injected by the consumer. */
+export interface AgentInvokeAdapters {
+    storage: ThreadIdStore;
+    generateId: GenerateId;
+    transport: InvokeTransport;
+    /** Optional: rehydrate the transcript for a hydrated threadId. See {@link AgentInvokeHistoryAdapter}. */
+    history?: AgentInvokeHistoryAdapter;
+}
+export interface UseAgentInvokeOptions {
+    /** Pod base URL (with or without a trailing `/agent/invoke`). Chat is disabled when null. */
+    endpointUrl: string | null;
+    /** Owning app id — namespaces the persisted threadId. */
+    appId?: string;
+    /** Platform host couplings (storage / crypto / transport). */
+    adapters: AgentInvokeAdapters;
+    /**
+     * Opt-in: ALSO fold the full AgJSON (silver-mode) stream into a
+     * block-preserving transcript exposed as {@link UseAgentInvokeReturn.reduceResult},
+     * alongside the always-on flat text surface. Off by default; when off the
+     * reducer is never constructed and the text behaviour is byte-identical.
+     */
+    preserveBlocks?: boolean;
+}
+export interface UseAgentInvokeReturn {
+    messages: AgentMessage[];
+    send: (input: string) => Promise<void>;
+    isStreaming: boolean;
+    error: string | null;
+    threadId: string | null;
+    /** Abort the in-flight turn (the stream stops; partial text is kept). */
+    abort: () => void;
+    reset: () => void;
+    /**
+     * The folded AgJSON transcript, or `null`.
+     *
+     * Contract — **null-until-first-valid-AgEvent** (the documented choice for
+     * the ambiguous "which protocol?" case; see {@link UseAgentInvokeOptions.preserveBlocks}):
+     *
+     *  - `null` whenever `preserveBlocks` is off (the reducer is never built);
+     *  - when `preserveBlocks` is on, `null` UNTIL the per-conversation `Reducer`
+     *    has folded at least one VALID AgEvent, then the reducer's live
+     *    `result()` snapshot (a fresh object on each fold, so it re-renders).
+     *
+     * The hook cannot know a priori whether the pod is in silver or bypass mode.
+     * In **bypass mode** the `message` frames are SDKMessage shapes that never
+     * validate as AgEvents, so nothing folds and `reduceResult` stays `null` for
+     * the whole conversation — the reducer only makes sense for silver AgJSON
+     * frames. `reset()` returns it to `null`. History rehydrate does NOT populate
+     * it — persisted cards surface via {@link historyCards} instead (Task 4), so
+     * a snapshot never has to be lied back into the live reducer.
+     */
+    reduceResult: AgReduceResult | null;
+    /**
+     * Persisted generative-UI cards rehydrated from thread history, ascending by
+     * `seq`. Empty (`[]`) unless the injected history adapter opted into cards
+     * (`fetchThreadHistory({ includeCards: true })`) AND the rehydrate seeded a
+     * transcript. Independent of {@link reduceResult}: `reduceResult` is the
+     * LIVE turn's fold, `historyCards` is the persisted PRIOR turns' cards — a
+     * block-preserving renderer interleaves both (and {@link messages}) by `seq`.
+     * `reset()` clears it back to `[]`.
+     */
+    historyCards: HistoryCard[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * Public types for the base-platform chat client.
+ *
+ * The hook's behaviour is platform-agnostic; its three host couplings —
+ * thread-id storage, client-message-id generation, and the network transport
+ * (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
+ * `MessageStorageAdapter` injection pattern.
+ */
+export {};

package/dist/useAgentInvoke.d.ts

@@ -0,0 +1,20 @@
+import type { AgentMessage, HistoryLoadResult, UseAgentInvokeOptions, UseAgentInvokeReturn } from "./types";
+/** The decision `applyHistoryResult` reaches for a loaded transcript. */
+export type HistoryApplication = {
+    kind: "seed";
+    messages: AgentMessage[];
+} | {
+    kind: "skip";
+} | {
+    kind: "clear";
+};
+/**
+ * Pure decision seam for post-hydration history application (see
+ * `AgentInvokeHistoryAdapter` in `./types`). `gone` always clears the
+ * persisted thread. Otherwise a non-empty transcript seeds the chat UNLESS
+ * the chat has already been touched (`currentMessages.length > 0`) — a
+ * mid-flight send always beats late-arriving history.
+ */
+export declare function applyHistoryResult(result: HistoryLoadResult, currentMessages: AgentMessage[]): HistoryApplication;
+export declare function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeReturn;
+//# sourceMappingURL=useAgentInvoke.d.ts.map

package/dist/useAgentInvoke.d.ts.map

@@ -0,0 +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"}

package/dist/useAgentInvoke.js

@@ -0,0 +1,282 @@
+/**
+ * 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):
+ *
+ *   POST {endpointUrl}/agent/invoke
+ *     body: { input, threadId?, clientMessageId }
+ *   ← SSE:
+ *     event: session  { sessionId, userId, threadId? }
+ *     event: message  <SDKMessage JSON>          (assistant turns + result)
+ *     event: done     { stopReason, threadId?, userSeq?, agentSeq? }
+ *     event: error    { code, message }
+ *
+ * History persistence (B1) is server-side: the pod resolves a durable Thread
+ * from the `threadId` we replay and persists each turn. The threadId is kept
+ * in consumer-provided storage (per app) so a reload continues the same
+ * conversation.
+ *
+ * Platform-agnostic: storage, id generation, and the network transport (which
+ * also carries anonymous identity) are injected via `opts.adapters`. See
+ * `./web-adapters` for the web (Studio) bundle; Portal supplies RN adapters.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Reducer } from "@silverprotocol/core";
+import { parseSseEvents, reduceAssistantText, stringField } from "./sse";
+import { ingestMessageFrame } from "./blocks";
+function threadStorageKey(appId) {
+    return `guuey:thread:${appId ?? "default"}`;
+}
+/**
+ * Pure decision seam for post-hydration history application (see
+ * `AgentInvokeHistoryAdapter` in `./types`). `gone` always clears the
+ * persisted thread. Otherwise a non-empty transcript seeds the chat UNLESS
+ * the chat has already been touched (`currentMessages.length > 0`) — a
+ * mid-flight send always beats late-arriving history.
+ */
+export function applyHistoryResult(result, currentMessages) {
+    if ("gone" in result)
+        return { kind: "clear" };
+    if (currentMessages.length > 0 || result.messages.length === 0)
+        return { kind: "skip" };
+    return { kind: "seed", messages: result.messages };
+}
+export function useAgentInvoke(opts) {
+    const { endpointUrl, appId } = opts;
+    const [messages, setMessages] = useState([]);
+    const [isStreaming, setIsStreaming] = useState(false);
+    const [error, setError] = 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
+    // starts null and only becomes non-null once the per-conversation reducer
+    // folds a valid AgEvent (so it stays null forever in bypass mode).
+    const [reduceResult, setReduceResult] = useState(null);
+    // Persisted generative-UI cards rehydrated from history (see return-type
+    // contract). Independent of the live `reduceResult` fold — populated only
+    // when a card-carrying history load seeds the transcript.
+    const [historyCards, setHistoryCards] = 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
+    // sidesteps the async-hydration race).
+    const threadIdRef = useRef(null);
+    const adaptersRef = useRef(opts.adapters);
+    adaptersRef.current = opts.adapters;
+    // The per-conversation AgJSON reducer (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.
+    const reducerRef = useRef(null);
+    const preserveBlocksRef = useRef(opts.preserveBlocks ?? false);
+    preserveBlocksRef.current = opts.preserveBlocks ?? false;
+    // The in-flight threadId hydration for the current appId. `send` awaits it
+    // so a fast first send replays the persisted thread instead of minting a
+    // new (orphan) one — critical on async stores (AsyncStorage).
+    const hydrationRef = useRef(null);
+    // Hydrate the persisted threadId on mount / app change. Switching apps
+    // starts a FRESH session: reset everything first so one agent's thread +
+    // transcript never leaks into another (the hook is shared + appId-keyed,
+    // and a consumer may swap appId in place without remounting). Tolerates a
+    // sync (localStorage) or async (AsyncStorage) store.
+    useEffect(() => {
+        abortRef.current?.abort();
+        threadIdRef.current = null;
+        setThreadId(null);
+        setMessages([]);
+        setError(null);
+        setIsStreaming(false);
+        // 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([]);
+        let cancelled = false;
+        const key = threadStorageKey(appId);
+        const hydration = Promise.resolve(adaptersRef.current.storage.load(key))
+            .then((id) => {
+            if (!cancelled && id && !threadIdRef.current) {
+                threadIdRef.current = id;
+                setThreadId(id);
+            }
+        })
+            .catch(() => {
+            // Storage unavailable (private mode / keychain error) — no persisted
+            // thread; the session simply starts fresh.
+        });
+        // `hydrationRef` (which `send` awaits) resolves at threadId-load time —
+        // history rehydration below is a SEPARATE, un-awaited continuation so a
+        // slow history endpoint never gates the user's first send.
+        hydrationRef.current = hydration;
+        void hydration.then(async () => {
+            // Best-effort transcript rehydration: only runs when a persisted
+            // threadId was actually found and a history adapter was supplied.
+            // Never throws — a failed/missing history load simply leaves the
+            // chat empty and the user starts fresh.
+            const tid = threadIdRef.current;
+            const history = adaptersRef.current.history;
+            if (cancelled || !tid || !history)
+                return;
+            let result;
+            try {
+                result = await history.load(tid);
+            }
+            catch {
+                return; // best-effort: offline / transient — chat continues without history
+            }
+            if (cancelled)
+                return;
+            if ("gone" in result) {
+                // Ordering intent: only clear if no concurrent send() has since
+                // established a fresh threadId (a session event mutates
+                // `threadIdRef` + saves it). Clearing/overwriting storage here after
+                // that would clobber a freshly-valid id with '' on async stores.
+                if (threadIdRef.current !== tid)
+                    return;
+                threadIdRef.current = null;
+                setThreadId(null);
+                void adaptersRef.current.storage.save(threadStorageKey(appId), "");
+                return;
+            }
+            // Single decision authority: `applyHistoryResult` runs INSIDE the
+            // functional update against the live `prev`, so a mid-flight send()'s
+            // optimistic messages always beat late-arriving history.
+            setMessages((prev) => {
+                const application = applyHistoryResult(result, prev);
+                return application.kind === "seed" ? application.messages : prev;
+            });
+            // Surface any persisted cards the loader opted to include (independent of
+            // the text seed decision — cards are their own render lane, never
+            // optimistically added by send(), so there is nothing to clobber). Empty
+            // when the adapter is text-only (no `cards` key on the result).
+            if ("cards" in result && result.cards && result.cards.length > 0) {
+                setHistoryCards(result.cards);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [appId]);
+    const abort = useCallback(() => {
+        abortRef.current?.abort();
+    }, []);
+    const reset = useCallback(() => {
+        abortRef.current?.abort();
+        // Start a genuinely fresh conversation: forget the durable thread so the
+        // next send() mints a new one (not append to the old), clear the
+        // persisted key so a reload doesn't rehydrate the old transcript, and
+        // wipe the visible state.
+        threadIdRef.current = null;
+        setThreadId(null);
+        void adaptersRef.current.storage.save(threadStorageKey(appId), "");
+        setMessages([]);
+        setError(null);
+        setIsStreaming(false);
+        // 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([]);
+    }, [appId]);
+    const send = useCallback(async (input) => {
+        if (!endpointUrl || !input.trim() || isStreaming)
+            return;
+        setError(null);
+        setIsStreaming(true);
+        setMessages((prev) => [...prev, { role: "user", text: input }, { role: "assistant", text: "" }]);
+        const controller = new AbortController();
+        abortRef.current = controller;
+        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
+        // clobbers the stored id. `hydrationRef` never rejects (it self-catches).
+        if (hydrationRef.current) {
+            await hydrationRef.current;
+        }
+        if (controller.signal.aborted) {
+            setIsStreaming(false);
+            abortRef.current = null;
+            return;
+        }
+        let assistantText = "";
+        const renderAssistant = (text) => {
+            assistantText = text;
+            setMessages((prev) => {
+                const next = prev.slice();
+                // The trailing entry is the assistant bubble we just pushed.
+                next[next.length - 1] = { role: "assistant", text };
+                return next;
+            });
+        };
+        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 body = {
+                input,
+                ...(threadIdRef.current ? { threadId: threadIdRef.current } : {}),
+                clientMessageId: adapters.generateId(),
+            };
+            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") {
+                        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") {
+                        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");
+                    }
+                    // `done` needs no handling — the stream closes after it.
+                }
+            }
+        }
+        catch (e) {
+            if (!controller.signal.aborted) {
+                setError(e instanceof Error ? e.message : "failed to reach agent");
+            }
+        }
+        finally {
+            setIsStreaming(false);
+            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
+            // blank assistant message.
+            if (controller.signal.aborted && assistantText === "") {
+                setMessages((prev) => {
+                    const last = prev[prev.length - 1];
+                    return last && last.role === "assistant" && last.text === ""
+                        ? prev.slice(0, -1)
+                        : prev;
+                });
+            }
+        }
+    }, [endpointUrl, appId, isStreaming]);
+    return { messages, send, isStreaming, error, threadId, abort, reset, reduceResult, historyCards };
+}