@rudderjs/ai 1.16.0 → 1.17.0

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export { BedrockProvider, type BedrockConfig } from './providers/bedrock.js';
 export { toolDefinition, dynamicTool, ToolBuilder, toolToSchema, pauseForClientTools, isPauseForClientToolsChunk, pauseForApproval, isPauseForApprovalChunk, } from './tool.js';
 export type { PauseForClientToolsChunk, PauseForApprovalChunk } from './tool.js';
 export { zodToJsonSchema } from './zod-to-json-schema.js';
+export { scopedTool, capability, flattenCapabilities, ScopedToolError } from './scoped-tool.js';
+export type { ScopedToolOptions, ScopedCapability, FlatPlan } from './scoped-tool.js';
 export { handoff, isHandoffTool } from './handoff.js';
 export type { HandoffTool, HandoffOptions, HandoffSpec } from './handoff.js';
 export { Agent, ConversableAgent, agent, stepCountIs, hasToolCall, setConversationStore, setUserMemory, resolveUserMemory } from './agent.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -22,6 +22,9 @@ export { BedrockProvider } from './providers/bedrock.js';
 // Tools
 export { toolDefinition, dynamicTool, ToolBuilder, toolToSchema, pauseForClientTools, isPauseForClientToolsChunk, pauseForApproval, isPauseForApprovalChunk, } from './tool.js';
 export { zodToJsonSchema } from './zod-to-json-schema.js';
+// Scoped / multi-capability tools — collapse a discriminated union of
+// capability branches into one flat function-call schema.
+export { scopedTool, capability, flattenCapabilities, ScopedToolError } from './scoped-tool.js';
 // Handoffs
 export { handoff, isHandoffTool } from './handoff.js';
 // Agent

package/dist/index.js.map

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

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

@@ -0,0 +1,111 @@
+/**
+ * Framework-free core of the `useAgentRun` React hook.
+ *
+ * The React hook (`useAgentRun.ts`) is a thin wrapper around the pieces here —
+ * same posture as `@rudderjs/sync`'s `CollabRoomManager` vs `useCollabRoom`:
+ * keeping the state machine and the stream-driving loop out of React lets us
+ * exhaustively unit-test the client-tool round-trip and the approval resume
+ * without a React testing harness (the framework intentionally ships none).
+ *
+ * Builds on the named-event agent-SSE protocol in `../agent-sse.ts`
+ * (`readAgentStream` + the `AgentStreamTurn` it accumulates). No `react` and no
+ * `node:` imports — safe in any `fetch`-capable runtime.
+ */
+import type { AgentStreamCallbacks, AgentStreamTurn } from '../agent-sse.js';
+import type { ToolCall } from '../types.js';
+/** One renderable entry in a run's transcript, in arrival order. */
+export type AgentRunOutput = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_call';
+    id?: string;
+    tool: string;
+    input?: Record<string, unknown>;
+} | {
+    type: 'tool_update';
+    id?: string;
+    tool?: string;
+    update: unknown;
+} | {
+    type: 'tool_result';
+    id?: string;
+    tool?: string;
+    content: string;
+} | {
+    type: 'approval_request';
+    toolCall: ToolCall;
+    isClientTool: boolean;
+} | {
+    type: 'handoff';
+    from: string;
+    to: string;
+    message?: string;
+} | {
+    type: 'error';
+    message: string;
+};
+/**
+ * Append one decoded SSE event to the output transcript, returning a NEW array
+ * (so a React consumer can use it as immutable state). Consecutive `text`
+ * deltas coalesce into the trailing text entry so streamed text renders as one
+ * growing block. `complete` and `pending_client_tools` produce no transcript
+ * entry — they drive run status / pending-action state instead.
+ */
+export declare function appendAgentOutput(outputs: AgentRunOutput[], event: string, data: unknown): AgentRunOutput[];
+/** A client-executed tool result, keyed to its originating tool call. */
+export interface AgentToolResult {
+    toolCallId: string;
+    result: unknown;
+}
+/**
+ * Run each pending client-tool call through the resolver, in order, collecting
+ * results keyed by `toolCallId`. A resolver that throws yields an
+ * `{ error }` result rather than aborting the batch — the model sees the
+ * failure as that tool's result and can recover, matching the server-side
+ * tool-error posture.
+ */
+export declare function executeClientTools(calls: ToolCall[], resolver: (call: ToolCall) => unknown | Promise<unknown>): Promise<AgentToolResult[]>;
+/**
+ * The intent the consumer's `request` function turns into an SSE `Response`.
+ * The hook owns the run/resume state machine; the app owns the endpoint and
+ * the request body shape (only the app's route knows how to reconstruct the
+ * server-side message history), so the driver hands it a typed intent and
+ * expects a streaming `Response` back.
+ */
+export type AgentRunRequest<TInput = unknown> = {
+    type: 'run';
+    input: TInput;
+} | {
+    type: 'resume';
+    /** The accumulated turn the resume continues from. */
+    turn: AgentStreamTurn;
+    /** Results from client-tool calls executed in the browser. */
+    clientToolResults: AgentToolResult[];
+    /** Tool-call ids the user approved. */
+    approved: string[];
+    /** Tool-call ids the user rejected. */
+    rejected: string[];
+};
+export interface AgentRunDriverOptions<TInput = unknown> {
+    /** Turn a run/resume intent into the streaming SSE `Response`. */
+    request: (req: AgentRunRequest<TInput>, signal: AbortSignal) => Promise<Response>;
+    /**
+     * Optional client-tool resolver. When provided, a run that pauses awaiting
+     * client tools auto-executes them and resumes — no manual `respond`. Omit it
+     * to surface the pending calls and resume by hand.
+     */
+    clientTools?: (call: ToolCall) => unknown | Promise<unknown>;
+    /** Forwarded to `readAgentStream` so the consumer sees events as they arrive. */
+    callbacks?: AgentStreamCallbacks;
+    signal: AbortSignal;
+}
+/**
+ * Drive one logical agent run to a settling point: stream the response,
+ * accumulate the turn, and — when a client-tool resolver is configured —
+ * auto-resume across client-tool pauses until the run completes or parks on an
+ * approval gate / manual client-tool round-trip. Returns the final
+ * {@link AgentStreamTurn}. Framework-free; the hook wires `callbacks` to state.
+ */
+export declare function driveAgentRun<TInput = unknown>(initial: AgentRunRequest<TInput>, opts: AgentRunDriverOptions<TInput>): Promise<AgentStreamTurn>;
+//# sourceMappingURL=agent-run.d.ts.map

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

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

