@cubos/agent-sdk-react 0.0.1136563

package/README.md

@@ -0,0 +1,304 @@
+# @cubos/agent-sdk-react
+
+Headless React hooks for the Cubos Agent conversation API.
+
+**No DOM.** The package renders nothing and imports no `react-dom`, so the same
+hooks drive a web app, React Native, or anything else React runs on. A test in
+this package fails the build if a browser global or a `<div>` sneaks in.
+
+```sh
+npm install @cubos/agent-sdk @cubos/agent-sdk-react
+```
+
+## The whole thing
+
+```tsx
+import { AgentProvider, useConversation } from "@cubos/agent-sdk-react";
+
+function App() {
+  return (
+    <AgentProvider
+      baseUrl="https://agent.acme.com"
+      getToken={async () => (await fetch("/api/agent-token").then((r) => r.json())).token}
+    >
+      <Chat />
+    </AgentProvider>
+  );
+}
+
+function Chat() {
+  const [id, setId] = useState<string | null>(null);
+  const { messages, send, activity } = useConversation(id, {
+    agentSlug: "support",
+    onCreated: (conversation) => setId(conversation.id),
+  });
+
+  return (
+    <>
+      {messages.map((m) => (
+        <div key={m.id} data-role={m.role}>
+          {m.content}
+        </div>
+      ))}
+      {(activity.isProcessing || activity.hasPendingTurn) && <Typing />}
+      <Composer onSubmit={send} />
+    </>
+  );
+}
+```
+
+`getToken` must return a **short-lived end-user token**, minted on your server.
+An api_key is tenant-wide and must never reach a client. The SDK asks again with
+`forceRefresh` after a 401, so expiry is handled for you.
+
+## Two hooks, and you hold the id between them
+
+There is no hook that owns "which conversation is open". That is your app's
+state — component state in the example above, a route param in a real one — and
+keeping it out of the package is what lets `/c/:id` work without syncing
+anything.
+
+```tsx
+const [selectedId, setSelectedId] = useState<string | null>(null);
+
+const list = useConversationList();
+const conversation = useConversation(selectedId, {
+  agentSlug: "support",
+  onCreated: (created) => setSelectedId(created.id),
+});
+```
+
+The one behaviour worth knowing: **a conversation is created on the first
+message, not when the user clicks "new chat".** Otherwise every abandoned blank
+slate leaves an empty row in the list. `send` covers both cases, so your UI never
+special-cases "no conversation yet" — it just passes `null` until `onCreated`
+fires. The messages already on screen survive that hand-off.
+
+Both hooks paginate, in opposite directions, so the names stay apart:
+`list.hasMore` / `list.loadMore` walk the **conversation list**;
+`conversation.hasOlder` / `conversation.loadOlder` walk the **open
+conversation's history**.
+
+## Infinite history, live present
+
+`useConversation` opens with one page of history and points the live stream at
+the end of that page, so a year-old conversation costs one page on open instead
+of the whole log — and keeps costing one page on every reconnect.
+
+```tsx
+const { messages, hasOlder, isLoadingOlder, loadOlder } = useConversation(id);
+
+// Whatever your list uses to notice the top: a scroll handler, an
+// IntersectionObserver on a sentinel, FlatList's onEndReached inverted.
+const onReachedTop = () => {
+  if (hasOlder && !isLoadingOlder) void loadOlder();
+};
+```
+
+Two details that are handled for you and one that is not:
+
+- **No gap at the junction.** The stream resumes from the page's cursor, and the
+  server replays everything past it before going live, so a message sent while
+  the page was in flight arrives rather than vanishing.
+- **Order is stable.** Pages, live frames and your own optimistic message are
+  merged by id and sorted by sequence, so a page landing mid-turn can't shuffle
+  the transcript.
+- **Scroll anchoring is yours.** Prepending grows the list upward while the
+  scroll offset stays put, which reads as a jump. Record `scrollHeight` before
+  calling `loadOlder` and add the difference back in a layout effect —
+  `packages/demo/src/chat/message-list.tsx` does exactly that.
+
+Reopening a conversation the user has already visited costs no request at all:
+the base SDK caches loaded conversations (in memory by default) and these hooks
+drive it for you — reading on open, recording as messages arrive, and resuming
+the stream from the cached cursor so nothing is replayed. Configure or replace it
+on the client (`cache`, `cacheMessageLimit`); see the `@cubos/agent-sdk` README.
+
+`loadOlder` resolves to how many messages it added. A page counts **events**, not
+messages, so a page full of tool calls can add none while `hasOlder` stays true —
+keep going rather than treating 0 as the end.
+
+## Your components in the agent's replies
+
+Hand the hook a map of **renderers** plus the **component libraries** this screen
+can draw, and the agent may use those components in a reply:
+
+```tsx
+const { messages, renderMessage } = useConversation(id, {
+  components: {
+    Choices: (props) => <Choices {...props} onPick={send} />,
+  },
+  componentLibraries: ["support-widgets"],
+  renderMarkdown: (text) => <Markdown>{text}</Markdown>,
+});
+
+// In your bubble. Null means the message has no blocks — every user message —
+// so that is where your own rendering of `content` goes.
+{renderMessage(message) ?? message.content}
+```
+
+The two halves have different owners, and that is deliberate. What the agent is
+*told* about a component — its summary, what each prop means, the JSON Schema,
+the example — lives in a component library that an operator authors over the
+admin API, because those words go into the model's context verbatim. What
+*draws* it is yours. You choose which libraries apply to the screen you have
+open; the hook enables them on the conversation, at creation for a chat that
+starts here and with a `PUT` when the list changes.
+
+The server refuses any component the enabled libraries don't resolve to, and
+validates props against the library's schema before the message is written — so
+a renderer never sees a shape it didn't ask for. A tag with no renderer draws
+nothing, and the hook logs a warning naming it, since that is a silent gap in a
+reply. The reverse is never warned about: **keep renderers for components no
+library offers any more**, because that is what draws the older messages in the
+transcript.
+
+`renderMarkdown` draws the prose around the components. Without it the markdown
+renders as plain text: this package ships no parser, and your app already has
+one.
+
+## Client tools: functions the agent calls in your app
+
+```tsx
+useConversation(id, {
+  clientTools: {
+    get_browser_context: {
+      description: "Timezone, locale and local time, as this browser reports them.",
+      inputSchema: { type: "object", properties: {} },
+      readOnlyHint: true,
+      handler: () => ({ timezone: Intl.DateTimeFormat().resolvedOptions().timeZone }),
+    },
+  },
+  onClientToolError: (err) => console.error(err),
+});
+```
+
+The agent calls it, **its turn suspends**, your handler runs here, and the turn
+resumes with what you returned. A handler that throws answers with the failure
+rather than leaving the agent to wait out its deadline.
+
+Two things this does for you that are easy to get wrong by hand:
+
+- **One stream, not two.** The runner rides the subscription the hook already
+  holds — a `client_tool_call` frame nudges it, and so does every reconnect, so a
+  call issued while the connection was down is picked up rather than left to
+  expire. Doing this outside the hook means a second SSE connection per
+  conversation, against a server that caps how many a user may hold.
+- **Declared before the first turn.** On the blank slate the tools are declared
+  in the same breath as creating the conversation, so the agent can already reach
+  for them in its first reply.
+
+The lease, the renewal while a slow handler runs, and the retry on the result
+POST are the base SDK's `serveClientTools`; the hook only decides when to start
+and stop it.
+
+## The surface
+
+| Hook | What it gives you |
+|---|---|
+| `useConversationList(opts)` | the live list, plus `archive`, `loadMore` |
+| `useConversation(id \| null, opts)` | messages, todos, activity, `send`, `sendAudio`, `sendImages`, `steer`, `loadOlder`, `renderMessage` |
+| `useIdentity()` | who the token acts as, and which agents it may use |
+| `useAgentClient()` | the underlying `AgentClient`, for anything not wrapped |
+
+`useConversation(null)` is valid and opens no connection — that is the blank
+slate before a conversation is picked.
+
+Both the list and the conversation are **live**: the hooks load a page of
+history, follow the SSE stream from where that page ends, and resume from the
+exact point after a drop. Nothing to poll, nothing to invalidate.
+
+## Messages
+
+```ts
+interface Message {
+  id: string;
+  role: "user" | "agent";
+  content: string;
+  attachments: Array<{
+    id: string;
+    kind: "image" | "audio";
+    mimeType: string;
+    bytes: number;
+    label: string | null;
+  }>;
+  seq: number;
+  at: string;
+}
+```
+
+Media hangs off `attachments`, and `content` is whatever text came with it — a
+caption for images, the transcription for a voice note. **Both can be empty**, so
+render `attachments` even when `content` is blank.
+
+A voice message arrives as one `Message` carrying its clip *and* the
+transcription, which is empty until the agent's STT model finishes — your cue to
+render a player with a "transcribing" state.
+
+Bytes come from `useAgentClient().fetchAttachment(conversationId, message.id,
+attachment.id)`, as a `Blob` rather than a URL: the token travels in a header, so
+an `<img src>` pointed at the route would arrive unauthenticated. Wrap it for the
+platform and release it when the view goes away.
+
+Sending images is the mirror image of that:
+
+```ts
+// Up to 10 as ONE message, so the agent reasons over the set rather than
+// spending a turn per picture. `caption` becomes the message's text.
+await sendImages(
+  [{ image: receipt, label: "receipt" }, { image: statement, label: "statement" }],
+  "which charge is duplicated?",
+);
+```
+
+A `label` names an image for the model, which lets it answer about "the receipt"
+instead of "the second image".
+
+`send` appends optimistically and reconciles with the server's echo, rolling the
+optimistic copy back if the send fails. A message whose `id` starts with
+`optimistic:` has not been confirmed yet.
+
+## Rendering
+
+This package deliberately ships no components and no CSS — that is what keeps it
+running wherever React runs. The pieces that are genuinely generic, and do need
+the DOM, live next door in
+[`@cubos/agent-sdk-react-dom`](../sdk-react-dom): `AgentMarkdown` renders an
+agent's reply (GFM, fenced code, TeX) and styles itself.
+
+```tsx
+import { AgentMarkdown } from "@cubos/agent-sdk-react-dom";
+
+useConversation(id, { renderMarkdown: (text) => <AgentMarkdown>{text}</AgentMarkdown> });
+```
+
+Chat UI proper — bubbles, composer, conversation list — is where products differ
+most, and a set of styled components for it is either too rigid to use or too
+configurable to maintain.
+
+`renderMessage` is the one exception, and it renders nothing of its own: it puts
+*your* components where the agent placed them and hands the prose to *your*
+markdown renderer. `renderBlocks` is the same function without the hook, for a
+message you already hold.
+
+For a complete worked example — message bubbles, a composer with image
+attachments and voice recording, agent-rendered components, client tools, the
+conversation list, a responsive drawer — see `packages/demo` in the repository.
+It is written against these hooks and meant to be copied and changed, not
+installed.
+
+## React Native
+
+The hooks are clean. Two caveats live below them, in the base SDK:
+
+- **Streaming.** Live updates use SSE over `fetch` response streams. React
+  Native's default networking does not stream response bodies; you need a fetch
+  polyfill that does (`react-native-fetch-api` with
+  `react-native-polyfill-globals`), handed to the provider as `fetch`.
+- **Media.** `sendAudio` and `sendImages` take `Blob`s, and `fetchAttachment`
+  hands one back. Recording, picking an image and turning a blob into something
+  displayable are all platform-specific — use what the platform offers.
+
+Components and client tools need nothing extra: `renderMessage` builds elements
+with `createElement`, and a handler is a function. Your `render` is a Native
+component like any other.

