@rudderjs/ai 1.12.0 → 1.14.0

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

@@ -0,0 +1,161 @@
+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

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

@@ -0,0 +1,98 @@
+/**
+ * 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('[RudderJS 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

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

@@ -0,0 +1,149 @@
+/**
+ * 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;
+}
+/**
+ * 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

package/dist/agent-sse.d.ts.map

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