package/dist/react/agent-run.js

@@ -0,0 +1,107 @@
+/**
+ * Framework-free core of the `useAgentRun` React hook.
+ *
+ * The React hook (`useAgentRun.ts`) is a thin wrapper around the pieces here —
+ * same posture as `@rudderjs/sync`'s `CollabRoomManager` vs `useCollabRoom`:
+ * keeping the state machine and the stream-driving loop out of React lets us
+ * exhaustively unit-test the client-tool round-trip and the approval resume
+ * without a React testing harness (the framework intentionally ships none).
+ *
+ * Builds on the named-event agent-SSE protocol in `../agent-sse.ts`
+ * (`readAgentStream` + the `AgentStreamTurn` it accumulates). No `react` and no
+ * `node:` imports — safe in any `fetch`-capable runtime.
+ */
+import { readAgentStream } from '../agent-sse.js';
+/**
+ * Append one decoded SSE event to the output transcript, returning a NEW array
+ * (so a React consumer can use it as immutable state). Consecutive `text`
+ * deltas coalesce into the trailing text entry so streamed text renders as one
+ * growing block. `complete` and `pending_client_tools` produce no transcript
+ * entry — they drive run status / pending-action state instead.
+ */
+export function appendAgentOutput(outputs, event, data) {
+    switch (event) {
+        case 'text': {
+            const text = data.text ?? '';
+            if (!text)
+                return outputs;
+            const last = outputs[outputs.length - 1];
+            if (last && last.type === 'text') {
+                return [...outputs.slice(0, -1), { type: 'text', text: last.text + text }];
+            }
+            return [...outputs, { type: 'text', text }];
+        }
+        case 'tool_call': {
+            const d = data;
+            return [...outputs, { type: 'tool_call', ...(d.id ? { id: d.id } : {}), tool: d.tool, ...(d.input ? { input: d.input } : {}) }];
+        }
+        case 'tool_update': {
+            const d = data;
+            return [...outputs, { type: 'tool_update', ...(d.id ? { id: d.id } : {}), ...(d.tool ? { tool: d.tool } : {}), update: d.update }];
+        }
+        case 'tool_result': {
+            const d = data;
+            const id = d.toolCallId ?? d.id;
+            return [...outputs, { type: 'tool_result', ...(id ? { id } : {}), ...(d.tool ? { tool: d.tool } : {}), content: d.content }];
+        }
+        case 'tool_approval_required': {
+            const d = data;
+            return [...outputs, { type: 'approval_request', toolCall: d.toolCall, isClientTool: d.isClientTool }];
+        }
+        case 'handoff': {
+            const d = data;
+            return [...outputs, { type: 'handoff', from: d.from, to: d.to, ...(d.message ? { message: d.message } : {}) }];
+        }
+        case 'error': {
+            const d = data;
+            return [...outputs, { type: 'error', message: d.message ?? 'Unknown error' }];
+        }
+        default:
+            return outputs;
+    }
+}
+/**
+ * Run each pending client-tool call through the resolver, in order, collecting
+ * results keyed by `toolCallId`. A resolver that throws yields an
+ * `{ error }` result rather than aborting the batch — the model sees the
+ * failure as that tool's result and can recover, matching the server-side
+ * tool-error posture.
+ */
+export async function executeClientTools(calls, resolver) {
+    const results = [];
+    for (const call of calls) {
+        try {
+            results.push({ toolCallId: call.id, result: await resolver(call) });
+        }
+        catch (err) {
+            results.push({ toolCallId: call.id, result: { error: err instanceof Error ? err.message : String(err) } });
+        }
+    }
+    return results;
+}
+/**
+ * Drive one logical agent run to a settling point: stream the response,
+ * accumulate the turn, and — when a client-tool resolver is configured —
+ * auto-resume across client-tool pauses until the run completes or parks on an
+ * approval gate / manual client-tool round-trip. Returns the final
+ * {@link AgentStreamTurn}. Framework-free; the hook wires `callbacks` to state.
+ */
+export async function driveAgentRun(initial, opts) {
+    let req = initial;
+    for (;;) {
+        const resp = await opts.request(req, opts.signal);
+        if (!resp.ok) {
+            throw new Error(`Agent stream request failed with status ${resp.status}.`);
+        }
+        const turn = await readAgentStream(resp, opts.callbacks);
+        // Auto-resume only across client-tool pauses, and only with a resolver.
+        // Approval pauses always park for an explicit approve/reject decision.
+        if (turn.awaiting === 'client_tools' && opts.clientTools && turn.pendingClientTools.length > 0) {
+            const clientToolResults = await executeClientTools(turn.pendingClientTools, opts.clientTools);
+            req = { type: 'resume', turn, clientToolResults, approved: [], rejected: [] };
+            continue;
+        }
+        return turn;
+    }
+}
+//# sourceMappingURL=agent-run.js.map

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

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