package/dist/blocks.d.ts

@@ -0,0 +1,47 @@
+import type { Block, Message } from "@cubos/agent-sdk";
+import { type ComponentType, type ReactNode } from "react";
+/**
+ * What draws one component, keyed by tag name — PascalCase, as the agent writes
+ * it.
+ *
+ * Renderers only. What the *agent* is told about a component (its summary, the
+ * prop schema, the example) lives in a component library the operator authors,
+ * because those words go into the model's context verbatim and a browser must
+ * not be the one writing them. Your app supplies the drawing half and the list
+ * of library slugs it can draw; `useConversation` warns when the two disagree.
+ *
+ * Keep renderers here for components no enabled library offers any more — that
+ * is what draws the components of older messages in the transcript.
+ */
+export type ComponentMap = Record<string, ComponentType<any>>;
+export interface RenderBlocksOptions {
+    components?: ComponentMap;
+    /** Draws the prose between components. Without it the markdown is rendered as
+     * plain text — correct, just not formatted; the SDK ships no markdown parser
+     * and a chat app already has one. */
+    renderMarkdown?: (text: string) => ReactNode;
+    /**
+     * Wraps each rendered block, given the block it came from.
+     *
+     * The reason it takes the block and not just the node: laying blocks out
+     * needs to know which are prose and which are components — two cards side by
+     * side and the paragraph above them full width — and by the time a block is a
+     * `ReactNode` that is gone. The SDK will not decide the layout (it renders no
+     * DOM at all), so it hands back what the app needs to decide it.
+     */
+    wrapBlock?: (node: ReactNode, block: Block) => ReactNode;
+}
+/**
+ * The message split into nodes: prose through `renderMarkdown`, each component
+ * block through the component registered under its tag.
+ *
+ * Null when the message carries no blocks — a user message, or an older server.
+ * That distinction is real, so it is left to the caller rather than papered over
+ * with `content`: a user's own text usually shouldn't go through a markdown
+ * renderer at all.
+ *
+ * A tag with no component renders nothing. It means the set changed after the
+ * message was written, and showing raw `<Tag …/>` text would be worse than a
+ * gap.
+ */
+export declare function renderBlocks(message: Message, options?: RenderBlocksOptions): ReactNode[] | null;

