@rudderjs/ai 1.17.3 → 1.18.0

package/boost/skills/ai-tools/SKILL.md

@@ -1,260 +0,0 @@
----
-name: ai-tools
-description: Defining server and client tools with Zod schemas, approval gates, streaming yields, and modelOutput for Rudder AI agents
-license: MIT
-appliesTo:
-  - '@rudderjs/ai'
-trigger: writing a `toolDefinition()`, defining server or client tools, adding streaming yields, or wiring approval gates
-skip: configuring an `Agent` class itself — load `ai-agents` instead
-metadata:
-  author: rudderjs
----
-
-# AI Tools
-
-## When to use this skill
-
-Load this skill when you need to define tools for AI agents -- server-side executors, client-side browser tools, streaming generator tools, approval gates, or tools with custom model output formatting.
-
-## Key concepts
-
-- **toolDefinition()**: Builder function that creates a typed tool from a Zod input schema. Call `.server()` to attach a handler, or leave as-is for a client tool.
-- **Server tools**: Have an `execute` function that runs on the server. Can be a regular async function or an `async function*` generator.
-- **Client tools**: No `execute` -- the agent loop pauses and returns pending tool calls for browser-side execution.
-- **Approval gates**: `needsApproval: true` (or a predicate function) pauses the loop with `tool_approval_required` finish reason.
-- **modelOutput()**: Transform the tool's structured result into a shorter string for the model's context, while the UI still gets the full result.
-- **Tool updates (streaming)**: Generator tools can `yield` progress payloads that surface as `tool-update` stream chunks.
-
-## Step-by-step
-
-### 1. Basic server tool
-
-```ts
-import { toolDefinition } from '@rudderjs/ai'
-import { z } from 'zod'
-
-const weatherTool = toolDefinition({
-  name: 'get_weather',
-  description: 'Get current weather for a location',
-  inputSchema: z.object({
-    location: z.string().describe('City name'),
-    units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
-  }),
-}).server(async ({ location, units }) => {
-  const data = await fetchWeather(location, units)
-  return { temp: data.temperature, conditions: data.conditions, unit: units }
-})
-```
-
-### 2. Client tool (browser-side execution)
-
-```ts
-// No .server() call -- this is a client tool
-const readClipboardTool = toolDefinition({
-  name: 'read_clipboard',
-  description: 'Read the contents of the user clipboard',
-  inputSchema: z.object({}),
-})
-
-// When the agent calls this tool, the loop pauses with:
-// finishReason: 'client_tool_calls'
-// pendingClientToolCalls: [{ id, name: 'read_clipboard', arguments: {} }]
-// The caller executes it browser-side and resumes with tool results.
-```
-
-### 3. Tool with approval gate
-
-```ts
-const deleteUserTool = toolDefinition({
-  name: 'delete_user',
-  description: 'Permanently delete a user account',
-  inputSchema: z.object({ userId: z.string() }),
-  needsApproval: true,  // always requires approval
-}).server(async ({ userId }) => {
-  await User.forceDelete(userId)
-  return { deleted: true }
-})
-
-// Conditional approval
-const sendEmailTool = toolDefinition({
-  name: 'send_email',
-  description: 'Send an email to a user',
-  inputSchema: z.object({
-    to: z.string(),
-    subject: z.string(),
-    body: z.string(),
-  }),
-  needsApproval: (input) => input.to.endsWith('@external.com'),
-}).server(async (input) => {
-  await sendEmail(input)
-  return { sent: true }
-})
-```
-
-When approval is required, the loop stops with:
-- `finishReason: 'tool_approval_required'`
-- `pendingApprovalToolCall: { toolCall, isClientTool: false }`
-
-Resume by passing `approvedToolCallIds` or `rejectedToolCallIds` in the next prompt options.
-
-### 4. Streaming tool with progress yields
-
-```ts
-const analyzeDataTool = toolDefinition({
-  name: 'analyze_data',
-  description: 'Analyze a dataset and return insights',
-  inputSchema: z.object({ datasetId: z.string() }),
-}).server(async function* ({ datasetId }) {
-  const dataset = await loadDataset(datasetId)
-
-  yield { progress: 25, message: 'Loading data...' }
-
-  const cleaned = cleanData(dataset)
-  yield { progress: 50, message: 'Cleaning data...' }
-
-  const analysis = runAnalysis(cleaned)
-  yield { progress: 75, message: 'Running analysis...' }
-
-  const insights = summarize(analysis)
-  yield { progress: 100, message: 'Complete' }
-
-  return { insights, recordCount: dataset.length }
-  // Each yield surfaces as a 'tool-update' StreamChunk
-  // The return value is the final 'tool-result'
-})
-```
-
-### 5. modelOutput() -- control what the model sees
-
-```ts
-const searchTool = toolDefinition({
-  name: 'search_documents',
-  description: 'Search the document database',
-  inputSchema: z.object({ query: z.string() }),
-}).server(async ({ query }) => {
-  const results = await searchDb(query)
-  return {
-    results,              // full structured data for the UI
-    totalCount: results.length,
-    metadata: { /* ... */ },
-  }
-}).modelOutput((result) => {
-  // The MODEL only sees this condensed string on its next step
-  // The UI still receives the full structured result above
-  return `Found ${result.totalCount} results: ${result.results.map(r => r.title).join(', ')}`
-})
-```
-
-### 6. Dynamic tools (runtime-defined schemas)
-
-```ts
-import { dynamicTool } from '@rudderjs/ai'
-
-// When the schema isn't known at compile time
-const tool = dynamicTool({
-  name: agentDef.slug,
-  description: agentDef.description,
-  inputSchema: z.object({}),
-}).server(async () => {
-  return await agentDef.run()
-})
-```
-
-### 7. Tool with ToolCallContext
-
-```ts
-const myTool = toolDefinition({
-  name: 'my_tool',
-  description: 'A tool that needs its call ID',
-  inputSchema: z.object({ data: z.string() }),
-}).server(async (input, ctx) => {
-  // ctx.toolCallId is the unique ID the model assigned to this call
-  console.log(`Tool call ID: ${ctx?.toolCallId}`)
-  return { processed: true }
-})
-```
-
-### 8. Lazy tools (not advertised until needed)
-
-```ts
-const secretTool = toolDefinition({
-  name: 'admin_panel',
-  description: 'Access admin functions',
-  inputSchema: z.object({ action: z.string() }),
-  lazy: true,  // not included in the tool list sent to the model
-}).server(async ({ action }) => {
-  // Only callable if the model explicitly names it
-  return { result: await adminAction(action) }
-})
-```
-
-### 9. Pause the parent loop from inside a server tool
-
-```ts
-import { pauseForClientTools, pauseForApproval } from '@rudderjs/ai'
-
-const runSubAgentTool = toolDefinition({
-  name: 'run_sub_agent',
-  description: 'Run a sub-agent that may need browser tools or approval',
-  inputSchema: z.object({ task: z.string() }),
-}).server(async function* ({ task }, ctx) {
-  const subResponse = await runSubAgent(task)
-
-  if (subResponse.pendingClientToolCalls?.length) {
-    // Client-tool pause -- surface inner client tool calls to the browser
-    yield pauseForClientTools(subResponse.pendingClientToolCalls, subResponse.resumeId)
-    return undefined as never  // unreachable after pause
-  }
-
-  if (subResponse.pendingApprovalToolCall) {
-    // Approval pause -- surface the gated tool call for the user to approve/reject
-    const { toolCall, isClientTool } = subResponse.pendingApprovalToolCall
-    yield pauseForApproval(toolCall, isClientTool, subResponse.resumeId)
-    return undefined as never
-  }
-
-  return subResponse.text
-})
-```
-
-`Agent.asTool({ suspendable })` does this automatically — yield manually only for hand-rolled sub-agent runners or non-agent tools that need a browser/approval round-trip.
-
-### 10. Using tools with an agent
-
-```ts
-import { Agent } from '@rudderjs/ai'
-import type { HasTools, AnyTool } from '@rudderjs/ai'
-
-class MyAgent extends Agent implements HasTools {
-  instructions() { return 'You are a helpful assistant with access to tools.' }
-
-  tools(): AnyTool[] {
-    return [
-      weatherTool,
-      searchTool,
-      analyzeDataTool,
-      deleteUserTool,
-    ]
-  }
-}
-
-// Or with the anonymous agent
-const response = await agent({
-  instructions: 'You are helpful.',
-  tools: [weatherTool, searchTool],
-}).prompt('What is the weather in Paris?')
-```
-
-## Examples
-
-Tools are typically defined in `app/Tools/` or co-located with the agent that uses them. See `packages/ai/src/tool.ts` for the full builder API.
-
-## Common pitfalls
-
-- **Zod schemas required**: Tool input schemas must be Zod objects. They are converted to JSON Schema for each provider automatically.
-- **Generator vs async function**: Use `async function*` only when you need streaming progress yields. For simple tools, use a regular `async` function.
-- **modelOutput is optional**: Only use `.modelOutput()` when the tool returns large structured data that would waste model context. The default behavior is `JSON.stringify` of the result.
-- **Approval flow is two-step**: When a tool needs approval, the loop stops. You must resume with `approvedToolCallIds` or `rejectedToolCallIds` in the next `prompt()` call's options. For approval-gated tools inside a sub-agent wrapped via `asTool({ suspendable })`, resume goes through `Agent.resumeAsTool(subRunId, [], { runStore, agent, approvedToolCallIds })` — the snapshot's `pauseKind: 'approval'` discriminator routes the resume contract.
-- **Client tool placeholder mode**: By default, client tools without `execute` get a placeholder result and the loop continues. Pass `toolCallStreamingMode: 'stop-on-client-tool'` to pause instead.
-- **exactOptionalPropertyTypes**: If your tsconfig has this enabled, do not pass `undefined` for optional tool parameters -- omit the key entirely.
-- **Tool name conventions**: Use `snake_case` for tool names (e.g. `get_weather`, `search_documents`). This matches what AI models expect.