package/dist/react/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * React client runtime for `@rudderjs/ai`.
+ *
+ * The agent framework, providers, and the runtime-agnostic agent-SSE protocol
+ * (`readAgentStream` + the server framers) live in the main `@rudderjs/ai`
+ * entry. This subpath adds the React hook that drives a streamed agent run from
+ * a component — same split as `@rudderjs/sync/react` (the main entry stays
+ * React-free; React lives behind `/react`).
+ *
+ * Peer requirement: `react@>=19.2.0`.
+ */
+export { useAgentRun } from './useAgentRun.js';
+export type { AgentRunStatus, UseAgentRunOptions, UseAgentRunResult, } from './useAgentRun.js';
+export { appendAgentOutput, executeClientTools, driveAgentRun, } from './agent-run.js';
+export type { AgentRunOutput, AgentToolResult, AgentRunRequest, AgentRunDriverOptions, } from './agent-run.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,kBAAkB,CAAA;AAIzB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,GACd,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,cAAc,EACd,eAAe,EACf,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAA"}

package/dist/react/index.js

@@ -0,0 +1,16 @@
+/**
+ * React client runtime for `@rudderjs/ai`.
+ *
+ * The agent framework, providers, and the runtime-agnostic agent-SSE protocol
+ * (`readAgentStream` + the server framers) live in the main `@rudderjs/ai`
+ * entry. This subpath adds the React hook that drives a streamed agent run from
+ * a component — same split as `@rudderjs/sync/react` (the main entry stays
+ * React-free; React lives behind `/react`).
+ *
+ * Peer requirement: `react@>=19.2.0`.
+ */
+export { useAgentRun } from './useAgentRun.js';
+// Framework-free core — exported so apps can drive a run outside React (or
+// unit-test their own integration) and so the output/request types are nameable.
+export { appendAgentOutput, executeClientTools, driveAgentRun, } from './agent-run.js';
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAO9C,2EAA2E;AAC3E,iFAAiF;AACjF,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,GACd,MAAM,gBAAgB,CAAA"}

package/dist/react/useAgentRun.d.ts