package/dist/context.d.ts

@@ -0,0 +1,23 @@
+import type { AgentClient, ClientOptions } from "@cubos/agent-sdk";
+import { type ReactNode } from "react";
+/** An intersection, not `extends`: `ClientOptions` is a union (`getToken` or
+ * `token`), and an interface cannot extend one. */
+export type AgentProviderProps = ClientOptions & {
+    children: ReactNode;
+};
+/**
+ * Holds one `AgentClient` for the tree below it.
+ *
+ * `baseUrl`, `tenant`, `fetch` and `timeoutMs` are identity keys: change one and
+ * a new client is built, so every subscription below reconnects. That is right
+ * when you switch backend or user, and a waste when it happens because the props
+ * object was rebuilt for nothing — keep `fetch` stable if you pass it.
+ *
+ * The credential is exempt: both `getToken` and `token` reach the client through
+ * a ref, so a fresh closure every render (the normal case for an inline arrow)
+ * neither rebuilds the client nor pins a stale token.
+ */
+export declare function AgentProvider({ children, ...options }: AgentProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<AgentClient | null>>;
+/** The client from the nearest `AgentProvider`. Throws outside one, because the
+ * alternative is a component that silently never loads. */
+export declare function useAgentClient(): AgentClient;

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export type { Activity, Attachment, AttachmentKind, Block, ClientTool, ClientToolCall, ClientToolContext, Conversation, ConversationEvent, EnabledComponents, Identity, Message, MessagePage, MessageRole, Todo, TodoStatus, } from "@cubos/agent-sdk";
+export type { ComponentMap, RenderBlocksOptions } from "./blocks.js";
+export { renderBlocks } from "./blocks.js";
+export type { AgentProviderProps } from "./context.js";
+export { AgentProvider, useAgentClient } from "./context.js";
+export type { UseConversationOptions, UseConversationResult } from "./use-conversation.js";
+export { useConversation } from "./use-conversation.js";
+export type { UseConversationEventsOptions, UseConversationEventsResult, } from "./use-conversation-events.js";
+export { useConversationEvents } from "./use-conversation-events.js";
+export type { UseConversationListOptions, UseConversationListResult, } from "./use-conversation-list.js";
+export { useConversationList } from "./use-conversation-list.js";
+export type { UseIdentityResult } from "./use-identity.js";
+export { useIdentity } from "./use-identity.js";