use-agentenkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eadwin
+
+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,179 @@
+# use-agentenkit
+
+A React hook for an [`agentenkit`](../agentenkit) backend: durable
+threads, live streaming, human-in-the-loop approvals and nested runs.
+
+It owns the client state machine — hydrate from the durable snapshot, replay
+the active run, then tail the event stream — and leaves every endpoint, string
+and transport to you.
+
+```bash
+bun add use-agentenkit
+```
+
+**[Full documentation](https://eadwincode.github.io/agentic-kit/)** · [React guide](https://eadwincode.github.io/agentic-kit/react) ·
+[the HTTP contract it expects](https://eadwincode.github.io/agentic-kit/http-api)
+
+## Use it
+
+```tsx
+'use client';
+import { useAgentThread } from 'use-agentenkit';
+
+export function Chat() {
+  const { entries, run, stop, agentState, pendingInputs, respondToInput } =
+    useAgentThread();
+
+  return (
+    <>
+      {entries.map((e) => (
+        <p key={e.id}>{e.role}: {e.text}</p>
+      ))}
+      {pendingInputs.map((input) => (
+        <button key={input.toolCallId} onClick={() => respondToInput(input.toolCallId, true)}>
+          Approve {input.toolName}
+        </button>
+      ))}
+      <button onClick={() => (agentState === 'RUNNING' ? stop() : run('hello'))}>
+        {agentState === 'RUNNING' ? 'Stop' : 'Send'}
+      </button>
+    </>
+  );
+}
+```
+
+With no config it calls the default routes below. Nothing else is assumed.
+
+## Routes
+
+| Route | Method | Default | Carries |
+| --- | --- | --- | --- |
+| `run` | POST | `/api/agent/run` | `{ threadId?, prompt, model, editMessageId? }` |
+| `stop` | POST | `/api/agent/control` | `{ threadId }` |
+| `respond` | POST | `/api/agent/respond` | `{ threadId, toolCallId, approved, payload? }` |
+| `stream` | GET (SSE) | `/api/agent/stream` | `?threadId=&since=` |
+| `history` | GET | `/api/agent/history` | `?threadId=` |
+| `usage` | GET | `/api/agent/usage` | `?threadId=` |
+| `threads` | GET | `/api/threads` | — |
+| `deleteThread` | DELETE | `/api/threads` | `?threadId=` |
+
+Override any subset. A route is either a path the hook appends its own query
+to, or a function that builds the whole URL — the function form covers path
+parameters, a different query vocabulary, or another host:
+
+```ts
+useAgentThread({
+  baseUrl: 'https://api.example.com',
+  routes: {
+    run: '/v2/agent/start',
+    history: ({ threadId }) => `/v2/threads/${threadId}`,
+  },
+});
+```
+
+## Configure once
+
+`AgentRunProvider` sets the config for everything below it. A hook's own
+options still win, section by section, so a component can replace one route
+without restating the rest.
+
+```tsx
+'use client';
+import { AgentRunProvider } from 'use-agentenkit';
+
+export function Providers({ children }) {
+  return (
+    <AgentRunProvider config={{ routes: { run: '/v2/agent/start' } }}>
+      {children}
+    </AgentRunProvider>
+  );
+}
+```
+
+## Everything else you can change
+
+| Option | Default | What it is for |
+| --- | --- | --- |
+| `fetch` | global `fetch` | auth wrappers, retries, a test double |
+| `headers` | none | sent with every request; a function is called per request, so a rotating token stays fresh |
+| `openStream` | `browserEventStream` | how the event stream is opened — see below |
+| `defaultModel` | `'gpt-4o'` | used when `run()` names no model |
+| `persistence` | `browserPersistence()` | where the open thread id is remembered; `false` keeps it in memory only |
+| `labels` | English | every user-facing string the hook produces |
+| `format` | plain text | how tool calls, results and subagent notices render |
+| `onEvent` | none | see every event first; return `true` to handle it yourself |
+| `threadsRefreshMs` | `30000` | background refresh of the thread list; `false` disables it |
+| `loadThreadsOnMount` | `true` | off for a single-thread embed |
+
+### Auth on the stream
+
+`headers` does **not** reach the event stream. The browser's `EventSource`
+cannot send headers — that is a limitation of the API, not of this package. Use
+a cookie, or supply your own `openStream`:
+
+```ts
+useAgentThread({
+  openStream: (url, { onMessage, onError }) => {
+    const source = new MyAuthedEventSource(url, { token });
+    source.onmessage = (e) => onMessage(e.data);
+    source.onerror = onError;
+    return { close: () => source.close() };
+  },
+});
+```
+
+### Your own events
+
+`onEvent` runs before the built-in reducer and can claim an event:
+
+```ts
+useAgentThread({
+  onEvent: (event) => {
+    if (event.type === 'MY_APP_EVENT') {
+      handle(event.payload);
+      return true; // handled — skip the built-in reducer
+    }
+  },
+});
+```
+
+## Streaming thought
+
+Models that expose their reasoning stream it separately from the answer. The
+hook keeps the two apart: thinking arrives as entries with `kind: 'reasoning'`,
+in order, so a UI can show it live and fold it away once the answer starts.
+
+```tsx
+{entries.map((e) =>
+  e.kind === 'reasoning' ? <Thought key={e.id} text={e.text} /> : <Bubble key={e.id} {...e} />,
+)}
+```
+
+It reads the same on a reload as it did live: a persisted message's reasoning
+parts are lifted into their own entry rather than folded into the answer text.
+
+Whether you see anything depends on the model. Providers that do not expose
+reasoning simply never send it, and no reasoning entries appear — OpenAI's
+`gpt-4o` is one of those, and the o-series reports reasoning *token counts*
+without the text. Anthropic extended thinking and DeepSeek R1 do send it.
+
+## What the hook returns
+
+State: `threadId`, `entries`, `agentState`, `activity`, `historyLoading`,
+`pendingInputs`, `subagents`, `threads`, `threadsLoading`, `usage`.
+
+Actions: `run`, `stop`, `respondToInput`, `newThread`, `selectThread`,
+`deleteThread`, `loadThreads`, `loadUsage`.
+
+An entry is `{ id, kind, role, text, agentId }`, where `kind` is `'text'`,
+`'tool'` or `'reasoning'`.
+
+## Notes
+
+- The server is the only source of truth. A reload, or a second tab, rebuilds
+  from the durable snapshot and then resumes the stream at its cursor.
+- `run()` adds the user's turn locally before the request goes out, then
+  replaces it with the durable one when the server confirms it, so the id is
+  real and the message can be edited.
+- Config is read fresh on every request, but an open stream keeps the URL it
+  was opened with. Change routes at mount, not mid-run.

package/dist/config.d.ts

@@ -0,0 +1,150 @@
+import type { StreamEvent } from './types.js';
+/** Just the call signature. `typeof fetch` also carries runtime-specific
+ *  extras (Bun adds `preconnect`) that a plain wrapper cannot satisfy. */
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/** A route is either a path the hook appends its own query to, or a function
+ *  that builds the whole URL. The function form is the escape hatch: it covers
+ *  path parameters (`/threads/:id/history`), a different query vocabulary, or
+ *  an entirely different host — cases a fixed path cannot express. */
+export type Route<P = void> = P extends void ? string : string | ((params: P) => string);
+export interface AgentRoutes {
+    /** POST { threadId?, prompt, model, editMessageId? } → RunResult */
+    run: string;
+    /** POST { threadId } — stop the active run */
+    stop: string;
+    /** POST { threadId, toolCallId, approved, payload? } — answer an approval */
+    respond: string;
+    /** GET, server-sent events. Resumes from `since`. */
+    stream: Route<{
+        threadId: string;
+        since: number;
+    }>;
+    /** GET → ThreadSnapshot */
+    history: Route<{
+        threadId: string;
+    }>;
+    /** GET → ThreadUsage */
+    usage: Route<{
+        threadId: string;
+    }>;
+    /** GET → { threads: ThreadListItem[] } */
+    threads: string;
+    /** DELETE — remove a thread and everything under it */
+    deleteThread: Route<{
+        threadId: string;
+    }>;
+}
+export declare const defaultRoutes: AgentRoutes;
+/** Every user-facing string the hook produces, in one place so an app can
+ *  translate or reword them without forking the state machine. */
+export interface ActivityLabels {
+    idle: string;
+    loading: string;
+    thinking: string;
+    responding: string;
+    reviewingSources: string;
+    preparingToolCall: string;
+    callingTool: string;
+    toolCompleted: string;
+    waitingApproval: string;
+    approvalExpired: string;
+    approvalSent: string;
+    requestDenied: string;
+    subagentWorking: string;
+    subagentCompleted: string;
+    completed: string;
+    stopped: string;
+    failed: string;
+    runFailed: string;
+    loadFailed: string;
+}
+export declare const defaultLabels: ActivityLabels;
+/** How a message turns into display text. The defaults are plain and
+ *  ASCII-marked; override to render your own tool cards. */
+export interface EntryFormat {
+    truncate(text: string, max: number): string;
+    toolCall(toolName: string, args: unknown): string;
+    toolResult(toolName: string | undefined, result: unknown): string;
+    subagentStarted(name: string): string;
+}
+export declare const defaultFormat: EntryFormat;
+/** Where the open thread id is remembered between reloads. This is app policy,
+ *  not library policy — an app with its own router should supply its own, and
+ *  one that wants a clean slate every load can pass `false`. */
+export interface ThreadPersistence {
+    load(): string | undefined;
+    save(threadId: string): void;
+    clear(): void;
+}
+/** The default: a `threadId` query parameter so a conversation is linkable,
+ *  backed by localStorage so a bare visit reopens the last one. */
+export declare function browserPersistence(storageKey?: string): ThreadPersistence;
+export interface StreamHandlers {
+    /** One event frame, still encoded. */
+    onMessage: (data: string) => void;
+    onError: (error: unknown) => void;
+}
+export interface StreamSubscription {
+    close(): void;
+}
+/** Open the event stream. Handlers go in and something closeable comes back —
+ *  rather than an EventSource look-alike, so an implementation is free to use
+ *  fetch streaming, a WebSocket, or a test double without imitating the
+ *  browser's property API. */
+export type OpenStream = (url: string, handlers: StreamHandlers) => StreamSubscription;
+export declare const browserEventStream: OpenStream;
+export interface AgentRunConfig {
+    /** Override any subset; the rest keep their defaults. */
+    routes?: Partial<AgentRoutes>;
+    /** Prefix applied to string routes — for an API on another origin. Routes
+     *  given as functions build their own URL and are left alone. */
+    baseUrl?: string;
+    /** Swap the transport: auth wrappers, retries, a test double. */
+    fetch?: FetchLike;
+    /** Sent with every request the hook makes. A function is called per request,
+     *  so a token that rotates stays fresh. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** Open the event stream. The default uses the browser's EventSource, which
+     *  CANNOT send headers — so `headers` does not reach the stream. An API
+     *  behind a bearer token needs its own implementation here (or a cookie). */
+    openStream?: OpenStream;
+    /** Used by `run()` when the caller names no model. */
+    defaultModel?: string;
+    /** `false` keeps the thread id in memory only. */
+    persistence?: ThreadPersistence | false;
+    labels?: Partial<ActivityLabels>;
+    format?: Partial<EntryFormat>;
+    /** Every event, before the hook interprets it. Return `true` to say the
+     *  event is handled and stop the built-in reducer — that is how an app adds
+     *  its own event types, or overrides one. */
+    onEvent?: (event: StreamEvent) => boolean | void;
+    /** Background refresh for the thread list, in ms. `false` disables it —
+     *  other tabs and the worker can change thread state without this tab
+     *  seeing an event, which is the only reason it exists. */
+    threadsRefreshMs?: number | false;
+    /** Load the thread list on mount. Off for a single-thread embed. */
+    loadThreadsOnMount?: boolean;
+}
+export interface ResolvedConfig {
+    routes: AgentRoutes;
+    baseUrl: string;
+    fetch: FetchLike;
+    headers: () => HeadersInit | Promise<HeadersInit>;
+    openStream: OpenStream;
+    defaultModel: string;
+    persistence: ThreadPersistence | null;
+    labels: ActivityLabels;
+    format: EntryFormat;
+    onEvent: ((event: StreamEvent) => boolean | void) | undefined;
+    threadsRefreshMs: number | false;
+    loadThreadsOnMount: boolean;
+}
+export declare function resolveConfig(config?: AgentRunConfig): ResolvedConfig;
+/** Append query parameters without disturbing a relative path or a query the
+ *  route already carries. `new URL` cannot be used here — it would force every
+ *  route to be absolute. */
+export declare function withQuery(path: string, params: Record<string, string | number | undefined>): string;
+/** Resolve one route to a URL. A string gets the base prefix and the hook's
+ *  standard query; a function is trusted to return a complete URL. */
+export declare function routeUrl<P extends Record<string, string | number | undefined>>(route: string | ((params: P) => string), params: P, baseUrl: string): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -0,0 +1,138 @@
+export const defaultRoutes = {
+    run: '/api/agent/run',
+    stop: '/api/agent/control',
+    respond: '/api/agent/respond',
+    stream: '/api/agent/stream',
+    history: '/api/agent/history',
+    usage: '/api/agent/usage',
+    threads: '/api/threads',
+    deleteThread: '/api/threads',
+};
+export const defaultLabels = {
+    idle: 'Idle',
+    loading: 'Loading conversation',
+    thinking: 'Thinking',
+    responding: 'Responding',
+    reviewingSources: 'Reviewing sources',
+    preparingToolCall: 'Preparing tool call',
+    callingTool: 'Calling tool',
+    toolCompleted: 'Tool completed',
+    waitingApproval: 'Waiting for approval',
+    approvalExpired: 'Approval expired',
+    approvalSent: 'Approval sent',
+    requestDenied: 'Request denied',
+    subagentWorking: 'Subagent working',
+    subagentCompleted: 'Subagent completed',
+    completed: 'Completed',
+    stopped: 'Stopped',
+    failed: 'Failed',
+    runFailed: 'Could not start run',
+    loadFailed: 'Could not load conversation',
+};
+const json = (value) => {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+};
+export const defaultFormat = {
+    truncate: (text, max) => (text.length > max ? `${text.slice(0, max)}…` : text),
+    toolCall: (toolName, args) => `⚙ ${toolName}(${defaultFormat.truncate(json(args ?? {}), 120)})`,
+    toolResult: (toolName, result) => `↳ ${toolName ? `${toolName}: ` : ''}${defaultFormat.truncate(json(result), 220)}`,
+    subagentStarted: (name) => `▸ subagent "${name}" started`,
+};
+/** The default: a `threadId` query parameter so a conversation is linkable,
+ *  backed by localStorage so a bare visit reopens the last one. */
+export function browserPersistence(storageKey = 'use-agentenkit:last-thread') {
+    const canUseDom = () => typeof window !== 'undefined';
+    const read = () => {
+        try {
+            return window.localStorage.getItem(storageKey);
+        }
+        catch {
+            return null; // private mode, or storage disabled
+        }
+    };
+    return {
+        load: () => {
+            if (!canUseDom())
+                return undefined;
+            const fromUrl = new URLSearchParams(window.location.search).get('threadId');
+            return fromUrl || read() || undefined;
+        },
+        save: (threadId) => {
+            if (!canUseDom())
+                return;
+            try {
+                window.localStorage.setItem(storageKey, threadId);
+            }
+            catch {
+                // storage is a convenience; never break the conversation over it
+            }
+            const url = new URL(window.location.href);
+            url.searchParams.set('threadId', threadId);
+            window.history.replaceState({}, '', url);
+        },
+        clear: () => {
+            if (!canUseDom())
+                return;
+            try {
+                window.localStorage.removeItem(storageKey);
+            }
+            catch {
+                // as above
+            }
+            const url = new URL(window.location.href);
+            url.searchParams.delete('threadId');
+            window.history.replaceState({}, '', url);
+        },
+    };
+}
+export const browserEventStream = (url, { onMessage, onError }) => {
+    const source = new EventSource(url);
+    source.onmessage = (event) => onMessage(event.data);
+    source.onerror = (event) => onError(event);
+    return { close: () => source.close() };
+};
+export function resolveConfig(config = {}) {
+    // Hoisted: TypeScript cannot narrow `config.headers` inside the closure.
+    const headers = config.headers;
+    return {
+        routes: { ...defaultRoutes, ...config.routes },
+        baseUrl: config.baseUrl ?? '',
+        // Bound to globalThis: an unbound reference throws "Illegal invocation"
+        // in the browser.
+        fetch: config.fetch ?? ((...args) => globalThis.fetch(...args)),
+        headers: typeof headers === 'function' ? headers : () => headers ?? {},
+        openStream: config.openStream ?? browserEventStream,
+        defaultModel: config.defaultModel ?? 'gpt-4o',
+        persistence: config.persistence === false ? null : (config.persistence ?? browserPersistence()),
+        labels: { ...defaultLabels, ...config.labels },
+        format: { ...defaultFormat, ...config.format },
+        onEvent: config.onEvent,
+        threadsRefreshMs: config.threadsRefreshMs ?? 30_000,
+        loadThreadsOnMount: config.loadThreadsOnMount ?? true,
+    };
+}
+/** Append query parameters without disturbing a relative path or a query the
+ *  route already carries. `new URL` cannot be used here — it would force every
+ *  route to be absolute. */
+export function withQuery(path, params) {
+    const search = Object.entries(params)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+        .join('&');
+    if (!search)
+        return path;
+    return `${path}${path.includes('?') ? '&' : '?'}${search}`;
+}
+/** Resolve one route to a URL. A string gets the base prefix and the hook's
+ *  standard query; a function is trusted to return a complete URL. */
+export function routeUrl(route, params, baseUrl) {
+    if (typeof route === 'function')
+        return route(params);
+    return withQuery(baseUrl + route, params);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,10 @@
+import type { AgentRunConfig } from './config.js';
+/** Holds the RAW config, not a resolved one: a hook's own options are merged
+ *  over it before defaults are applied, so a component can override one route
+ *  without restating the rest. */
+export declare const AgentRunContext: import("react").Context<AgentRunConfig | null>;
+/** The config from the nearest provider, if there is one. */
+export declare function useAgentRunConfig(): AgentRunConfig | null;
+/** Later wins, per section — so `{ routes: { run } }` replaces only `run`. */
+export declare function mergeConfig(base: AgentRunConfig | null, over: AgentRunConfig): AgentRunConfig;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;kCAEkC;AAClC,eAAO,MAAM,eAAe,gDAA6C,CAAC;AAE1E,6DAA6D;AAC7D,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,IAAI,CAEzD;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CACzB,IAAI,EAAE,cAAc,GAAG,IAAI,EAC3B,IAAI,EAAE,cAAc,GACnB,cAAc,CAShB"}

package/dist/context.js

@@ -0,0 +1,23 @@
+'use client';
+import { createContext, useContext } from 'react';
+/** Holds the RAW config, not a resolved one: a hook's own options are merged
+ *  over it before defaults are applied, so a component can override one route
+ *  without restating the rest. */
+export const AgentRunContext = createContext(null);
+/** The config from the nearest provider, if there is one. */
+export function useAgentRunConfig() {
+    return useContext(AgentRunContext);
+}
+/** Later wins, per section — so `{ routes: { run } }` replaces only `run`. */
+export function mergeConfig(base, over) {
+    if (!base)
+        return over;
+    return {
+        ...base,
+        ...over,
+        routes: { ...base.routes, ...over.routes },
+        labels: { ...base.labels, ...over.labels },
+        format: { ...base.format, ...over.format },
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGlD;;kCAEkC;AAClC,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAwB,IAAI,CAAC,CAAC;AAE1E,6DAA6D;AAC7D,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,CAAC,eAAe,CAAC,CAAC;AACrC,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,WAAW,CACzB,IAA2B,EAC3B,IAAoB;IAEpB,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO;QACL,GAAG,IAAI;QACP,GAAG,IAAI;QACP,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE;QAC1C,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE;QAC1C,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE;KAC3C,CAAC;AACJ,CAAC"}

package/dist/format.d.ts

@@ -0,0 +1,19 @@
+import type { ActivityLabels, EntryFormat } from './config.js';
+import type { AgentActivity, AgentState, ChatEntry, SnapshotMessage } from './types.js';
+/** Flatten AI-SDK message content into something a bubble can render. */
+export declare function contentToText(content: unknown, format: EntryFormat): string;
+/** One durable message → one entry, or null when it carries nothing to show.
+ *  A message that is only tool activity is marked `kind: 'tool'` so a UI can
+ *  style it apart from conversation. */
+export declare function messageToEntry(message: SnapshotMessage, format: EntryFormat): ChatEntry | null;
+/** The model's thinking, as persisted on a message. Providers that do not
+ *  expose it simply have no such parts, and this returns ''. */
+export declare function reasoningText(content: unknown): string;
+/** One durable message → the entries it renders as: its thinking first, then
+ *  the answer. Split because they stream separately and a UI folds thinking
+ *  away, so keeping them in one bubble would make a reload look different from
+ *  the live run. */
+export declare function messageToEntries(message: SnapshotMessage, format: EntryFormat): ChatEntry[];
+/** The activity a thread state implies when nothing more specific is happening. */
+export declare function stateActivity(state: AgentState, labels: ActivityLabels): AgentActivity;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAUxF,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAiB3E;AAED;;wCAEwC;AACxC,wBAAgB,cAAc,CAC5B,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,WAAW,GAClB,SAAS,GAAG,IAAI,CAoBlB;AAED;gEACgE;AAChE,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAMtD;AAED;;;oBAGoB;AACpB,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,CAe3F;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,aAAa,CAetF"}