@guuey/agent-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loqu, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @guuey/agent-client
+
+The client SDK for a [guuey](https://guuey.com) agent's streaming contract:
+
+- **`POST /agent/invoke`** — a Server-Sent-Events stream (`session` / `message`
+  / `done` / `error` frames) folded into a flat transcript.
+- **`GET /threads/:id/messages`** — the paginated history read plane, so a
+  reload repaints the conversation before any new streaming starts.
+
+The hook is platform-agnostic: thread-id storage, client-message-id
+generation, and the network transport (which also carries identity) are
+injected as adapters, so the same core runs on web (Next.js) and React Native.
+
+```bash
+npm install @guuey/agent-client
+```
+
+## Two entry points
+
+| Import                      | Contents                                                                           | React? |
+| --------------------------- | ---------------------------------------------------------------------------------- | ------ |
+| `@guuey/agent-client`       | SSE helpers, the thread-history reader, `createWebAdapters`, and all public types. | No     |
+| `@guuey/agent-client/react` | The `useAgentInvoke` hook (+ `applyHistoryResult`).                                | Yes    |
+
+The root subpath is React-free — importing it never pulls React in. React is a
+**required peer** (`react >=18`) because the `./react` subpath needs it; if you
+only consume the root subpath, that peer is inert at runtime.
+
+## React example
+
+```tsx
+import { useAgentInvoke } from "@guuey/agent-client/react";
+import { createWebAdapters } from "@guuey/agent-client";
+
+export function Chat({ endpointUrl, appId }: { endpointUrl: string; appId: string }) {
+  const adapters = createWebAdapters({ getAccessToken: async () => myToken });
+  const { messages, send, isStreaming } = useAgentInvoke({ endpointUrl, appId, adapters });
+
+  return (
+    <>
+      {messages.map((m, i) => (
+        <p key={i} data-role={m.role}>
+          {m.text}
+        </p>
+      ))}
+      <button disabled={isStreaming} onClick={() => send("hello")}>
+        Send
+      </button>
+    </>
+  );
+}
+```
+
+On React Native, supply your own adapters (AsyncStorage + an `expo/fetch`
+transport) in place of `createWebAdapters` — the hook's contract is identical.
+
+## React Native / Metro
+
+Both entry points declare a `react-native` export condition that points at the
+**TypeScript source** (shipped in the npm tarball alongside `dist/` for exactly
+this reason — the standard RN package pattern). Metro resolves that condition
+by default and transpiles the source with your app's Babel config; Node and
+web bundlers ignore it and use the compiled ESM in `dist/`. No
+`transpilePackages`-style configuration is needed on either side.

package/dist/block-ui.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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 declare function isJsonObject(v: JsonValue | undefined): v is {
+    [key: string]: JsonValue;
+};
+/**
+ * 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 declare function asResourcePayload(v: JsonValue | undefined): McpUiResourcePayload | undefined;
+/**
+ * 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 declare function asUiResource(uiData: JsonValue | undefined): McpUiResourcePayload | undefined;
+/**
+ * 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 declare function scanProviderRawForUiResource(raw: JsonValue | undefined): McpUiResourcePayload | 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 declare function blockUiResource(block: JsonValue): McpUiResourcePayload | 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 declare function toolResultUiResource(block: Extract<AgBlock, {
+    type: "tool-result";
+}>): McpUiResourcePayload | 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 declare function cardUiResource(cardSnapshot: JsonValue): McpUiResourcePayload | undefined;
+/**
+ * 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 declare function resourceHtml(resource: McpUiResourcePayload): string | 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 declare function toolNameFor(message: AgMessage, toolCallId: string): string;
+/**
+ * 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 declare function sortHistoryCards(cards: readonly HistoryCard[]): HistoryCard[];
+//# sourceMappingURL=block-ui.d.ts.map

package/dist/block-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-ui.d.ts","sourceRoot":"","sources":["../src/block-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,CAAC,IAAI;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAExF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAU5F;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAK5F;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,SAAS,GAAG,SAAS,GACzB,oBAAoB,GAAG,SAAS,CAMlC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAclF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,GAC/C,oBAAoB,GAAG,SAAS,CAUlC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAUxF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAU/E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE,CAE7E"}

package/dist/block-ui.js

@@ -0,0 +1,165 @@
+/** Narrow an opaque `JsonValue` to a plain (non-array) JSON object. */
+export function isJsonObject(v) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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, toolCallId) {
+    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) {
+    return [...cards].sort((a, b) => a.seq - b.seq);
+}

