@guuey/agent-client 0.1.0

package/src/react.ts

@@ -0,0 +1,13 @@
+/**
+ * React entry point (`@guuey/agent-client/react`).
+ *
+ * The `useAgentInvoke` hook is the only React-coupled surface — the root
+ * subpath (`@guuey/agent-client`) stays React-free (pure SSE helpers, the
+ * history reader, and the web adapters). Consumers that only need those never
+ * import React at all; consumers that render chat import the hook from here.
+ */
+export { useAgentInvoke, applyHistoryResult, type HistoryApplication } from "./useAgentInvoke";
+// The block-preserving transcript surfaces `AgReduceResult`; re-export it (and
+// `AgEvent`) here so `./react` consumers can type `reduceResult` without a
+// direct `@silverprotocol/core` import.
+export type { AgEvent, AgReduceResult } from "@silverprotocol/core";

package/src/sse.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 function parseSseEvents(buffer: string): { events: ParsedSseEvent[]; rest: string } {
+  const events: ParsedSseEvent[] = [];
+  const parts = buffer.split("\n\n");
+  const rest = parts.pop() ?? "";
+  for (const block of parts) {
+    let event = "message";
+    const dataLines: string[] = [];
+    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: unknown = 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: unknown): boolean {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    (data as { type?: unknown }).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: string, data: unknown): string {
+  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: unknown): string {
+  if (typeof data !== "object" || data === null) return "";
+  const type = (data as { type?: unknown }).type;
+  if (type === "text.delta") {
+    const delta = (data as { delta?: unknown }).delta;
+    return typeof delta === "string" ? delta : "";
+  }
+  if (type === "assistant") {
+    const message = (data as { message?: unknown }).message;
+    if (typeof message === "object" && message !== null && "content" in message) {
+      const content = (message as { content?: unknown }).content;
+      if (Array.isArray(content)) {
+        return content
+          .filter(
+            (b): b is { type: "text"; text: string } =>
+              typeof b === "object" &&
+              b !== null &&
+              (b as { type?: unknown }).type === "text" &&
+              typeof (b as { text?: unknown }).text === "string",
+          )
+          .map((b) => b.text)
+          .join("");
+      }
+    }
+    return "";
+  }
+  if (type === "result") {
+    const subtype = (data as { subtype?: unknown }).subtype;
+    const result = (data as { result?: unknown }).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: unknown, key: string): string | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const v = (data as Record<string, unknown>)[key];
+  return typeof v === "string" ? v : undefined;
+}

package/src/types.ts

@@ -0,0 +1,153 @@
+/**
+ * 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[];
+}

package/src/useAgentInvoke.ts

@@ -0,0 +1,303 @@
+/**
+ * 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, type AgReduceResult } from "@silverprotocol/core";
+import { parseSseEvents, reduceAssistantText, stringField } from "./sse";
+import { ingestMessageFrame } from "./blocks";
+import type {
+  AgentInvokeAdapters,
+  AgentMessage,
+  HistoryCard,
+  HistoryLoadResult,
+  UseAgentInvokeOptions,
+  UseAgentInvokeReturn,
+} from "./types";
+
+function threadStorageKey(appId: string | undefined): string {
+  return `guuey:thread:${appId ?? "default"}`;
+}
+
+/** 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 function applyHistoryResult(
+  result: HistoryLoadResult,
+  currentMessages: AgentMessage[],
+): HistoryApplication {
+  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: UseAgentInvokeOptions): UseAgentInvokeReturn {
+  const { endpointUrl, appId } = opts;
+  const [messages, setMessages] = useState<AgentMessage[]>([]);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [threadId, setThreadId] = useState<string | null>(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<AgReduceResult | null>(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<HistoryCard[]>([]);
+
+  const abortRef = useRef<AbortController | null>(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<string | null>(null);
+  const adaptersRef = useRef<AgentInvokeAdapters>(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<Reducer | null>(null);
+  const preserveBlocksRef = useRef<boolean>(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<Promise<void> | null>(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: HistoryLoadResult;
+      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: string) => {
+      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: string) => {
+        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 };
+}