@guuey/agent-client 0.1.0

package/dist/web-adapters.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Web (browser / Next.js) host adapters for {@link useAgentInvoke}.
+ *
+ * Studio builds its bundle via {@link createWebAdapters}. The implementations
+ * touch `window.localStorage`, `crypto`, and `fetch` only inside their
+ * functions — never at module load — so this file is import-safe under SSR
+ * (the functions guard on `typeof window`).
+ */
+import type { AgentInvokeAdapters, InvokeRequest, ThreadIdStore } from "./types";
+/**
+ * Thrown when the pod returns a non-2xx status on `/agent/invoke` (before any
+ * SSE stream opens). Carries the pod's structured `{ code, message }` when
+ * present — e.g. a `QUOTA_EXCEEDED` 429 whose message ("…reached its plan
+ * generation limit…") the chat UI should surface — falling back to the bare
+ * status for non-JSON failures.
+ */
+export declare class AgentResponseError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+/** Persists the threadId in `window.localStorage` (synchronously). */
+export declare const localStorageThreadStore: ThreadIdStore;
+/** Crypto-strong client-message id, with a non-crypto fallback. */
+export declare function webGenerateId(): string;
+/**
+ * Web SSE transport. 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.
+ * Reads the body via `ReadableStream.getReader()` (browser).
+ */
+export declare function fetchStreamTransport(req: InvokeRequest, accessToken?: string | null): AsyncGenerator<string>;
+export interface CreateWebAdaptersOptions {
+    /**
+     * Public read-plane base (ending in `/v1`) for transcript history. When
+     * omitted, no history adapter is installed and reloads start empty.
+     */
+    apiBaseUrl?: string;
+    /**
+     * 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.
+     */
+    getAccessToken?: () => Promise<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.
+ */
+export declare function createWebAdapters(opts?: CreateWebAdaptersOptions): AgentInvokeAdapters;
+//# sourceMappingURL=web-adapters.d.ts.map

package/dist/web-adapters.d.ts.map

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

package/dist/web-adapters.js

@@ -0,0 +1,135 @@
+import { fetchThreadHistory } from "./history";
+/**
+ * Thrown when the pod returns a non-2xx status on `/agent/invoke` (before any
+ * SSE stream opens). Carries the pod's structured `{ code, message }` when
+ * present — e.g. a `QUOTA_EXCEEDED` 429 whose message ("…reached its plan
+ * generation limit…") the chat UI should surface — falling back to the bare
+ * status for non-JSON failures.
+ */
+export class AgentResponseError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "AgentResponseError";
+    }
+}
+/** Persists the threadId in `window.localStorage` (synchronously). */
+export const localStorageThreadStore = {
+    load(key) {
+        if (typeof window === "undefined")
+            return null;
+        try {
+            return window.localStorage.getItem(key);
+        }
+        catch {
+            return null;
+        }
+    },
+    save(key, threadId) {
+        if (typeof window === "undefined")
+            return;
+        try {
+            window.localStorage.setItem(key, threadId);
+        }
+        catch {
+            /* private mode / blocked storage — threadId stays in-memory only */
+        }
+    },
+};
+/** Crypto-strong client-message id, with a non-crypto fallback. */
+export function webGenerateId() {
+    if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+        return crypto.randomUUID();
+    }
+    return `cmid-${Date.now()}-${Math.floor(Math.random() * 1e9)}`;
+}
+/**
+ * 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.
+ * Reads the body via `ReadableStream.getReader()` (browser).
+ */
+export async function* fetchStreamTransport(req, accessToken) {
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "text/event-stream",
+    };
+    const init = {
+        method: "POST",
+        signal: req.signal,
+        headers,
+        body: JSON.stringify(req.body),
+    };
+    if (accessToken) {
+        headers.Authorization = `Bearer ${accessToken}`;
+    }
+    else {
+        init.credentials = "include";
+    }
+    const resp = await fetch(req.url, init);
+    if (!resp.ok || !resp.body) {
+        // Surface a structured pod error ({ code, message }) when present — e.g. a
+        // QUOTA_EXCEEDED 429 carries an upgrade message the UI should show. Fall
+        // back to the bare status for non-JSON failures.
+        const body = await resp.json().catch(() => null);
+        let message = `agent responded ${resp.status}`;
+        let code;
+        if (body !== null && typeof body === "object") {
+            if ("message" in body && typeof body.message === "string" && body.message) {
+                message = body.message;
+            }
+            if ("code" in body && typeof body.code === "string") {
+                code = body.code;
+            }
+        }
+        throw new AgentResponseError(message, resp.status, code);
+    }
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        yield decoder.decode(value, { stream: true });
+    }
+}
+/**
+ * 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.
+ */
+export function createWebAdapters(opts = {}) {
+    const { apiBaseUrl, getAccessToken } = opts;
+    const transport = async function* (req) {
+        const token = getAccessToken ? await getAccessToken() : null;
+        yield* fetchStreamTransport(req, token);
+    };
+    const adapters = {
+        storage: localStorageThreadStore,
+        generateId: webGenerateId,
+        transport,
+    };
+    if (apiBaseUrl && getAccessToken) {
+        adapters.history = {
+            load: async (threadId) => {
+                const token = await getAccessToken();
+                // No readable identity → leave the chat empty (skip) rather than
+                // `gone`, which would clear the persisted threadId.
+                if (!token)
+                    return { messages: [] };
+                return fetchThreadHistory({
+                    baseUrl: apiBaseUrl,
+                    threadId,
+                    requestInit: { headers: { Authorization: `Bearer ${token}` } },
+                });
+            },
+        };
+    }
+    return adapters;
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@guuey/agent-client",
+  "version": "0.1.0",
+  "description": "Client SDK for Guuey's agent runtime: the `useAgentInvoke` React hook + pure SSE helpers that speak the /agent/invoke streaming contract, plus the paginated thread-history read plane. Host adapters (storage / id / transport) are injected, so it runs on web (Next) and React Native alike.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "react-native": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "react-native": "./src/react.ts",
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    }
+  },
+  "dependencies": {
+    "@silverprotocol/core": "0.3.2"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.0.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.0.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "guuey",
+    "agent",
+    "sse",
+    "chat",
+    "react",
+    "client"
+  ],
+  "homepage": "https://guuey.com",
+  "bugs": {
+    "url": "https://github.com/loqu-co/guuey/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withguuey/guuey-sdks.git",
+    "directory": "packages/agent-client"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/block-ui.ts

@@ -0,0 +1,196 @@
+/**
+ * Pure block-walk / resource-narrowing helpers for a block-preserving agent
+ * transcript — no React, no DOM, so the narrowing logic stays unit-testable in
+ * isolation (this package's vitest runs a `node` environment) and can be shared
+ * by every host renderer (Studio's `AgentBlocks`, Portal-web's agent chat).
+ *
+ * The pod's AgJSON wire carries generative-UI payloads on `tool.done` events,
+ * which the reducer folds onto `tool-result` blocks. Two channels reach us:
+ *
+ *  1. **`uiData`** — the MCP-Apps *surface* channel. The pod's Claude facet
+ *     routes a tool result's `structuredContent` here when the server stamped
+ *     `_meta.ui`. Any resource here is intended as UI.
+ *  2. **`provider-raw` content blocks** — an MCP embedded `resource` content
+ *     part does NOT survive as a first-class `resource` AgBlock in the Claude
+ *     facet; it degrades to `{ type:'provider-raw', vendor, raw:<part> }`. So a
+ *     `ui://` resource can be hiding inside `provider-raw.raw` and must be
+ *     scanned for defensively.
+ *
+ * The resource-narrowing (opaque `JsonValue` → typed payload) mirrors the
+ * proven `create-agentic-app` web template — structural validation, never a cast.
+ */
+import type { AgBlock, AgMessage, JsonValue } from "@silverprotocol/core";
+import type { HistoryCard } from "./types";
+
+/** A narrowed MCP embedded UI resource (the `_meta.ui.resource` shape). */
+export interface McpUiResourcePayload {
+  uri: string;
+  mimeType?: string;
+  text?: string;
+  blob?: string;
+}
+
+/** Narrow an opaque `JsonValue` to a plain (non-array) JSON object. */
+export function isJsonObject(v: JsonValue | undefined): v is { [key: string]: JsonValue } {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * A JSON object → an MCP UI resource, if it has a `uri` plus renderable
+ * payload (`text` or base64 `blob`). Returns `undefined` for anything else.
+ */
+export function asResourcePayload(v: JsonValue | undefined): McpUiResourcePayload | undefined {
+  if (!isJsonObject(v)) return undefined;
+  if (typeof v.uri !== "string") return undefined;
+  if (typeof v.text !== "string" && typeof v.blob !== "string") return undefined;
+  return {
+    uri: v.uri,
+    ...(typeof v.mimeType === "string" ? { mimeType: v.mimeType } : {}),
+    ...(typeof v.text === "string" ? { text: v.text } : {}),
+    ...(typeof v.blob === "string" ? { blob: v.blob } : {}),
+  };
+}
+
+/**
+ * Does a `tool-result` block's `uiData` carry an MCP embedded UI resource?
+ * Accepts the resource inlined directly, or wrapped as `{ resource: {...} }`
+ * (the shape an MCP `resource` content part carries). No `ui://` scheme gate
+ * here on purpose: `uiData` is the explicit *surface* channel (the server
+ * stamped `_meta.ui`), so any resource on it is meant to render.
+ */
+export function asUiResource(uiData: JsonValue | undefined): McpUiResourcePayload | undefined {
+  if (!isJsonObject(uiData)) return undefined;
+  const direct = asResourcePayload(uiData);
+  if (direct) return direct;
+  return asResourcePayload(uiData.resource);
+}
+
+/**
+ * Scan a `provider-raw` block's `raw` (the vendor tool_result content part)
+ * for a *generative-UI* resource. Unlike {@link asUiResource}, this path IS
+ * gated on the `ui://` scheme: `provider-raw` degradation is a lossy catch-all,
+ * so a plain file/text resource riding it is NOT a UI to mount — only the
+ * mcp-ui `ui://` convention is.
+ */
+export function scanProviderRawForUiResource(
+  raw: JsonValue | undefined,
+): McpUiResourcePayload | undefined {
+  if (!isJsonObject(raw)) return undefined;
+  const candidate =
+    raw.resource !== undefined ? asResourcePayload(raw.resource) : asResourcePayload(raw);
+  if (!candidate) return undefined;
+  return candidate.uri.startsWith("ui://") ? candidate : undefined;
+}
+
+/**
+ * Extract a mountable UI resource from an opaque AgBlock-shaped `JsonValue`
+ * (used for persisted card snapshot parts, which arrive untyped). Dispatches
+ * by `block.type`:
+ *   - `tool-result` → its `uiData` surface channel
+ *   - `provider-raw` → a `ui://` resource hiding in `raw`
+ *   - `resource`     → a first-class embedded resource (gated on `ui://`)
+ * Everything else → `undefined`.
+ */
+export function blockUiResource(block: JsonValue): McpUiResourcePayload | undefined {
+  if (!isJsonObject(block)) return undefined;
+  switch (block.type) {
+    case "tool-result":
+      return asUiResource(block.uiData);
+    case "provider-raw":
+      return scanProviderRawForUiResource(block.raw);
+    case "resource": {
+      const r = asResourcePayload(block.resource);
+      return r && r.uri.startsWith("ui://") ? r : undefined;
+    }
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * A live `tool-result` AgBlock → its mountable UI resource, checking BOTH
+ * channels the Claude facet uses:
+ *   1. the `uiData` surface channel (server stamped `_meta.ui`), and
+ *   2. an embedded `ui://` resource that degraded into a `provider-raw`
+ *      content part inside the tool result (MCP `resource` parts do NOT survive
+ *      as first-class `resource` AgBlocks here).
+ * First-class `resource` content parts are intentionally not scanned in this
+ * typed live path (the Claude facet never emits them); the untyped card path
+ * ({@link blockUiResource}) covers them for other facets' persisted snapshots.
+ */
+export function toolResultUiResource(
+  block: Extract<AgBlock, { type: "tool-result" }>,
+): McpUiResourcePayload | undefined {
+  const fromUiData = asUiResource(block.uiData);
+  if (fromUiData) return fromUiData;
+  for (const part of block.content) {
+    if (part.type === "provider-raw") {
+      const found = scanProviderRawForUiResource(part.raw);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * A persisted `HistoryCard`'s `cardSnapshot` → a mountable UI resource. The
+ * snapshot is the verbatim `AgArtifact` the pod stored (`{ parts: AgBlock[] }`),
+ * so walk its `parts` for the first block that yields a resource; fall back to
+ * treating the snapshot root itself as a block.
+ *
+ * NOTE (`no-ggui-tools`): a ggui-rendered card carries NO inline HTML resource —
+ * its UI rides `_meta.ggui.bootstrap` and mounts via `@ggui-ai/react`'s
+ * `McpAppIframe`. That branch is OUT OF SCOPE for v1 (deferred-pending-capture).
+ * So a real ggui card resolves to `undefined` here and renders as the host's
+ * coherent placeholder, not a broken mount.
+ */
+export function cardUiResource(cardSnapshot: JsonValue): McpUiResourcePayload | undefined {
+  if (!isJsonObject(cardSnapshot)) return undefined;
+  const parts = cardSnapshot.parts;
+  if (Array.isArray(parts)) {
+    for (const part of parts) {
+      const found = blockUiResource(part);
+      if (found) return found;
+    }
+  }
+  return blockUiResource(cardSnapshot);
+}
+
+/**
+ * The resource's HTML: inline `text` wins; else base64-decode `blob`. `atob`
+ * alone yields a Latin-1 string (mojibake on multibyte UTF-8), so decode via
+ * bytes + `TextDecoder`. Invalid base64 → `undefined` (no renderable payload).
+ */
+export function resourceHtml(resource: McpUiResourcePayload): string | undefined {
+  if (resource.text !== undefined) return resource.text;
+  if (resource.blob !== undefined) {
+    try {
+      return new TextDecoder().decode(Uint8Array.from(atob(resource.blob), (c) => c.charCodeAt(0)));
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The tool name for a `tool-result` block, read off its paired `tool-call`
+ * block in the same message (the reducer keeps both in one message's content).
+ * Falls back to `"tool"` when the pair is missing.
+ */
+export function toolNameFor(message: AgMessage, toolCallId: string): string {
+  for (const b of message.content) {
+    if (b.type === "tool-call" && b.toolCallId === toolCallId) return b.name;
+  }
+  return "tool";
+}
+
+/**
+ * Persisted cards, ascending by transcript `seq` (stable; input untouched).
+ * These are PRIOR-turn cards — they always precede the live fold, so a
+ * block-preserving renderer surfaces them first (e.g. under an "Earlier in
+ * this conversation" divider).
+ */
+export function sortHistoryCards(cards: readonly HistoryCard[]): HistoryCard[] {
+  return [...cards].sort((a, b) => a.seq - b.seq);
+}

package/src/blocks.ts

@@ -0,0 +1,32 @@
+/**
+ * Frame → AgEvent[] ingestion for the opt-in block-preserving transcript.
+ *
+ * The wire carries ONE `message` frame per SSE event, but the *payload* shape
+ * differs by producer:
+ *
+ *  - the deployed pod (`nocode-runtime`) emits a SINGLE AgEvent JSON OBJECT per
+ *    frame (`sendEvent(res, 'message', e)`);
+ *  - the CLI dev server (`guuey dev --serve`) batches an AgEvent[] ARRAY per
+ *    frame (`sendEvent(res, 'message', batch)`).
+ *
+ * `ingestMessageFrame` is tolerant of BOTH shapes (object OR array). Validation
+ * is delegated to `@silverprotocol/core`'s `ingestAgEvents`, the library's own
+ * parse-known-else-skip consumer validator: any element that is not a valid
+ * AgJSON event — including bypass-mode SDKMessage shapes (`type: "assistant"` /
+ * `type: "result"`, which are NOT AgEvent `type` literals) — is dropped rather
+ * than crashing the stream or forcing a type lie. A frame that is not even a
+ * JSON value (`undefined`, a function, `NaN`, …) yields `[]`.
+ *
+ * The `unknown` → `JsonValue` narrowing is done at runtime via the exported
+ * `JsonValue` schema's `safeParse` (the same posture the Claude facet uses for
+ * provider-raw parts) — no assertion, no `as`.
+ */
+import { ingestAgEvents, JsonValue, type AgEvent } from "@silverprotocol/core";
+
+/** Ingest one `message` SSE payload (object OR array) into validated AgEvents. */
+export function ingestMessageFrame(raw: unknown): AgEvent[] {
+  const parsed = JsonValue.safeParse(raw);
+  if (!parsed.success) return [];
+  const value = parsed.data;
+  return ingestAgEvents(Array.isArray(value) ? value : [value]);
+}

package/src/history.ts

@@ -0,0 +1,126 @@
+/**
+ * Shared transcript-history reader for the base-platform chat client.
+ *
+ * Reads a thread's persisted transcript from the public read plane
+ * (`GET {baseUrl}/threads/{id}/messages`, paginated by `nextToken`) so a
+ * reload can repaint history before any SSE traffic starts. Host-agnostic:
+ * the caller supplies the base URL and a `requestInit` carrying whatever
+ * identity that host can present (a `Authorization: Bearer` header on web /
+ * RN when signed in, an `x-guuey-guest` header for RN guests, cookies via
+ * `credentials: "include"`). Consumed by {@link createWebAdapters}; Portal
+ * has its own copy today and can migrate onto this later.
+ */
+import type { JsonValue } from "@silverprotocol/core";
+import type { AgentMessage, HistoryCard, HistoryLoadResult } from "./types";
+
+/** One row of `GET /v1/threads/:id/messages`. */
+export interface ThreadHistoryRow {
+  seq: number;
+  at: string;
+  kind: string;
+  authorRole: string;
+  text: string | null;
+  /**
+   * The verbatim persisted `AgArtifact` on `kind === "card"` rows; `null` or
+   * absent on text/event rows (the read plane omits it there). Forwarded
+   * opaquely — never re-parsed into AgEvents.
+   */
+  cardSnapshot?: JsonValue | null;
+}
+
+interface ThreadMessagesResponse {
+  rows: ThreadHistoryRow[];
+  nextToken: string | null;
+}
+
+/** Rows requested per history page. */
+const HISTORY_PAGE_LIMIT = 100;
+
+/**
+ * Hard bound on `nextToken` pagination: 10 pages × 100 rows = 1000 messages.
+ * The server pages in ASCENDING seq order and the newest turns arrive on the
+ * LAST pages, so we follow `nextToken` to completion within this cap rather
+ * than stopping at page 1 (which would drop exactly the turns a resuming user
+ * cares about). A >1000-message thread truncates its tail — accepted here;
+ * a server-side `sort=desc`/`from`-seq param would be the fix if it matters.
+ */
+const MAX_HISTORY_PAGES = 10;
+
+/** Project raw rows to chat turns: text rows only, author → role. */
+export function threadHistoryRowsToMessages(rows: ThreadHistoryRow[]): AgentMessage[] {
+  const messages: AgentMessage[] = [];
+  for (const row of rows) {
+    if (row.kind !== "text" || row.text == null) continue;
+    messages.push({ role: row.authorRole === "user" ? "user" : "assistant", text: row.text });
+  }
+  return messages;
+}
+
+/**
+ * Project raw rows to persisted generative-UI cards: `kind === "card"` rows
+ * that actually carry a snapshot, tagged with their transcript position. The
+ * additive counterpart to {@link threadHistoryRowsToMessages} — a
+ * block-preserving consumer merges both by `seq`.
+ */
+export function threadHistoryRowsToCards(rows: ThreadHistoryRow[]): HistoryCard[] {
+  const cards: HistoryCard[] = [];
+  for (const row of rows) {
+    if (row.kind !== "card" || row.cardSnapshot == null) continue;
+    cards.push({ seq: row.seq, at: row.at, cardSnapshot: row.cardSnapshot });
+  }
+  return cards;
+}
+
+export interface ThreadHistoryFetchOptions {
+  /** Public read-plane base, already ending in `/v1`. */
+  baseUrl: string;
+  threadId: string;
+  /** Per-request init merged into each page fetch (headers, credentials). */
+  requestInit?: RequestInit;
+  /**
+   * Opt-in: ALSO project `kind === "card"` rows into `result.cards` (see
+   * {@link HistoryLoadResult}). Off by default so text-only consumers get the
+   * byte-identical `{ messages }` shape. On, a block-preserving renderer gets
+   * the persisted cards to interleave by `seq`.
+   */
+  includeCards?: boolean;
+  /** Injection seam for tests; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Fetch a thread's transcript across all pages. Returns `{ gone: true }` on
+ * 403/404 (a stale local threadId the caller no longer owns / that no longer
+ * exists) so the hook can drop the persisted id; throws on any other non-OK
+ * status so `useAgentInvoke`'s best-effort caller can swallow it and leave
+ * the chat empty.
+ */
+export async function fetchThreadHistory({
+  baseUrl,
+  threadId,
+  requestInit,
+  includeCards = false,
+  fetchImpl = fetch,
+}: ThreadHistoryFetchOptions): Promise<HistoryLoadResult> {
+  const routeUrl = `${baseUrl}/threads/${encodeURIComponent(threadId)}/messages`;
+  const rows: ThreadHistoryRow[] = [];
+  let nextToken: string | null = null;
+
+  for (let page = 0; page < MAX_HISTORY_PAGES; page++) {
+    const url =
+      `${routeUrl}?limit=${HISTORY_PAGE_LIMIT}` +
+      (nextToken ? `&nextToken=${encodeURIComponent(nextToken)}` : "");
+    const res = await fetchImpl(url, requestInit);
+    if (res.status === 403 || res.status === 404) return { gone: true };
+    if (!res.ok) throw new Error(`history load failed: ${res.status}`);
+    const body: ThreadMessagesResponse = await res.json();
+    rows.push(...body.rows);
+    nextToken = body.nextToken;
+    if (!nextToken) break;
+  }
+
+  return {
+    messages: threadHistoryRowsToMessages(rows),
+    ...(includeCards ? { cards: threadHistoryRowsToCards(rows) } : {}),
+  };
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+export {
+  parseSseEvents,
+  extractAssistantText,
+  reduceAssistantText,
+  stringField,
+  type ParsedSseEvent,
+} from "./sse";
+export {
+  createWebAdapters,
+  localStorageThreadStore,
+  webGenerateId,
+  fetchStreamTransport,
+  AgentResponseError,
+  type CreateWebAdaptersOptions,
+} from "./web-adapters";
+export {
+  fetchThreadHistory,
+  threadHistoryRowsToMessages,
+  threadHistoryRowsToCards,
+  type ThreadHistoryRow,
+  type ThreadHistoryFetchOptions,
+} from "./history";
+export { ingestMessageFrame } from "./blocks";
+// Pure block-walk / resource-narrowing helpers for a block-preserving renderer
+// (shared by Studio's `AgentBlocks` and Portal-web's agent chat). React-free.
+export {
+  asResourcePayload,
+  asUiResource,
+  blockUiResource,
+  cardUiResource,
+  isJsonObject,
+  resourceHtml,
+  scanProviderRawForUiResource,
+  sortHistoryCards,
+  toolNameFor,
+  toolResultUiResource,
+  type McpUiResourcePayload,
+} from "./block-ui";
+// Re-export the AgJSON types the block-preserving transcript surfaces, so
+// consumers can name `reduceResult` / block types without a direct
+// `@silverprotocol/core` import.
+export type { AgEvent, AgReduceResult, AgMessage, AgBlock } from "@silverprotocol/core";
+export type {
+  AgentMessage,
+  HistoryCard,
+  ThreadIdStore,
+  GenerateId,
+  InvokeRequest,
+  InvokeTransport,
+  AgentInvokeAdapters,
+  AgentInvokeHistoryAdapter,
+  HistoryLoadResult,
+  UseAgentInvokeOptions,
+  UseAgentInvokeReturn,
+} from "./types";