@@ -0,0 +1,64 @@
+import type { AgentSseApprovalPayload, AgentSseCompletePayload } from '../agent-sse.js';
+import type { ToolCall } from '../types.js';
+import { type AgentRunOutput, type AgentRunRequest, type AgentToolResult } from './agent-run.js';
+/**
+ * Run status. While the run is paused awaiting client tools (no resolver) or an
+ * approval decision, status stays `'running'` and `pendingClientTools` /
+ * `pendingApproval` are populated — the UI renders the prompt and calls
+ * `respond` / `approve` / `reject` to continue the same logical run.
+ */
+export type AgentRunStatus = 'idle' | 'running' | 'complete' | 'error';
+export interface UseAgentRunOptions<TInput = unknown> {
+    /**
+     * Turn a run/resume intent into the streaming SSE `Response`. The app owns
+     * the endpoint and request-body shape (only its route can reconstruct the
+     * server-side message history); typically `fetch(endpoint, { ..., signal })`.
+     */
+    request: (req: AgentRunRequest<TInput>, signal: AbortSignal) => Promise<Response>;
+    /**
+     * Optional client-tool resolver. When set, a run that pauses awaiting client
+     * tools auto-executes them and resumes; omit it to surface
+     * `pendingClientTools` and resume manually via `respond`.
+     */
+    clientTools?: (call: ToolCall) => unknown | Promise<unknown>;
+    onComplete?: (data: AgentSseCompletePayload) => void;
+    onError?: (message: string) => void;
+}
+export interface UseAgentRunResult<TInput = unknown> {
+    status: AgentRunStatus;
+    /** Renderable transcript, accumulated across the run and every resume. */
+    outputs: AgentRunOutput[];
+    /** Client-tool calls awaiting a browser round-trip (empty when auto-resolved). */
+    pendingClientTools: ToolCall[];
+    /** The approval gate the run parked on, or `null`. */
+    pendingApproval: AgentSseApprovalPayload | null;
+    error: string | null;
+    /** Start a fresh run, resetting the transcript. */
+    run: (input: TInput) => Promise<void>;
+    /** Resume a client-tool pause with results gathered by hand. */
+    respond: (results: AgentToolResult[]) => Promise<void>;
+    /** Approve the pending approval gate and resume. */
+    approve: (toolCallId: string) => Promise<void>;
+    /** Reject the pending approval gate and resume. */
+    reject: (toolCallId: string) => Promise<void>;
+    /** Abort any in-flight stream and return to `idle`. */
+    reset: () => void;
+}
+/**
+ * React client runtime for the named-event agent-SSE protocol. Drives
+ * `readAgentStream` (via the framework-free `driveAgentRun`), accumulates the
+ * transcript, tracks run status, and surfaces pending client-tool calls and
+ * approval requests with imperative `run` / `respond` / `approve` / `reject`.
+ *
+ * Lives behind the `@rudderjs/ai/react` subpath so the main entry stays
+ * runtime-agnostic (same split as `@rudderjs/sync/react`).
+ *
+ * @example
+ * const { status, outputs, run } = useAgentRun({
+ *   request: (req, signal) =>
+ *     fetch('/api/agent', { method: 'POST', body: JSON.stringify(req), signal }),
+ * })
+ * // <button onClick={() => run('Summarize the latest report')}>Ask</button>
+ */
+export declare function useAgentRun<TInput = unknown>(options: UseAgentRunOptions<TInput>): UseAgentRunResult<TInput>;
+//# sourceMappingURL=useAgentRun.d.ts.map

package/dist/react/useAgentRun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAgentRun.d.ts","sourceRoot":"","sources":["../../src/react/useAgentRun.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EAGxB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAA;AAEvB;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAA;AAEtE,MAAM,WAAW,kBAAkB,CAAC,MAAM,GAAG,OAAO;IAClD;;;;OAIG;IACH,OAAO,EAAO,CAAC,GAAG,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IACtF;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC5D,UAAU,CAAC,EAAG,CAAC,IAAI,EAAE,uBAAuB,KAAK,IAAI,CAAA;IACrD,OAAO,CAAC,EAAM,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC;AAED,MAAM,WAAW,iBAAiB,CAAC,MAAM,GAAG,OAAO;IACjD,MAAM,EAAc,cAAc,CAAA;IAClC,0EAA0E;IAC1E,OAAO,EAAa,cAAc,EAAE,CAAA;IACpC,kFAAkF;IAClF,kBAAkB,EAAE,QAAQ,EAAE,CAAA;IAC9B,sDAAsD;IACtD,eAAe,EAAK,uBAAuB,GAAG,IAAI,CAAA;IAClD,KAAK,EAAe,MAAM,GAAG,IAAI,CAAA;IACjC,mDAAmD;IACnD,GAAG,EAAiB,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,gEAAgE;IAChE,OAAO,EAAa,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACjE,oDAAoD;IACpD,OAAO,EAAa,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACzD,mDAAmD;IACnD,MAAM,EAAc,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACzD,uDAAuD;IACvD,KAAK,EAAe,MAAM,IAAI,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,MAAM,GAAG,OAAO,EAC1C,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAClC,iBAAiB,CAAC,MAAM,CAAC,CA8G3B"}

package/dist/react/useAgentRun.js

