@rudderjs/ai 0.0.1

package/dist/queue-job.js

@@ -0,0 +1,82 @@
+/**
+ * Queued AI prompt builder.
+ * Created via `agent.queue('prompt')`.
+ *
+ * @example
+ * await agent.queue('Analyze this report')
+ *   .onQueue('ai')
+ *   .then(response => console.log(response.text))
+ *   .catch(err => console.error(err))
+ *   .send()
+ */
+export class QueuedPromptBuilder {
+    agentRef;
+    input;
+    options;
+    _queue = 'default';
+    _delay = 0;
+    _thenFn;
+    _catchFn;
+    constructor(agentRef, input, options) {
+        this.agentRef = agentRef;
+        this.input = input;
+        this.options = options;
+    }
+    /** Set the queue name */
+    onQueue(name) {
+        this._queue = name;
+        return this;
+    }
+    /** Set a delay before the job runs */
+    delay(ms) {
+        this._delay = ms;
+        return this;
+    }
+    /** Callback when the prompt succeeds */
+    then(fn) {
+        this._thenFn = fn;
+        return this;
+    }
+    /** Callback when the prompt fails */
+    catch(fn) {
+        this._catchFn = fn;
+        return this;
+    }
+    /** Dispatch the job to the queue */
+    async send() {
+        // Lazy import @rudderjs/queue — uses dispatch(fn) for queued closures
+        let dispatchFn;
+        try {
+            const specifier = '@rudderjs/queue';
+            const mod = await import(/* @vite-ignore */ specifier);
+            dispatchFn = mod['dispatch'];
+        }
+        catch {
+            throw new Error('[RudderJS AI] @rudderjs/queue is required for agent.queue(). Install it: pnpm add @rudderjs/queue');
+        }
+        const agentRef = this.agentRef;
+        const input = this.input;
+        const promptOptions = this.options;
+        const thenFn = this._thenFn;
+        const catchFn = this._catchFn;
+        await dispatchFn(async () => {
+            try {
+                const response = await agentRef.prompt(input, promptOptions);
+                if (thenFn)
+                    await thenFn(response);
+            }
+            catch (error) {
+                if (catchFn) {
+                    await catchFn(error);
+                }
+                else {
+                    throw error;
+                }
+            }
+        }, {
+            queue: this._queue,
+            delay: this._delay,
+        });
+    }
+}
+//# sourceMappingURL=queue-job.js.map

package/dist/queue-job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-job.js","sourceRoot":"","sources":["../src/queue-job.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,mBAAmB;IAOX;IACA;IACA;IARX,MAAM,GAAG,SAAS,CAAA;IAClB,MAAM,GAAG,CAAC,CAAA;IACV,OAAO,CAAiE;IACxE,QAAQ,CAAwD;IAExE,YACmB,QAAyF,EACzF,KAAa,EACb,OAA4B;QAF5B,aAAQ,GAAR,QAAQ,CAAiF;QACzF,UAAK,GAAL,KAAK,CAAQ;QACb,YAAO,GAAP,OAAO,CAAqB;IAC5C,CAAC;IAEJ,yBAAyB;IACzB,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,sCAAsC;IACtC,KAAK,CAAC,EAAU;QACd,IAAI,CAAC,MAAM,GAAG,EAAE,CAAA;QAChB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,wCAAwC;IACxC,IAAI,CAAC,EAAqD;QACxD,IAAI,CAAC,OAAO,GAAG,EAAE,CAAA;QACjB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,qCAAqC;IACrC,KAAK,CAAC,EAA4C;QAChD,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAA;QAClB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,oCAAoC;IACpC,KAAK,CAAC,IAAI;QACR,sEAAsE;QACtE,IAAI,UAA2G,CAAA;QAC/G,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,iBAAiB,CAAA;YACnC,MAAM,GAAG,GAA4B,MAAM,MAAM,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAA;YAC/E,UAAU,GAAG,GAAG,CAAC,UAAU,CAAsB,CAAA;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CACb,mGAAmG,CACpG,CAAA;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;QACxB,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAA;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAA;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAA;QAE7B,MAAM,UAAU,CAAC,KAAK,IAAI,EAAE;YAC1B,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAA;gBAC5D,IAAI,MAAM;oBAAE,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAA;YACpC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,OAAO,EAAE,CAAC;oBACZ,MAAM,OAAO,CAAC,KAAK,CAAC,CAAA;gBACtB,CAAC;qBAAM,CAAC;oBACN,MAAM,KAAK,CAAA;gBACb,CAAC;YACH,CAAC;QACH,CAAC,EAAE;YACD,KAAK,EAAE,IAAI,CAAC,MAAM;YAClB,KAAK,EAAE,IAAI,CAAC,MAAM;SACnB,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/registry.d.ts