package/dist/blocks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { type AgEvent } from "@silverprotocol/core";
+/** Ingest one `message` SSE payload (object OR array) into validated AgEvents. */
+export declare function ingestMessageFrame(raw: unknown): AgEvent[];
+//# sourceMappingURL=blocks.d.ts.map

package/dist/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAA6B,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/E,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,EAAE,CAK1D"}

package/dist/blocks.js

@@ -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 } from "@silverprotocol/core";
+/** Ingest one `message` SSE payload (object OR array) into validated AgEvents. */
+export function ingestMessageFrame(raw) {
+    const parsed = JsonValue.safeParse(raw);
+    if (!parsed.success)
+        return [];
+    const value = parsed.data;
+    return ingestAgEvents(Array.isArray(value) ? value : [value]);
+}

package/dist/history.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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;
+}
+/** Project raw rows to chat turns: text rows only, author → role. */
+export declare function threadHistoryRowsToMessages(rows: ThreadHistoryRow[]): AgentMessage[];
+/**
+ * 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 declare function threadHistoryRowsToCards(rows: ThreadHistoryRow[]): HistoryCard[];
+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 declare function fetchThreadHistory({ baseUrl, threadId, requestInit, includeCards, fetchImpl, }: ThreadHistoryFetchOptions): Promise<HistoryLoadResult>;
+//# sourceMappingURL=history.d.ts.map

package/dist/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5E,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CACjC;AAoBD,qEAAqE;AACrE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,YAAY,EAAE,CAOpF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE,CAOhF;AAED,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,OAAO,EACP,QAAQ,EACR,WAAW,EACX,YAAoB,EACpB,SAAiB,GAClB,EAAE,yBAAyB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsBxD"}

package/dist/history.js

@@ -0,0 +1,66 @@
+/** 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) {
+    const messages = [];
+    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) {
+    const cards = [];
+    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;
+}
+/**
+ * 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, }) {
+    const routeUrl = `${baseUrl}/threads/${encodeURIComponent(threadId)}/messages`;
+    const rows = [];
+    let nextToken = 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 = await res.json();
+        rows.push(...body.rows);
+        nextToken = body.nextToken;
+        if (!nextToken)
+            break;
+    }
+    return {
+        messages: threadHistoryRowsToMessages(rows),
+        ...(includeCards ? { cards: threadHistoryRowsToCards(rows) } : {}),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+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";
+export { asResourcePayload, asUiResource, blockUiResource, cardUiResource, isJsonObject, resourceHtml, scanProviderRawForUiResource, sortHistoryCards, toolNameFor, toolResultUiResource, type McpUiResourcePayload, } from "./block-ui";
+export type { AgEvent, AgReduceResult, AgMessage, AgBlock } from "@silverprotocol/core";
+export type { AgentMessage, HistoryCard, ThreadIdStore, GenerateId, InvokeRequest, InvokeTransport, AgentInvokeAdapters, AgentInvokeHistoryAdapter, HistoryLoadResult, UseAgentInvokeOptions, UseAgentInvokeReturn, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,KAAK,cAAc,GACpB,MAAM,OAAO,CAAC;AACf,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,wBAAwB,GAC9B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,GAC/B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAG9C,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,4BAA4B,EAC5B,gBAAgB,EAChB,WAAW,EACX,oBAAoB,EACpB,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAC;AAIpB,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACxF,YAAY,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { parseSseEvents, extractAssistantText, reduceAssistantText, stringField, } from "./sse";
+export { createWebAdapters, localStorageThreadStore, webGenerateId, fetchStreamTransport, AgentResponseError, } from "./web-adapters";
+export { fetchThreadHistory, threadHistoryRowsToMessages, threadHistoryRowsToCards, } 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, } from "./block-ui";

package/dist/react.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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";
+export type { AgEvent, AgReduceResult } from "@silverprotocol/core";
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI/F,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/react.js

@@ -0,0 +1,9 @@
+/**
+ * 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 } from "./useAgentInvoke";