@@ -0,0 +1,124 @@
+import { useCallback, useRef, useState } from 'react';
+import { appendAgentOutput, driveAgentRun, } from './agent-run.js';
+/**
+ * React client runtime for the named-event agent-SSE protocol. Drives
+ * `readAgentStream` (via the framework-free `driveAgentRun`), accumulates the
+ * transcript, tracks run status, and surfaces pending client-tool calls and
+ * approval requests with imperative `run` / `respond` / `approve` / `reject`.
+ *
+ * Lives behind the `@rudderjs/ai/react` subpath so the main entry stays
+ * runtime-agnostic (same split as `@rudderjs/sync/react`).
+ *
+ * @example
+ * const { status, outputs, run } = useAgentRun({
+ *   request: (req, signal) =>
+ *     fetch('/api/agent', { method: 'POST', body: JSON.stringify(req), signal }),
+ * })
+ * // <button onClick={() => run('Summarize the latest report')}>Ask</button>
+ */
+export function useAgentRun(options) {
+    const [status, setStatus] = useState('idle');
+    const [outputs, setOutputs] = useState([]);
+    const [pendingClientTools, setPendingClientTools] = useState([]);
+    const [pendingApproval, setPendingApproval] = useState(null);
+    const [error, setError] = useState(null);
+    // Latest values needed by the async driver / resume actions, kept in refs so
+    // the imperative callbacks don't go stale between renders.
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const turnRef = useRef(null);
+    const abortRef = useRef(null);
+    // Shared loop body for both the initial run and every resume.
+    const drive = useCallback(async (req) => {
+        const opts = optionsRef.current;
+        abortRef.current?.abort();
+        const controller = new AbortController();
+        abortRef.current = controller;
+        setStatus('running');
+        setPendingClientTools([]);
+        setPendingApproval(null);
+        setError(null);
+        let sawError = null;
+        const callbacks = {
+            onText: t => setOutputs(o => appendAgentOutput(o, 'text', { text: t })),
+            onToolCall: d => setOutputs(o => appendAgentOutput(o, 'tool_call', d)),
+            onToolUpdate: d => setOutputs(o => appendAgentOutput(o, 'tool_update', d)),
+            onToolResult: d => setOutputs(o => appendAgentOutput(o, 'tool_result', d)),
+            onToolApprovalRequired: d => setOutputs(o => appendAgentOutput(o, 'tool_approval_required', d)),
+            onHandoff: d => setOutputs(o => appendAgentOutput(o, 'handoff', d)),
+            onError: d => { sawError = d.message; setOutputs(o => appendAgentOutput(o, 'error', d)); },
+            onComplete: d => opts.onComplete?.(d),
+        };
+        try {
+            const turn = await driveAgentRun(req, {
+                request: opts.request,
+                callbacks,
+                signal: controller.signal,
+                ...(opts.clientTools ? { clientTools: opts.clientTools } : {}),
+            });
+            if (controller.signal.aborted)
+                return;
+            turnRef.current = turn;
+            if (sawError !== null) {
+                setStatus('error');
+                setError(sawError);
+                opts.onError?.(sawError);
+                return;
+            }
+            // Parked on an approval gate, or on client tools with no resolver:
+            // surface the prompt and keep the run logically open.
+            if (turn.awaiting === 'approval' && turn.pendingApproval) {
+                setPendingApproval(turn.pendingApproval);
+                return;
+            }
+            if (turn.awaiting === 'client_tools' && turn.pendingClientTools.length > 0) {
+                setPendingClientTools(turn.pendingClientTools);
+                return;
+            }
+            setStatus('complete');
+        }
+        catch (err) {
+            if (controller.signal.aborted)
+                return;
+            const message = err instanceof Error ? err.message : String(err);
+            setStatus('error');
+            setError(message);
+            optionsRef.current.onError?.(message);
+        }
+    }, []);
+    const run = useCallback(async (input) => {
+        turnRef.current = null;
+        setOutputs([]);
+        await drive({ type: 'run', input });
+    }, [drive]);
+    const respond = useCallback(async (results) => {
+        const turn = turnRef.current;
+        if (!turn)
+            return;
+        await drive({ type: 'resume', turn, clientToolResults: results, approved: [], rejected: [] });
+    }, [drive]);
+    const approve = useCallback(async (toolCallId) => {
+        const turn = turnRef.current;
+        if (!turn)
+            return;
+        await drive({ type: 'resume', turn, clientToolResults: [], approved: [toolCallId], rejected: [] });
+    }, [drive]);
+    const reject = useCallback(async (toolCallId) => {
+        const turn = turnRef.current;
+        if (!turn)
+            return;
+        await drive({ type: 'resume', turn, clientToolResults: [], approved: [], rejected: [toolCallId] });
+    }, [drive]);
+    const reset = useCallback(() => {
+        abortRef.current?.abort();
+        abortRef.current = null;
+        turnRef.current = null;
+        setStatus('idle');
+        setOutputs([]);
+        setPendingClientTools([]);
+        setPendingApproval(null);
+        setError(null);
+    }, []);
+    return { status, outputs, pendingClientTools, pendingApproval, error, run, respond, approve, reject, reset };
+}
+//# sourceMappingURL=useAgentRun.js.map