package/dist/agent-run-store.d.ts

@@ -1,161 +0,0 @@
-import type { AiMessage, ToolCall } from './types.js';
-/**
- * Discriminator for the kind of pause a standalone run is parked on.
- * Mirrors {@link SubAgentPauseKind} — the two run-store families share a
- * vocabulary so a host can persist sub-agent and top-level pauses the same way.
- *
- * - `'client_tool'` — the run surfaced one or more client tools; resume must
- *   carry one tool-result per id in `pendingToolCallIds`. The default when the
- *   field is absent (older snapshots stay readable after an upgrade).
- * - `'approval'` — the run stopped on an approval gate; resume must carry an
- *   approve/reject decision covering the single id in `pendingToolCallIds`.
- */
-export type AgentPauseKind = 'client_tool' | 'approval';
-/**
- * Snapshot of a paused **standalone** (top-level) agent run — the state a host
- * persists between an `agent.stream()` that parks on a client tool or approval
- * gate and the follow-up request that resumes it.
- *
- * This is the standalone sibling of {@link SubAgentRunSnapshot}: same idea, but
- * for a top-level `stream()` rather than an `Agent.asTool` sub-run. The shape is
- * intentionally replay-ready — `messages` is the full conversation up to the
- * pause point, so resume only appends the incoming client-tool results (or
- * injects the approval decision) and re-enters `stream()` in `messages` mode.
- */
-export interface AgentRunState {
-    /** Full conversation history at suspend time (system + user + every interleaved assistant/tool message). */
-    messages: AiMessage[];
-    /**
-     * Tool-call ids the run is waiting on.
-     *
-     * - `pauseKind === 'client_tool'` (default): one entry per client tool the
-     *   loop surfaced; resume appends one result per id.
-     * - `pauseKind === 'approval'`: a single entry for the approval-gated tool
-     *   call; resume injects the id into the approve or reject set.
-     */
-    pendingToolCallIds: string[];
-    /** Total steps the run has executed across all suspends so far. */
-    stepsSoFar: number;
-    /** Total prompt+completion tokens accumulated across all suspends. */
-    tokensSoFar: number;
-    /**
-     * Discriminator for the resume contract. Defaults to `'client_tool'` when
-     * absent so snapshots written before approval-pause support stay readable.
-     */
-    pauseKind?: AgentPauseKind;
-    /**
-     * Approval pauses only. The full pending tool-call payload (name + args + id)
-     * so a renderer can show "approve `delete_user(id=42)`?" without re-running
-     * the agent. Mirrors `AgentResponse.pendingApprovalToolCall`.
-     */
-    pendingApprovalToolCall?: {
-        toolCall: ToolCall;
-        isClientTool: boolean;
-    };
-    /**
-     * Opaque metadata the host can pass through. The framework treats this as
-     * JSON and never reads it — useful for rehydrating request context
-     * (e.g. `{ userId, threadId, agentSlug }`) around the resume call.
-     */
-    meta?: unknown;
-}
-/**
- * Pluggable persistence backend for paused standalone agent runs. The framework
- * ships two reference implementations:
- *
- * - {@link InMemoryAgentRunStore} — a `Map`-backed store. Single-process only;
- *   fine for unit tests and small dev setups, lossy across worker processes and
- *   restarts.
- * - {@link CachedAgentRunStore} — lazy adapter on top of `@rudderjs/cache`.
- *   Cross-process / cross-restart when the cache is configured with redis or any
- *   non-memory driver.
- *
- * Hosts may implement their own (Redis directly, Prisma, etc.) by satisfying
- * this interface.
- *
- * The split between {@link load} (non-destructive peek) and {@link consume}
- * (atomic single-use read+delete) matters: a host can `load()` to render a
- * "waiting for approval" view on a GET without burning the run, then `consume()`
- * on the resume POST so a forged or replayed `runId` cannot read data twice.
- */
-export interface AgentRunStore {
-    /** Persist a snapshot under `runId`. Implementations MAY apply a TTL. */
-    store(runId: string, state: AgentRunState): Promise<void>;
-    /**
-     * Non-destructive read. Returns `null` if the id is unknown or the snapshot
-     * has expired. Leaves the snapshot in place — use for read-only peeks
-     * (rendering a pending-run view); use {@link consume} when resuming.
-     */
-    load(runId: string): Promise<AgentRunState | null>;
-    /**
-     * Atomic read + delete. Returns `null` if the id is unknown or the snapshot
-     * has expired. Single-use semantics matter: a forged or replayed `runId` must
-     * not return data twice.
-     */
-    consume(runId: string): Promise<AgentRunState | null>;
-}
-/**
- * Generate a fresh, hard-to-guess run id. Uses `crypto.randomUUID()` where the
- * runtime exposes it (Node ≥ 16.7, every modern browser, Deno, Bun), falling
- * back to a timestamp + random suffix. Run ids are unguessable on purpose — a
- * `runId` is a capability handle to a parked conversation, so a predictable id
- * would let a third party `consume()` someone else's run.
- */
-export declare function newAgentRunId(): string;
-/**
- * `Map`-backed implementation suitable for tests and single-process dev.
- * Loses state across restarts and worker processes — for any multi-worker
- * deployment, use {@link CachedAgentRunStore} or a custom backend.
- */
-export declare class InMemoryAgentRunStore implements AgentRunStore {
-    private readonly states;
-    store(runId: string, state: AgentRunState): Promise<void>;
-    load(runId: string): Promise<AgentRunState | null>;
-    consume(runId: string): Promise<AgentRunState | null>;
-    /** Test helper — clears all snapshots without consuming. */
-    clear(): void;
-}
-/**
- * Minimal structural shape of a cache adapter (the methods this store touches).
- * Mirrors `@rudderjs/cache`'s `CacheAdapter` so the dep stays structural — the
- * framework's main entry stays runtime-agnostic.
- */
-interface CacheStoreLike {
-    get<T = unknown>(key: string): Promise<T | null>;
-    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
-    forget(key: string): Promise<void>;
-}
-export interface CachedAgentRunStoreOptions {
-    /**
-     * Cache adapter to use. When omitted, the store loads `@rudderjs/cache`
-     * lazily and falls back to the registered global adapter
-     * (`CacheRegistry.get()`); throws if neither resolves.
-     */
-    cache?: CacheStoreLike;
-    /** Key namespace prefix. Default `'rudderjs:ai:agent-run:'`. */
-    keyPrefix?: string;
-    /** Time-to-live in seconds. Default 5 minutes. */
-    ttlSeconds?: number;
-}
-/**
- * Standalone agent run store backed by `@rudderjs/cache`. Loads the cache
- * adapter lazily so `@rudderjs/ai`'s main entry stays runtime-agnostic (no
- * static import on the cache package).
- *
- * Default TTL is 5 minutes — long enough for a browser to round-trip a few
- * client tool calls or an approval decision, short enough that abandoned runs
- * garbage-collect promptly and the storage bill stays bounded.
- */
-export declare class CachedAgentRunStore implements AgentRunStore {
-    private readonly explicitCache?;
-    private readonly keyPrefix;
-    private readonly ttlSeconds;
-    private resolvedCache?;
-    constructor(opts?: CachedAgentRunStoreOptions);
-    private getCache;
-    store(runId: string, state: AgentRunState): Promise<void>;
-    load(runId: string): Promise<AgentRunState | null>;
-    consume(runId: string): Promise<AgentRunState | null>;
-}
-export {};
-//# sourceMappingURL=agent-run-store.d.ts.map