@@ -0,0 +1,25 @@
+import type { AiModelConfig, ProviderFactory, ProviderAdapter } from './types.js';
+export declare class AiRegistry {
+    private static readonly factories;
+    private static _default;
+    private static _models;
+    /** Register a provider factory */
+    static register(factory: ProviderFactory): void;
+    /** Get a registered provider factory by name */
+    static getFactory(name: string): ProviderFactory;
+    /** Set the default provider/model string */
+    static setDefault(modelString: string): void;
+    /** Get the default provider/model string */
+    static getDefault(): string;
+    /** Parse 'provider/model' string into [providerName, modelId] */
+    static parseModelString(modelString: string): [string, string];
+    /** Resolve a provider/model string to a ProviderAdapter */
+    static resolve(modelString: string): ProviderAdapter;
+    /** Set available models for user selection */
+    static setModels(models: AiModelConfig[]): void;
+    /** Get available models */
+    static getModels(): AiModelConfig[];
+    /** @internal — reset for testing */
+    static reset(): void;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjF,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAqC;IACtE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAsB;IAC7C,OAAO,CAAC,MAAM,CAAC,OAAO,CAAsB;IAE5C,kCAAkC;IAClC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAI/C,gDAAgD;IAChD,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe;IAMhD,4CAA4C;IAC5C,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAI5C,4CAA4C;IAC5C,MAAM,CAAC,UAAU,IAAI,MAAM;IAK3B,iEAAiE;IACjE,MAAM,CAAC,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAM9D,2DAA2D;IAC3D,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe;IAMpD,8CAA8C;IAC9C,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI;IAI/C,2BAA2B;IAC3B,MAAM,CAAC,SAAS,IAAI,aAAa,EAAE;IAInC,oCAAoC;IACpC,MAAM,CAAC,KAAK,IAAI,IAAI;CAKrB"}

package/dist/registry.js

@@ -0,0 +1,54 @@
+export class AiRegistry {
+    static factories = new Map();
+    static _default = null;
+    static _models = [];
+    /** Register a provider factory */
+    static register(factory) {
+        this.factories.set(factory.name, factory);
+    }
+    /** Get a registered provider factory by name */
+    static getFactory(name) {
+        const f = this.factories.get(name);
+        if (!f)
+            throw new Error(`[RudderJS AI] Unknown AI provider "${name}". Register it first.`);
+        return f;
+    }
+    /** Set the default provider/model string */
+    static setDefault(modelString) {
+        this._default = modelString;
+    }
+    /** Get the default provider/model string */
+    static getDefault() {
+        if (!this._default)
+            throw new Error('[RudderJS AI] No default model set. Add ai() to providers with a config.');
+        return this._default;
+    }
+    /** Parse 'provider/model' string into [providerName, modelId] */
+    static parseModelString(modelString) {
+        const slash = modelString.indexOf('/');
+        if (slash === -1)
+            throw new Error(`[RudderJS AI] Invalid model string "${modelString}". Expected "provider/model" format.`);
+        return [modelString.slice(0, slash), modelString.slice(slash + 1)];
+    }
+    /** Resolve a provider/model string to a ProviderAdapter */
+    static resolve(modelString) {
+        const [providerName, model] = this.parseModelString(modelString);
+        const factory = this.getFactory(providerName);
+        return factory.create(model);
+    }
+    /** Set available models for user selection */
+    static setModels(models) {
+        this._models = models;
+    }
+    /** Get available models */
+    static getModels() {
+        return this._models;
+    }
+    /** @internal — reset for testing */
+    static reset() {
+        this.factories.clear();
+        this._default = null;
+        this._models = [];
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,UAAU;IACb,MAAM,CAAU,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAA;IAC9D,MAAM,CAAC,QAAQ,GAAkB,IAAI,CAAA;IACrC,MAAM,CAAC,OAAO,GAAoB,EAAE,CAAA;IAE5C,kCAAkC;IAClC,MAAM,CAAC,QAAQ,CAAC,OAAwB;QACtC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IAC3C,CAAC;IAED,gDAAgD;IAChD,MAAM,CAAC,UAAU,CAAC,IAAY;QAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAClC,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,uBAAuB,CAAC,CAAA;QAC1F,OAAO,CAAC,CAAA;IACV,CAAC;IAED,4CAA4C;IAC5C,MAAM,CAAC,UAAU,CAAC,WAAmB;QACnC,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAA;IAC7B,CAAC;IAED,4CAA4C;IAC5C,MAAM,CAAC,UAAU;QACf,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAA;QAC/G,OAAO,IAAI,CAAC,QAAQ,CAAA;IACtB,CAAC;IAED,iEAAiE;IACjE,MAAM,CAAC,gBAAgB,CAAC,WAAmB;QACzC,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QACtC,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,WAAW,sCAAsC,CAAC,CAAA;QAC3H,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAA;IACpE,CAAC;IAED,2DAA2D;IAC3D,MAAM,CAAC,OAAO,CAAC,WAAmB;QAChC,MAAM,CAAC,YAAY,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAA;QAChE,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAA;QAC7C,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC9B,CAAC;IAED,8CAA8C;IAC9C,MAAM,CAAC,SAAS,CAAC,MAAuB;QACtC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED,2BAA2B;IAC3B,MAAM,CAAC,SAAS;QACd,OAAO,IAAI,CAAC,OAAO,CAAA;IACrB,CAAC;IAED,oCAAoC;IACpC,MAAM,CAAC,KAAK;QACV,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAA;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAA;QACpB,IAAI,CAAC,OAAO,GAAG,EAAE,CAAA;IACnB,CAAC"}

package/dist/tool.d.ts

@@ -0,0 +1,157 @@
+import type { z } from 'zod';
+import type { Tool, ToolCall, ToolCallContext, ToolDefinitionOptions, ToolDefinitionSchema, ToolExecuteFn } from './types.js';
+/**
+ * Control chunk a server tool can `yield` from an `async function*`
+ * execute to pause the enclosing agent loop and surface a set of CLIENT
+ * tool calls to the caller — as if the model itself had emitted them.
+ *
+ * This is the sanctioned way for a server tool to inject client-tool
+ * calls into the parent loop's pending list. The agent loop iterating
+ * the execute generator recognizes the shape via the reserved `__rudderjs`
+ * discriminator, appends `toolCalls` to the parent's
+ * `pendingClientToolCalls`, sets the stop-for-client-tools flag, and —
+ * critically — does NOT push an error tool_result / tool message for the
+ * yielding tool call. The yielding tool's own call remains orphaned in
+ * the parent's message history until the caller resolves it on
+ * continuation (typically by computing a final result from whatever the
+ * client-side tool execution returned).
+ *
+ * Why a yield instead of a throw:
+ * - Symmetry with the existing `tool-update` yield protocol — no parallel
+ *   catch-based control path.
+ * - Middleware can observe pauses through `runOnChunk`; a thrown error
+ *   would route through `onError` and muddle telemetry.
+ * - Exceptions signal "something went wrong"; this is not an error.
+ * - Platform-level feature: any server tool can yield this, not just
+ *   nested agent runners. E.g., a tool that wants the browser's
+ *   geolocation, clipboard, or a user file upload.
+ *
+ * **Primary use case today:** nested agent runners (`run_agent` in
+ * panels). A runner that streams a sub-agent server-side can hit a pause
+ * point when the sub-agent's model calls a client tool. Those calls have
+ * to execute in the browser, not server-side, so the parent loop must
+ * surface them to its own caller.
+ *
+ * Tools that yield this chunk are responsible for persisting any state
+ * they need to resume the inner work on continuation (usually in a cache
+ * or runStore). `@rudderjs/ai` does not know or care about that state —
+ * it just propagates the pause. The optional `resumeHandle` is an opaque
+ * string the tool author owns; the agent loop never inspects it.
+ *
+ * Tool authors should construct this via {@link pauseForClientTools},
+ * not by hand, so future shape changes stay source-compatible.
+ */
+export interface PauseForClientToolsChunk {
+    /** Reserved discriminator. Namespaced to avoid colliding with user data. */
+    readonly __rudderjs: 'pause_for_client_tools';
+    readonly toolCalls: ToolCall[];
+    readonly resumeHandle?: string;
+}
+/**
+ * Construct a pause control chunk for `yield`ing from a server tool's
+ * async-generator execute.
+ *
+ * @example
+ * .server(async function* (input, ctx) {
+ *   const subRunId = await persistSubRunState(...)
+ *   yield pauseForClientTools(subAgentPending, subRunId)
+ *   // Unreachable — the loop halts iteration after the pause chunk.
+ *   return undefined as never
+ * })
+ */
+export declare function pauseForClientTools(toolCalls: ToolCall[], resumeHandle?: string): PauseForClientToolsChunk;
+/**
+ * Structural typeguard for a pause chunk. Used by the agent loop to
+ * detect pauses mid-execute without requiring tool authors to import any
+ * `@rudderjs/ai` symbol at the yield site — they can yield via
+ * {@link pauseForClientTools} or construct the object literal directly.
+ */
+export declare function isPauseForClientToolsChunk(value: unknown): value is PauseForClientToolsChunk;
+/**
+ * Builder returned by {@link toolDefinition}. The builder itself is a valid
+ * `Tool` — call `.server(execute)` to attach a server-side handler, or use
+ * the builder as-is to register a client tool (no `execute`).
+ */
+export declare class ToolBuilder<TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType = z.ZodType> implements Tool<z.infer<TInput>, never> {
+    readonly options: ToolDefinitionOptions<TInput, TOutput>;
+    readonly definition: ToolDefinitionOptions;
+    /** Builders are valid client tools — `execute` is intentionally absent. */
+    readonly execute?: undefined;
+    constructor(options: ToolDefinitionOptions<TInput, TOutput>);
+    /**
+     * Attach a server-side handler.
+     *
+     * The handler may be a regular async function (single return value) or an
+     * async generator (`async function*`). Generators can `yield` preliminary
+     * progress payloads — each yield surfaces as a `tool-update` stream chunk
+     * while the tool runs. The generator's `return` value becomes the final
+     * tool result. The same tool definition works in both `agent.prompt()`
+     * (yields are silently drained) and `agent.stream()`.
+     */
+    server<TReturn = unknown, TUpdate = unknown>(execute: (input: z.infer<TInput>, ctx?: ToolCallContext) => AsyncGenerator<TUpdate, TReturn, void>): ServerToolBuilder<z.infer<TInput>, TReturn>;
+    server<TReturn = unknown>(execute: (input: z.infer<TInput>, ctx?: ToolCallContext) => TReturn | Promise<TReturn>): ServerToolBuilder<z.infer<TInput>, TReturn>;
+    /** Convert to provider-friendly JSON Schema format */
+    toSchema(): ToolDefinitionSchema;
+}
+/**
+ * Builder returned by {@link ToolBuilder.server}. Itself a valid `Tool`, so
+ * it can be passed directly into `tools()` arrays — `.toModelOutput(...)` is
+ * an optional chained refinement, not a required `.build()` step.
+ *
+ * Future per-tool refinements (`.onError(...)`, `.middleware(...)`) would slot
+ * in here in the same chained-builder style.
+ */
+export declare class ServerToolBuilder<TInput = unknown, TOutput = unknown> implements Tool<TInput, TOutput> {
+    readonly definition: ToolDefinitionOptions;
+    readonly execute: ToolExecuteFn<TInput, TOutput, unknown>;
+    readonly toModelOutput?: ((result: TOutput) => string | Promise<string>) | undefined;
+    constructor(definition: ToolDefinitionOptions, execute: ToolExecuteFn<TInput, TOutput, unknown>, toModelOutput?: (result: TOutput) => string | Promise<string>);
+    /**
+     * Declare a transform from this tool's structured result to the string the
+     * **model** sees on its next step. The UI continues to receive the original
+     * structured result.
+     *
+     * @example
+     * toolDefinition({...})
+     *   .server(async (input) => bigStructuredResult)
+     *   .modelOutput((result) => `${result.items.length} items found`)
+     */
+    modelOutput(fn: (result: TOutput) => string | Promise<string>): ServerToolBuilder<TInput, TOutput>;
+}
+/**
+ * Define a tool with typed input/output schemas.
+ *
+ * @example  Server tool
+ * const weatherTool = toolDefinition({
+ *   name: 'get_weather',
+ *   description: 'Get weather for a location',
+ *   inputSchema: z.object({ location: z.string() }),
+ * }).server(async ({ location }) => ({ temp: 72, unit: 'F' }))
+ *
+ * @example  Client tool (no `.server()`)
+ * const readFormStateTool = toolDefinition({
+ *   name: 'read_form_state',
+ *   description: 'Read the user\'s current local form values.',
+ *   inputSchema: z.object({ fields: z.array(z.string()).optional() }),
+ * })
+ */
+export declare function toolDefinition<TInput extends z.ZodType, TOutput extends z.ZodType = z.ZodUndefined>(options: ToolDefinitionOptions<TInput, TOutput>): ToolBuilder<TInput, TOutput>;
+/**
+ * Build a tool whose input/output types are not known at compile time.
+ *
+ * Use this when the tool's schema is constructed dynamically from user data
+ * (e.g. a resource agent that exposes one tool per agent definition).
+ *
+ * @example
+ * const t = dynamicTool({
+ *   name: agentDef.slug,
+ *   description: agentDef.description,
+ *   inputSchema: z.object({}),
+ * }).server(async () => agentDef.run())
+ */
+export declare function dynamicTool(options: ToolDefinitionOptions): ToolBuilder;
+/** Convert any Tool to a ToolDefinitionSchema for provider consumption */
+export declare function toolToSchema(tool: {
+    definition: ToolDefinitionOptions;
+}): ToolDefinitionSchema;
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

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

package/dist/tool.js

@@ -0,0 +1,134 @@
+import { zodToJsonSchema } from './zod-to-json-schema.js';
+/**
+ * Construct a pause control chunk for `yield`ing from a server tool's
+ * async-generator execute.
+ *
+ * @example
+ * .server(async function* (input, ctx) {
+ *   const subRunId = await persistSubRunState(...)
+ *   yield pauseForClientTools(subAgentPending, subRunId)
+ *   // Unreachable — the loop halts iteration after the pause chunk.
+ *   return undefined as never
+ * })
+ */
+export function pauseForClientTools(toolCalls, resumeHandle) {
+    const chunk = resumeHandle !== undefined
+        ? { __rudderjs: 'pause_for_client_tools', toolCalls, resumeHandle }
+        : { __rudderjs: 'pause_for_client_tools', toolCalls };
+    return chunk;
+}
+/**
+ * Structural typeguard for a pause chunk. Used by the agent loop to
+ * detect pauses mid-execute without requiring tool authors to import any
+ * `@rudderjs/ai` symbol at the yield site — they can yield via
+ * {@link pauseForClientTools} or construct the object literal directly.
+ */
+export function isPauseForClientToolsChunk(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    return v.__rudderjs === 'pause_for_client_tools' && Array.isArray(v.toolCalls);
+}
+/**
+ * Builder returned by {@link toolDefinition}. The builder itself is a valid
+ * `Tool` — call `.server(execute)` to attach a server-side handler, or use
+ * the builder as-is to register a client tool (no `execute`).
+ */
+export class ToolBuilder {
+    options;
+    definition;
+    /** Builders are valid client tools — `execute` is intentionally absent. */
+    execute;
+    constructor(options) {
+        this.options = options;
+        this.definition = options;
+    }
+    server(execute) {
+        return new ServerToolBuilder(this.options, execute);
+    }
+    /** Convert to provider-friendly JSON Schema format */
+    toSchema() {
+        return {
+            name: this.options.name,
+            description: this.options.description,
+            parameters: zodToJsonSchema(this.options.inputSchema),
+        };
+    }
+}
+/**
+ * Builder returned by {@link ToolBuilder.server}. Itself a valid `Tool`, so
+ * it can be passed directly into `tools()` arrays — `.toModelOutput(...)` is
+ * an optional chained refinement, not a required `.build()` step.
+ *
+ * Future per-tool refinements (`.onError(...)`, `.middleware(...)`) would slot
+ * in here in the same chained-builder style.
+ */
+export class ServerToolBuilder {
+    definition;
+    execute;
+    toModelOutput;
+    constructor(definition, execute, toModelOutput) {
+        this.definition = definition;
+        this.execute = execute;
+        if (toModelOutput)
+            this.toModelOutput = toModelOutput;
+    }
+    /**
+     * Declare a transform from this tool's structured result to the string the
+     * **model** sees on its next step. The UI continues to receive the original
+     * structured result.
+     *
+     * @example
+     * toolDefinition({...})
+     *   .server(async (input) => bigStructuredResult)
+     *   .modelOutput((result) => `${result.items.length} items found`)
+     */
+    modelOutput(fn) {
+        return new ServerToolBuilder(this.definition, this.execute, fn);
+    }
+}
+/**
+ * Define a tool with typed input/output schemas.
+ *
+ * @example  Server tool
+ * const weatherTool = toolDefinition({
+ *   name: 'get_weather',
+ *   description: 'Get weather for a location',
+ *   inputSchema: z.object({ location: z.string() }),
+ * }).server(async ({ location }) => ({ temp: 72, unit: 'F' }))
+ *
+ * @example  Client tool (no `.server()`)
+ * const readFormStateTool = toolDefinition({
+ *   name: 'read_form_state',
+ *   description: 'Read the user\'s current local form values.',
+ *   inputSchema: z.object({ fields: z.array(z.string()).optional() }),
+ * })
+ */
+export function toolDefinition(options) {
+    return new ToolBuilder(options);
+}
+/**
+ * Build a tool whose input/output types are not known at compile time.
+ *
+ * Use this when the tool's schema is constructed dynamically from user data
+ * (e.g. a resource agent that exposes one tool per agent definition).
+ *
+ * @example
+ * const t = dynamicTool({
+ *   name: agentDef.slug,
+ *   description: agentDef.description,
+ *   inputSchema: z.object({}),
+ * }).server(async () => agentDef.run())
+ */
+export function dynamicTool(options) {
+    return new ToolBuilder(options);
+}
+/** Convert any Tool to a ToolDefinitionSchema for provider consumption */
+export function toolToSchema(tool) {
+    return {
+        name: tool.definition.name,
+        description: tool.definition.description,
+        parameters: zodToJsonSchema(tool.definition.inputSchema),
+    };
+}
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AA4DzD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAqB,EACrB,YAAqB;IAErB,MAAM,KAAK,GAA6B,YAAY,KAAK,SAAS;QAChE,CAAC,CAAC,EAAE,UAAU,EAAE,wBAAwB,EAAE,SAAS,EAAE,YAAY,EAAE;QACnE,CAAC,CAAC,EAAE,UAAU,EAAE,wBAAwB,EAAE,SAAS,EAAE,CAAA;IACvD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC7D,MAAM,CAAC,GAAG,KAAsD,CAAA;IAChE,OAAO,CAAC,CAAC,UAAU,KAAK,wBAAwB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,WAAW;IAIb,OAAO,CAAwC;IAC/C,UAAU,CAAuB;IAE1C,2EAA2E;IAClE,OAAO,CAAY;IAE5B,YAAY,OAA+C;QACzD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,CAAC,UAAU,GAAG,OAA2C,CAAA;IAC/D,CAAC;IAyBD,MAAM,CACJ,OAAyD;QAEzD,OAAO,IAAI,iBAAiB,CAC1B,IAAI,CAAC,OAA2C,EAChD,OAA2D,CAC5D,CAAA;IACH,CAAC;IAED,sDAAsD;IACtD,QAAQ;QACN,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;YACvB,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW;YACrC,UAAU,EAAE,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;SACtD,CAAA;IACH,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAiB;IAGnB,UAAU,CAAuB;IACjC,OAAO,CAAyC;IAChD,aAAa,CAA8D;IAEpF,YACE,UAAiC,EACjC,OAAgD,EAChD,aAA6D;QAE7D,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,aAAa;YAAE,IAAI,CAAC,aAAa,GAAG,aAAa,CAAA;IACvD,CAAC;IAED;;;;;;;;;OASG;IACH,WAAW,CACT,EAAiD;QAEjD,OAAO,IAAI,iBAAiB,CAAkB,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;IAClF,CAAC;CACF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAG5B,OAA+C;IAC/C,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,CAAA;AACjC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,OAA8B;IAE9B,OAAO,IAAI,WAAW,CAAC,OAAsD,CAAC,CAAA;AAChF,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,YAAY,CAAC,IAA2C;IACtE,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI;QAC1B,WAAW,EAAE,IAAI,CAAC,UAAU,CAAC,WAAW;QACxC,UAAU,EAAE,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;KACzD,CAAA;AACH,CAAC"}

package/dist/transcription.d.ts

@@ -0,0 +1,28 @@
+import type { SpeechToTextResult } from './types.js';
+/**
+ * Fluent builder for speech-to-text transcription.
+ *
+ * @example
+ * const result = await Transcription.fromPath('./audio.mp3').generate()
+ * const result = await Transcription.fromBuffer(buf).language('en').generate()
+ */
+export declare class Transcription {
+    private readonly _audio;
+    private _model?;
+    private _language?;
+    private _prompt?;
+    private constructor();
+    /** Create a Transcription from a file path */
+    static fromPath(path: string): Transcription;
+    /** Create a Transcription from a Buffer */
+    static fromBuffer(buffer: Buffer): Transcription;
+    /** Set the STT model (e.g. 'openai/whisper-1') */
+    model(m: string): this;
+    /** Set the language hint (ISO-639-1, e.g. 'en', 'es', 'fr') */
+    language(l: string): this;
+    /** Set an optional prompt to guide transcription style */
+    prompt(p: string): this;
+    /** Run the transcription */
+    generate(): Promise<SpeechToTextResult>;
+}
+//# sourceMappingURL=transcription.d.ts.map

package/dist/transcription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcription.d.ts","sourceRoot":"","sources":["../src/transcription.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD;;;;;;GAMG;AACH,qBAAa,aAAa;IAKJ,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJ3C,OAAO,CAAC,MAAM,CAAC,CAAQ;IACvB,OAAO,CAAC,SAAS,CAAC,CAAQ;IAC1B,OAAO,CAAC,OAAO,CAAC,CAAQ;IAExB,OAAO;IAEP,8CAA8C;IAC9C,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAI5C,2CAA2C;IAC3C,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa;IAIhD,kDAAkD;IAClD,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKtB,+DAA+D;IAC/D,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKzB,0DAA0D;IAC1D,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKvB,4BAA4B;IACtB,QAAQ,IAAI,OAAO,CAAC,kBAAkB,CAAC;CAyB9C"}

package/dist/transcription.js

@@ -0,0 +1,63 @@
+import { readFileSync } from 'node:fs';
+import { AiRegistry } from './registry.js';
+/**
+ * Fluent builder for speech-to-text transcription.
+ *
+ * @example
+ * const result = await Transcription.fromPath('./audio.mp3').generate()
+ * const result = await Transcription.fromBuffer(buf).language('en').generate()
+ */
+export class Transcription {
+    _audio;
+    _model;
+    _language;
+    _prompt;
+    constructor(_audio) {
+        this._audio = _audio;
+    }
+    /** Create a Transcription from a file path */
+    static fromPath(path) {
+        return new Transcription(path);
+    }
+    /** Create a Transcription from a Buffer */
+    static fromBuffer(buffer) {
+        return new Transcription(buffer);
+    }
+    /** Set the STT model (e.g. 'openai/whisper-1') */
+    model(m) {
+        this._model = m;
+        return this;
+    }
+    /** Set the language hint (ISO-639-1, e.g. 'en', 'es', 'fr') */
+    language(l) {
+        this._language = l;
+        return this;
+    }
+    /** Set an optional prompt to guide transcription style */
+    prompt(p) {
+        this._prompt = p;
+        return this;
+    }
+    /** Run the transcription */
+    async generate() {
+        const modelString = this._model ?? AiRegistry.getDefault();
+        const [providerName, modelId] = AiRegistry.parseModelString(modelString);
+        const factory = AiRegistry.getFactory(providerName);
+        if (!factory.createStt) {
+            throw new Error(`[RudderJS AI] Provider "${providerName}" does not support speech-to-text. ` +
+                `Use a provider that implements createStt() (e.g. openai).`);
+        }
+        // Resolve audio: if string (path), read into Buffer
+        const audioBuffer = typeof this._audio === 'string'
+            ? readFileSync(this._audio)
+            : this._audio;
+        const adapter = factory.createStt(modelId);
+        return adapter.transcribe({
+            audio: audioBuffer,
+            model: modelId,
+            language: this._language,
+            prompt: this._prompt,
+        });
+    }
+}
+//# sourceMappingURL=transcription.js.map

package/dist/transcription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcription.js","sourceRoot":"","sources":["../src/transcription.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAG1C;;;;;;GAMG;AACH,MAAM,OAAO,aAAa;IAKa;IAJ7B,MAAM,CAAS;IACf,SAAS,CAAS;IAClB,OAAO,CAAS;IAExB,YAAqC,MAAuB;QAAvB,WAAM,GAAN,MAAM,CAAiB;IAAG,CAAC;IAEhE,8CAA8C;IAC9C,MAAM,CAAC,QAAQ,CAAC,IAAY;QAC1B,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,CAAA;IAChC,CAAC;IAED,2CAA2C;IAC3C,MAAM,CAAC,UAAU,CAAC,MAAc;QAC9B,OAAO,IAAI,aAAa,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IAED,kDAAkD;IAClD,KAAK,CAAC,CAAS;QACb,IAAI,CAAC,MAAM,GAAG,CAAC,CAAA;QACf,OAAO,IAAI,CAAA;IACb,CAAC;IAED,+DAA+D;IAC/D,QAAQ,CAAC,CAAS;QAChB,IAAI,CAAC,SAAS,GAAG,CAAC,CAAA;QAClB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,0DAA0D;IAC1D,MAAM,CAAC,CAAS;QACd,IAAI,CAAC,OAAO,GAAG,CAAC,CAAA;QAChB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,4BAA4B;IAC5B,KAAK,CAAC,QAAQ;QACZ,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,CAAC,UAAU,EAAE,CAAA;QAC1D,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,GAAG,UAAU,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAA;QACxE,MAAM,OAAO,GAAG,UAAU,CAAC,UAAU,CAAC,YAAY,CAAC,CAAA;QAEnD,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,2BAA2B,YAAY,qCAAqC;gBAC5E,2DAA2D,CAC5D,CAAA;QACH,CAAC;QAED,oDAAoD;QACpD,MAAM,WAAW,GAAG,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ;YACjD,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC;YAC3B,CAAC,CAAC,IAAI,CAAC,MAAM,CAAA;QAEf,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QAC1C,OAAO,OAAO,CAAC,UAAU,CAAC;YACxB,KAAK,EAAE,WAAW;YAClB,KAAK,EAAE,OAAO;YACd,QAAQ,EAAE,IAAI,CAAC,SAAS;YACxB,MAAM,EAAE,IAAI,CAAC,OAAO;SACrB,CAAC,CAAA;IACJ,CAAC;CACF"}