package/dist/react/useAgentRun.js.map

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

package/dist/scoped-tool.d.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import { ServerToolBuilder } from './tool.js';
+import type { ToolCallContext, ToolNeedsApproval } from './types.js';
+/**
+ * One capability branch of a scoped tool: a named sub-tool with its own
+ * input shape + handler. Authored either inline in {@link scopedTool}'s
+ * `capabilities` map or via the {@link capability} helper (which preserves
+ * per-branch input inference for the handler signature).
+ */
+export interface ScopedCapability<TInput extends z.ZodType = z.ZodType, TOutput = unknown, TUpdate = unknown> {
+    /** Optional per-capability description, surfaced in the discriminator enum note. */
+    description?: string;
+    /** This branch's input schema. Validated in code before the handler runs. */
+    input: TInput;
+    /**
+     * Branch handler. May be a plain async function (single return value) or
+     * an `async function*` (yields `tool-update` chunks, returns the result) —
+     * the same dual protocol `ToolBuilder.server` accepts.
+     */
+    handler: (input: z.infer<TInput>, ctx?: ToolCallContext) => TOutput | Promise<TOutput> | AsyncGenerator<TUpdate, TOutput, void>;
+}
+/**
+ * Identity helper that infers a capability's input type at the definition
+ * site, so its `handler` parameter is typed without an explicit annotation.
+ *
+ * @example
+ * const web = capability({
+ *   input: z.object({ query: z.string() }),
+ *   handler: async ({ query }) => search(query), // `query` is `string`
+ * })
+ */
+export declare function capability<TInput extends z.ZodType, TOutput, TUpdate = unknown>(spec: ScopedCapability<TInput, TOutput, TUpdate>): ScopedCapability<TInput, TOutput, TUpdate>;
+export interface ScopedToolOptions {
+    name: string;
+    description: string;
+    /** Discriminator field name added to the flat schema. Default `'sub_tool'`. */
+    discriminator?: string;
+    /** Named capability branches. Keys become the discriminator enum values. */
+    capabilities: Record<string, ScopedCapability>;
+    /**
+     * Runtime allowlist — restrict callable capabilities to a subset of
+     * `capabilities` keys (e.g. per-plan gating). Both the discriminator enum
+     * and the runtime dispatch honor it. Defaults to every capability key.
+     * Entries not present in `capabilities` throw at build time.
+     */
+    allow?: string[];
+    /** Forwarded to the generated tool definition. */
+    needsApproval?: ToolNeedsApproval | undefined;
+}
+/**
+ * The shared flattening plan, computed once so the JSON-Schema render and the
+ * runtime dispatch/validation cannot drift. Exported for adapters and tests.
+ */
+export interface FlatPlan {
+    discriminator: string;
+    /** Allowed discriminator values, in declaration order. */
+    values: string[];
+    /** Merged JSON-Schema properties (discriminator included). */
+    properties: Record<string, unknown>;
+    /** Top-level required = discriminator + fields required by EVERY branch. */
+    required: string[];
+    /** Per-capability required field names, for in-code validation before dispatch. */
+    requiredByCapability: Record<string, string[]>;
+    /** For each non-discriminator field, which capabilities reference it. */
+    owners: Record<string, string[]>;
+}
+/** Error thrown by a scoped tool's dispatch before any handler runs. */
+export declare class ScopedToolError extends Error {
+    readonly name = "ScopedToolError";
+    constructor(message: string);
+}
+/**
+ * Collapse N capability branches into one flat function-call plan with a
+ * discriminator enum. Function-calling APIs do not reliably honor a top-level
+ * `oneOf`, so a discriminated union must flatten to a single object schema:
+ * the union of all branches' fields, a top-level `required` containing only
+ * fields required by EVERY branch, and per-branch requireds enforced in code.
+ */
+export declare function flattenCapabilities(capabilities: Record<string, ScopedCapability>, discriminator?: string, allow?: string[]): FlatPlan;
+/**
+ * Build a single function-call tool from a discriminated union of capability
+ * branches. The branches collapse into one flat schema with a discriminator
+ * enum (see {@link flattenCapabilities}); at call time the dispatch validates
+ * the discriminator against the allowlist, validates the chosen branch's input
+ * (enforcing its required fields), and runs that branch's handler.
+ *
+ * @example
+ * const search = scopedTool({
+ *   name: 'search',
+ *   description: 'Run a search across one of several engines.',
+ *   capabilities: {
+ *     web:    capability({ input: z.object({ query: z.string() }),               handler: webSearch }),
+ *     images: capability({ input: z.object({ query: z.string(), safe: z.boolean() }), handler: imageSearch }),
+ *   },
+ * })
+ */
+export declare function scopedTool(options: ScopedToolOptions): ServerToolBuilder<Record<string, unknown>, unknown>;
+//# sourceMappingURL=scoped-tool.d.ts.map