package/dist/agent-run-store.d.ts.map

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

package/dist/agent-run-store.js

@@ -1,98 +0,0 @@
-/**
- * Generate a fresh, hard-to-guess run id. Uses `crypto.randomUUID()` where the
- * runtime exposes it (Node ≥ 16.7, every modern browser, Deno, Bun), falling
- * back to a timestamp + random suffix. Run ids are unguessable on purpose — a
- * `runId` is a capability handle to a parked conversation, so a predictable id
- * would let a third party `consume()` someone else's run.
- */
-export function newAgentRunId() {
-    if (typeof globalThis.crypto?.randomUUID === 'function')
-        return globalThis.crypto.randomUUID();
-    return `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
-}
-// ─── In-memory ─────────────────────────────────────────────
-/**
- * `Map`-backed implementation suitable for tests and single-process dev.
- * Loses state across restarts and worker processes — for any multi-worker
- * deployment, use {@link CachedAgentRunStore} or a custom backend.
- */
-export class InMemoryAgentRunStore {
-    states = new Map();
-    async store(runId, state) {
-        this.states.set(runId, state);
-    }
-    async load(runId) {
-        return this.states.get(runId) ?? null;
-    }
-    async consume(runId) {
-        const state = this.states.get(runId);
-        if (!state)
-            return null;
-        this.states.delete(runId);
-        return state;
-    }
-    /** Test helper — clears all snapshots without consuming. */
-    clear() {
-        this.states.clear();
-    }
-}
-/**
- * Standalone agent run store backed by `@rudderjs/cache`. Loads the cache
- * adapter lazily so `@rudderjs/ai`'s main entry stays runtime-agnostic (no
- * static import on the cache package).
- *
- * Default TTL is 5 minutes — long enough for a browser to round-trip a few
- * client tool calls or an approval decision, short enough that abandoned runs
- * garbage-collect promptly and the storage bill stays bounded.
- */
-export class CachedAgentRunStore {
-    explicitCache;
-    keyPrefix;
-    ttlSeconds;
-    resolvedCache;
-    constructor(opts = {}) {
-        if (opts.cache)
-            this.explicitCache = opts.cache;
-        this.keyPrefix = opts.keyPrefix ?? 'rudderjs:ai:agent-run:';
-        this.ttlSeconds = opts.ttlSeconds ?? 5 * 60;
-    }
-    async getCache() {
-        if (this.resolvedCache)
-            return this.resolvedCache;
-        if (this.explicitCache) {
-            this.resolvedCache = this.explicitCache;
-            return this.resolvedCache;
-        }
-        // Lazy-import @rudderjs/cache and ask the registry for the active adapter.
-        // This keeps the static import surface zero — the import only fires when the
-        // host actually opts into suspendable standalone runs. We dodge static
-        // module-resolution by using an indirected specifier so `@rudderjs/cache`
-        // doesn't need to be a declared dep of `@rudderjs/ai` (optional runtime peer).
-        const cacheSpecifier = '@rudderjs/cache';
-        const mod = await import(/* @vite-ignore */ cacheSpecifier);
-        const adapter = mod.CacheRegistry?.get?.();
-        if (!adapter) {
-            throw new Error('[Rudder AI] CachedAgentRunStore needs a cache adapter. Install `@rudderjs/cache`, register a driver, or pass `{ cache }` explicitly.');
-        }
-        this.resolvedCache = adapter;
-        return adapter;
-    }
-    async store(runId, state) {
-        const cache = await this.getCache();
-        await cache.set(this.keyPrefix + runId, state, this.ttlSeconds);
-    }
-    async load(runId) {
-        const cache = await this.getCache();
-        return (await cache.get(this.keyPrefix + runId)) ?? null;
-    }
-    async consume(runId) {
-        const cache = await this.getCache();
-        const key = this.keyPrefix + runId;
-        const state = await cache.get(key);
-        if (!state)
-            return null;
-        await cache.forget(key);
-        return state;
-    }
-}
-//# sourceMappingURL=agent-run-store.js.map

package/dist/agent-run-store.js.map

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

package/dist/agent-sse.d.ts

@@ -1,153 +0,0 @@
-/**
- * Named-event SSE protocol for streaming an agent loop to a browser.
- *
- * `@rudderjs/ai` already ships the Vercel AI SDK data-stream protocol
- * ({@link toVercelDataStream}) - the numeric-prefix wire (`0:` / `9:` / `a:`
- * ...). This is the alternative for apps that want a plain
- * `text/event-stream` with self-describing event names that mirror the agent
- * loop's own lifecycle (`text`, `tool_call`, `tool_update`, `tool_result`,
- * `pending_client_tools`, `tool_approval_required`, `handoff`, `complete`,
- * `error`).
- *
- * Both ends live here so the wire vocabulary can never drift:
- *
- * - Server: {@link toAgentSseStream} / {@link toAgentSseResponse} project an
- *   `agent.stream()` result onto the named events and frame them as SSE.
- * - Browser: {@link readAgentStream} decodes the same events back into an
- *   {@link AgentStreamTurn} and fires per-event callbacks for UI side effects.
- *   {@link applyAgentSseEvent} is exposed so the per-event reducer can be
- *   unit-tested against a synthetic turn.
- *
- * Runtime-agnostic: uses only web globals (`ReadableStream`, `Response`,
- * `TextEncoder` / `TextDecoder`, `crypto.randomUUID`), no `node:` imports, so
- * the module is safe in the main entry and runs server-side (Node / edge) and
- * client-side alike.
- *
- * This ships the framework-generic core. App-specific events (conversation
- * ids, billing, sub-run fan-out bookkeeping, server-authoritative history
- * sync) are not part of it - emit and decode those alongside this protocol on
- * your own channel.
- */
-import type { AgentStreamResponse, AiMessage, FinishReason, TokenUsage, ToolCall } from './types.js';
-/** The named SSE events this protocol emits, in agent-loop order. */
-export type AgentSseEventName = 'text' | 'tool_call' | 'tool_update' | 'tool_result' | 'pending_client_tools' | 'tool_approval_required' | 'handoff' | 'complete' | 'error';
-/** What the loop parked on when it paused, surfaced on the `complete` event. */
-export type AgentAwaiting = 'client_tools' | 'approval';
-export interface AgentSseTextPayload {
-    text: string;
-}
-export interface AgentSseToolCallPayload {
-    id?: string;
-    tool: string;
-    input?: Record<string, unknown>;
-}
-export interface AgentSseToolUpdatePayload {
-    id?: string;
-    tool?: string;
-    update: unknown;
-}
-export interface AgentSseToolResultPayload {
-    id?: string;
-    toolCallId?: string;
-    tool?: string;
-    /** String passthrough when the tool returned a string, else JSON-encoded. */
-    content: string;
-}
-export interface AgentSsePendingClientToolsPayload {
-    toolCalls: ToolCall[];
-}
-export interface AgentSseApprovalPayload {
-    toolCall: ToolCall;
-    isClientTool: boolean;
-}
-export interface AgentSseHandoffPayload {
-    from: string;
-    to: string;
-    message?: string;
-}
-export interface AgentSseCompletePayload {
-    done: true;
-    finishReason?: FinishReason;
-    awaiting?: AgentAwaiting;
-    /** Number of model steps the run took (`response.steps.length`). */
-    steps?: number;
-    usage?: TokenUsage;
-}
-export interface AgentSseErrorPayload {
-    message: string;
-}
-/**
- * Project an `agent.stream()` result onto the named-event SSE wire as a
- * `ReadableStream<Uint8Array>`.
- *
- * Iterates the chunk stream, emits one named event per loop chunk, then
- * awaits the `response` promise and emits a terminal `complete` event
- * carrying `done`, `finishReason`, the `awaiting` pause (if any), step count,
- * and usage. If iteration or the response throws, an `error` event is emitted
- * and the stream closes cleanly so the browser reader's `onError` fires.
- */
-export declare function toAgentSseStream(streaming: AgentStreamResponse): ReadableStream<Uint8Array>;
-/**
- * Wrap {@link toAgentSseStream} in a `Response` with the standard
- * `text/event-stream` headers (no caching, no proxy buffering). Return it
- * directly from a route handler.
- */
-export declare function toAgentSseResponse(streaming: AgentStreamResponse, init?: ResponseInit): Response;
-/**
- * The accumulated state of one streamed agent turn, built up event by event
- * by {@link readAgentStream}. Mirrors {@link AgentResponse} fields the browser
- * needs to render the turn and build the next continuation request.
- */
-export interface AgentStreamTurn {
-    /** Concatenated `text` event deltas. */
-    assistantText: string;
-    /** Tool calls stamped by `tool_call` events (for the next continuation). */
-    assistantToolCalls: ToolCall[];
-    /** Server-side `role:'tool'` result messages from `tool_result` events. */
-    serverToolResults: AiMessage[];
-    /** Client tool calls from a `pending_client_tools` event to run locally. */
-    pendingClientTools: ToolCall[];
-    /** Approval pause from a `tool_approval_required` event. */
-    pendingApproval: AgentSseApprovalPayload | null;
-    /** Chain of agent class names traversed via `handoff` events. */
-    handoffPath: string[];
-    /** `true` once a `complete` event with `done: true` arrived. */
-    done: boolean;
-    /** What the run paused on, from the `complete` event. */
-    awaiting: AgentAwaiting | undefined;
-}
-/** A fresh, empty {@link AgentStreamTurn}. */
-export declare function newAgentStreamTurn(): AgentStreamTurn;
-/** Per-event callbacks fired by {@link readAgentStream} for UI side effects. */
-export interface AgentStreamCallbacks {
-    onText?: (text: string) => void;
-    onToolCall?: (call: AgentSseToolCallPayload) => void;
-    onToolUpdate?: (update: AgentSseToolUpdatePayload) => void;
-    onToolResult?: (result: AgentSseToolResultPayload) => void;
-    onPendingClientTools?: (toolCalls: ToolCall[]) => void;
-    onToolApprovalRequired?: (approval: AgentSseApprovalPayload) => void;
-    onHandoff?: (handoff: AgentSseHandoffPayload) => void;
-    onComplete?: (data: AgentSseCompletePayload) => void;
-    onError?: (error: AgentSseErrorPayload) => void;
-    /** Fired for any SSE event outside the standard protocol vocabulary. Use this
-     *  to observe app-specific events (e.g. a server-issued `run_started` carrying
-     *  a `runId`) without consuming the response body twice. */
-    onAppEvent?: (event: string, data: unknown) => void;
-}
-/**
- * Read a named-event agent-SSE response body, applying each event to a fresh
- * {@link AgentStreamTurn} and firing the matching callback. Resolves with the
- * accumulated turn once the stream closes.
- *
- * The caller owns the `fetch` and the `!resp.ok` branch (so a rich error body
- * can be read for non-2xx responses); pass an already-OK response. A missing
- * body resolves to an empty turn. Malformed event JSON is skipped.
- */
-export declare function readAgentStream(resp: Response, callbacks?: AgentStreamCallbacks): Promise<AgentStreamTurn>;
-/**
- * Apply a single parsed SSE event to the turn state and fire the matching
- * callback. Mutates `turn`; otherwise pure. Exposed for unit-testing the
- * reducer against a synthetic turn without a live stream.
- */
-export declare function applyAgentSseEvent(event: string, data: unknown, turn: AgentStreamTurn, callbacks?: AgentStreamCallbacks): void;
-//# sourceMappingURL=agent-sse.d.ts.map