package/dist/scoped-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-tool.d.ts","sourceRoot":"","sources":["../src/scoped-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAG7C,OAAO,KAAK,EAAE,eAAe,EAAyB,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE3F;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAC/B,MAAM,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,EACpC,OAAO,GAAG,OAAO,EACjB,OAAO,GAAG,OAAO;IAEjB,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,OAAO,EAAE,CACP,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EACtB,GAAG,CAAC,EAAE,eAAe,KAClB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAA;CACzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,EAC7E,IAAI,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,GAC/C,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAE5C;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IAC9C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,kDAAkD;IAClD,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACnC,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,mFAAmF;IACnF,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IAC9C,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;CACjC;AAED,wEAAwE;AACxE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,IAAI,qBAAoB;gBAC9B,OAAO,EAAE,MAAM;CAG5B;AAYD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC9C,aAAa,SAAa,EAC1B,KAAK,CAAC,EAAE,MAAM,EAAE,GACf,QAAQ,CA8EV;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAoD1G"}

package/dist/scoped-tool.js

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+import { ServerToolBuilder } from './tool.js';
+import { isAsyncGenerator } from './tool-helpers.js';
+import { zodToJsonSchema } from './zod-to-json-schema.js';
+/**
+ * Identity helper that infers a capability's input type at the definition
+ * site, so its `handler` parameter is typed without an explicit annotation.
+ *
+ * @example
+ * const web = capability({
+ *   input: z.object({ query: z.string() }),
+ *   handler: async ({ query }) => search(query), // `query` is `string`
+ * })
+ */
+export function capability(spec) {
+    return spec;
+}
+/** Error thrown by a scoped tool's dispatch before any handler runs. */
+export class ScopedToolError extends Error {
+    name = 'ScopedToolError';
+    constructor(message) {
+        super(message);
+    }
+}
+function jsonSchemaFor(schema) {
+    const json = zodToJsonSchema(schema, 'input');
+    const properties = (json.properties && typeof json.properties === 'object') ? json.properties : {};
+    const required = Array.isArray(json.required) ? json.required.filter((r) => typeof r === 'string') : [];
+    return { properties, required };
+}
+/**
+ * Collapse N capability branches into one flat function-call plan with a
+ * discriminator enum. Function-calling APIs do not reliably honor a top-level
+ * `oneOf`, so a discriminated union must flatten to a single object schema:
+ * the union of all branches' fields, a top-level `required` containing only
+ * fields required by EVERY branch, and per-branch requireds enforced in code.
+ */
+export function flattenCapabilities(capabilities, discriminator = 'sub_tool', allow) {
+    const keys = Object.keys(capabilities);
+    if (keys.length === 0) {
+        throw new ScopedToolError('A scoped tool needs at least one capability.');
+    }
+    const values = allow ?? keys;
+    for (const v of values) {
+        if (!(v in capabilities)) {
+            throw new ScopedToolError(`allow lists "${v}", which is not a declared capability.`);
+        }
+    }
+    if (values.length === 0) {
+        throw new ScopedToolError('A scoped tool needs at least one allowed capability.');
+    }
+    const properties = {};
+    const owners = {};
+    const requiredByCapability = {};
+    // A field is top-level required iff every allowed branch requires it. Seed
+    // with the first branch's requireds, then intersect down across the rest.
+    let requiredByAll = null;
+    for (const key of values) {
+        if (key === discriminator) {
+            throw new ScopedToolError(`Capability "${key}" collides with the discriminator field name "${discriminator}".`);
+        }
+        const { properties: props, required } = jsonSchemaFor(capabilities[key].input);
+        requiredByCapability[key] = required;
+        for (const [field, schema] of Object.entries(props)) {
+            if (field === discriminator) {
+                throw new ScopedToolError(`Capability "${key}" declares a field named "${discriminator}", which collides with the discriminator.`);
+            }
+            // First branch to declare a field owns its schema; later branches must
+            // share the field name (the model fills one flat object), so we keep the
+            // first shape and just record co-ownership for the field's note.
+            if (!(field in properties))
+                properties[field] = schema;
+            (owners[field] ??= []).push(key);
+        }
+        requiredByAll = requiredByAll === null
+            ? [...required]
+            : requiredByAll.filter(f => required.includes(f));
+    }
+    // Annotate each non-universal field with the capabilities that use it, so
+    // the model knows a field only applies to certain discriminator values.
+    for (const [field, ownerKeys] of Object.entries(owners)) {
+        if (ownerKeys.length === values.length)
+            continue; // universal — no note
+        const note = `Only for ${discriminator}: ${ownerKeys.join(', ')}.`;
+        const schema = properties[field];
+        if (schema && typeof schema === 'object') {
+            const s = schema;
+            s.description = typeof s.description === 'string' && s.description.length > 0
+                ? `${s.description} ${note}`
+                : note;
+        }
+    }
+    const descParts = values.map(k => {
+        const d = capabilities[k].description;
+        return d ? `"${k}" (${d})` : `"${k}"`;
+    });
+    properties[discriminator] = {
+        type: 'string',
+        enum: values,
+        description: `Which capability to invoke. One of: ${descParts.join(', ')}.`,
+    };
+    return {
+        discriminator,
+        values,
+        properties,
+        required: [discriminator, ...(requiredByAll ?? [])],
+        requiredByCapability,
+        owners,
+    };
+}
+/**
+ * Build a single function-call tool from a discriminated union of capability
+ * branches. The branches collapse into one flat schema with a discriminator
+ * enum (see {@link flattenCapabilities}); at call time the dispatch validates
+ * the discriminator against the allowlist, validates the chosen branch's input
+ * (enforcing its required fields), and runs that branch's handler.
+ *
+ * @example
+ * const search = scopedTool({
+ *   name: 'search',
+ *   description: 'Run a search across one of several engines.',
+ *   capabilities: {
+ *     web:    capability({ input: z.object({ query: z.string() }),               handler: webSearch }),
+ *     images: capability({ input: z.object({ query: z.string(), safe: z.boolean() }), handler: imageSearch }),
+ *   },
+ * })
+ */
+export function scopedTool(options) {
+    const discriminator = options.discriminator ?? 'sub_tool';
+    const plan = flattenCapabilities(options.capabilities, discriminator, options.allow);
+    const allowed = new Set(plan.values);
+    const jsonSchema = {
+        type: 'object',
+        properties: plan.properties,
+        required: plan.required,
+    };
+    const definition = {
+        name: options.name,
+        description: options.description,
+        // Placeholder — the wire schema is `jsonSchema`; the loop's arg validation
+        // passes the raw object through and our dispatch does per-branch checks.
+        inputSchema: z.unknown(),
+        jsonSchema,
+        ...(options.needsApproval !== undefined ? { needsApproval: options.needsApproval } : {}),
+    };
+    async function* dispatch(input, ctx) {
+        const raw = (input && typeof input === 'object') ? input : {};
+        const which = raw[discriminator];
+        if (typeof which !== 'string') {
+            throw new ScopedToolError(`Missing or non-string "${discriminator}". Expected one of: ${plan.values.join(', ')}.`);
+        }
+        if (!allowed.has(which)) {
+            throw new ScopedToolError(`Unknown ${discriminator} "${which}". Expected one of: ${plan.values.join(', ')}.`);
+        }
+        const branch = options.capabilities[which];
+        // Strip the discriminator before validating against the branch's schema —
+        // the branch never declares it, and a strict schema would reject it.
+        const { [discriminator]: _omit, ...branchInput } = raw;
+        const parsed = branch.input.safeParse(branchInput);
+        if (!parsed.success) {
+            const issues = parsed.error.issues
+                .map(i => `${i.path.map(String).join('.') || '(root)'}: ${i.message}`)
+                .join('; ');
+            throw new ScopedToolError(`Invalid arguments for ${discriminator} "${which}": ${issues}`);
+        }
+        const result = branch.handler(parsed.data, ctx);
+        if (isAsyncGenerator(result)) {
+            return yield* result;
+        }
+        return await result;
+    }
+    return new ServerToolBuilder(definition, dispatch);
+}
+//# sourceMappingURL=scoped-tool.js.map

package/dist/scoped-tool.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rudderjs/ai",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "AI engine — providers, agents, tools, streaming, middleware",
   "rudderjs": {
     "provider": "AiProvider",
@@ -87,6 +87,10 @@
     "./computer-use": {
       "import": "./dist/computer-use/index.js",
       "types": "./dist/computer-use/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts"
     }
   },
   "dependencies": {
@@ -96,8 +100,9 @@
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@rudderjs/core": "^1.13.1",
-    "@rudderjs/orm": "^1.21.2"
+    "react": ">=19.2.0",
+    "@rudderjs/orm": "^1.21.2",
+    "@rudderjs/core": "^1.13.1"
   },
   "peerDependenciesMeta": {
     "@rudderjs/core": {
@@ -108,6 +113,9 @@
     },
     "@modelcontextprotocol/sdk": {
       "optional": true
+    },
+    "react": {
+      "optional": true
     }
   },
   "optionalDependencies": {
@@ -120,6 +128,8 @@
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/node": "^20.0.0",
+    "@types/react": "^19.2.0",
+    "react": "^19.2.0",
     "typescript": "^5.4.0",
     "@rudderjs/console": "^1.4.2",
     "@rudderjs/core": "^1.13.1",