vovk 3.5.1 → 3.7.0

package/dist/tools/create-tool-factory.d.ts

@@ -0,0 +1,135 @@
+import type { VovkValidationType } from '../types/core.js';
+import type { VovkTool } from '../types/tools.js';
+import type { DefaultModelOutput, ToModelOutputDefaultFn } from './to-model-output-default.js';
+import type { CombinedSpec } from '../types/validation.js';
+import type { KnownAny } from '../types/utils.js';
+type InferFormattedOutput<TFn, TOutput> = TFn extends ToModelOutputDefaultFn ? DefaultModelOutput<TOutput> : TFn extends (...args: KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown;
+type AnyToModelOutputFn = (...args: KnownAny[]) => KnownAny;
+export declare function createToolFactory({ toJSONSchema, }: {
+    toJSONSchema: (model: KnownAny, meta: {
+        validationType: VovkValidationType;
+        target: CombinedSpec.Target | undefined;
+    }) => KnownAny;
+}): {
+    <TInput, TOutput, TToModelOutput extends AnyToModelOutputFn>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: VovkTool<TInput, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: VovkTool<TInput, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>) => void) | undefined;
+        target?: CombinedSpec.Target;
+    } & {
+        inputSchema: CombinedSpec<TInput, TInput>;
+    } & {
+        outputSchema: CombinedSpec<TOutput, TOutput>;
+    } & {
+        execute: (input: TInput, processingMeta?: KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput: TToModelOutput;
+    }): VovkTool<TInput, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>;
+    <TInput, TOutput>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: VovkTool<TInput, TOutput, DefaultModelOutput<TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: VovkTool<TInput, TOutput, DefaultModelOutput<TOutput>>) => void) | undefined;
+        target?: CombinedSpec.Target;
+    } & {
+        inputSchema: CombinedSpec<TInput, TInput>;
+    } & {
+        outputSchema: CombinedSpec<TOutput, TOutput>;
+    } & {
+        execute: (input: TInput, processingMeta?: KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput?: undefined;
+    }): VovkTool<TInput, TOutput, DefaultModelOutput<TOutput>>;
+    <TInput, TOutput, TToModelOutput extends AnyToModelOutputFn>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: VovkTool<TInput, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: VovkTool<TInput, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>) => void) | undefined;
+        target?: CombinedSpec.Target;
+    } & {
+        inputSchema: CombinedSpec<TInput, TInput>;
+    } & {
+        outputSchema?: undefined;
+    } & {
+        execute: (input: TInput, processingMeta?: KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput: TToModelOutput;
+    }): VovkTool<TInput, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>;
+    <TInput, TOutput>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: VovkTool<TInput, TOutput, DefaultModelOutput<TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: VovkTool<TInput, TOutput, DefaultModelOutput<TOutput>>) => void) | undefined;
+        target?: CombinedSpec.Target;
+    } & {
+        inputSchema: CombinedSpec<TInput, TInput>;
+    } & {
+        outputSchema?: undefined;
+    } & {
+        execute: (input: TInput, processingMeta?: KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput?: undefined;
+    }): VovkTool<TInput, TOutput, DefaultModelOutput<TOutput>>;
+    <TOutput, TToModelOutput extends AnyToModelOutputFn>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: VovkTool<null, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: VovkTool<null, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>) => void) | undefined;
+        target?: CombinedSpec.Target;
+    } & {
+        inputSchema?: undefined;
+    } & {
+        outputSchema: CombinedSpec<TOutput, TOutput>;
+    } & {
+        execute: (input: null, processingMeta?: KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput: TToModelOutput;
+    }): VovkTool<null, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>;
+    <TOutput>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: VovkTool<null, TOutput, DefaultModelOutput<TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: VovkTool<null, TOutput, DefaultModelOutput<TOutput>>) => void) | undefined;
+        target?: CombinedSpec.Target;
+    } & {
+        inputSchema?: undefined;
+    } & {
+        outputSchema: CombinedSpec<TOutput, TOutput>;
+    } & {
+        execute: (input: null, processingMeta?: KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput?: undefined;
+    }): VovkTool<null, TOutput, DefaultModelOutput<TOutput>>;
+    <TOutput, TToModelOutput extends AnyToModelOutputFn>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: VovkTool<null, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: VovkTool<null, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>) => void) | undefined;
+        target?: CombinedSpec.Target;
+    } & {
+        inputSchema?: undefined;
+    } & {
+        outputSchema?: undefined;
+    } & {
+        execute: (input: null, processingMeta?: KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput: TToModelOutput;
+    }): VovkTool<null, TOutput, InferFormattedOutput<TToModelOutput, TOutput>>;
+    <TOutput>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: VovkTool<null, TOutput, DefaultModelOutput<TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: VovkTool<null, TOutput, DefaultModelOutput<TOutput>>) => void) | undefined;
+        target?: CombinedSpec.Target;
+    } & {
+        inputSchema?: undefined;
+    } & {
+        outputSchema?: undefined;
+    } & {
+        execute: (input: null, processingMeta?: KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput?: undefined;
+    }): VovkTool<null, TOutput, DefaultModelOutput<TOutput>>;
+};
+export {};

package/dist/tools/create-tool-factory.js

@@ -0,0 +1,62 @@
+import { ToModelOutput } from './to-model-output.js';
+export function createToolFactory({ toJSONSchema, }) {
+    // Implementation
+    function createTool({ name, title, description, toModelOutput = ToModelOutput.DEFAULT, onExecute, onError, inputSchema, outputSchema, execute, target, }) {
+        let parameters;
+        const tool = {
+            type: 'function',
+            name,
+            title,
+            description,
+            get parameters() {
+                // biome-ignore lint/suspicious/noAssignInExpressions: TODO
+                return (parameters ??= inputSchema ? toJSONSchema(inputSchema, { validationType: 'tool-input', target }) : {});
+            },
+            inputSchema: inputSchema,
+            outputSchema: outputSchema,
+            inputSchemas: undefined,
+            async execute(input, processingMeta) {
+                let result;
+                try {
+                    let validatedInput;
+                    if (inputSchema) {
+                        const validatedInputResult = await inputSchema['~standard'].validate(input);
+                        if (validatedInputResult.issues?.length) {
+                            throw new Error(`Input validation failed. ${validatedInputResult.issues
+                                .map(({ message, path }) => `${message}${path ? ` at ${path.join('.')}` : ''}`)
+                                .join(', ')}`);
+                        }
+                        validatedInput = validatedInputResult.value;
+                    }
+                    else {
+                        validatedInput = null;
+                    }
+                    result = await execute(validatedInput, processingMeta);
+                    if (outputSchema) {
+                        const validatedOutputResult = await outputSchema['~standard'].validate(result);
+                        if (validatedOutputResult.issues?.length) {
+                            throw new Error(`Output validation failed. ${validatedOutputResult.issues
+                                .map(({ message, path }) => `${message}${path ? ` at ${path.join('.')}` : ''}`)
+                                .join(', ')}`);
+                        }
+                        result = validatedOutputResult.value;
+                    }
+                    onExecute?.(result, tool);
+                }
+                catch (e) {
+                    onError?.(e, tool);
+                    result = e;
+                }
+                if (result instanceof Error) {
+                    result.toJSON = () => ({
+                        isError: true,
+                        message: result.message,
+                    });
+                }
+                return toModelOutput(result, tool, null);
+            },
+        };
+        return tool;
+    }
+    return createTool;
+}

package/dist/tools/create-tool.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Function to create a standalone AI tool.
+ * @see https://vovk.dev/tools
+ */
+export declare const createTool: {
+    <TInput, TOutput, TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => import("../types/utils.js").KnownAny>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: import("../index.js").VovkTool<TInput, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>) => void) | undefined;
+        onError?: ((error: Error, tool: import("../index.js").VovkTool<TInput, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>) => void) | undefined;
+        target?: import("../types/validation.js").CombinedSpec.Target;
+    } & {
+        inputSchema: import("../types/validation.js").CombinedSpec<TInput, TInput>;
+    } & {
+        outputSchema: import("../types/validation.js").CombinedSpec<TOutput, TOutput>;
+    } & {
+        execute: (input: TInput, processingMeta?: import("../types/utils.js").KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput: TToModelOutput;
+    }): import("../index.js").VovkTool<TInput, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>;
+    <TInput, TOutput>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: import("../index.js").VovkTool<TInput, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: import("../index.js").VovkTool<TInput, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>) => void) | undefined;
+        target?: import("../types/validation.js").CombinedSpec.Target;
+    } & {
+        inputSchema: import("../types/validation.js").CombinedSpec<TInput, TInput>;
+    } & {
+        outputSchema: import("../types/validation.js").CombinedSpec<TOutput, TOutput>;
+    } & {
+        execute: (input: TInput, processingMeta?: import("../types/utils.js").KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput?: undefined;
+    }): import("../index.js").VovkTool<TInput, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>;
+    <TInput, TOutput, TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => import("../types/utils.js").KnownAny>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: import("../index.js").VovkTool<TInput, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>) => void) | undefined;
+        onError?: ((error: Error, tool: import("../index.js").VovkTool<TInput, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>) => void) | undefined;
+        target?: import("../types/validation.js").CombinedSpec.Target;
+    } & {
+        inputSchema: import("../types/validation.js").CombinedSpec<TInput, TInput>;
+    } & {
+        outputSchema?: undefined;
+    } & {
+        execute: (input: TInput, processingMeta?: import("../types/utils.js").KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput: TToModelOutput;
+    }): import("../index.js").VovkTool<TInput, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>;
+    <TInput, TOutput>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: import("../index.js").VovkTool<TInput, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: import("../index.js").VovkTool<TInput, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>) => void) | undefined;
+        target?: import("../types/validation.js").CombinedSpec.Target;
+    } & {
+        inputSchema: import("../types/validation.js").CombinedSpec<TInput, TInput>;
+    } & {
+        outputSchema?: undefined;
+    } & {
+        execute: (input: TInput, processingMeta?: import("../types/utils.js").KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput?: undefined;
+    }): import("../index.js").VovkTool<TInput, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>;
+    <TOutput, TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => import("../types/utils.js").KnownAny>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: import("../index.js").VovkTool<null, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>) => void) | undefined;
+        onError?: ((error: Error, tool: import("../index.js").VovkTool<null, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>) => void) | undefined;
+        target?: import("../types/validation.js").CombinedSpec.Target;
+    } & {
+        inputSchema?: undefined;
+    } & {
+        outputSchema: import("../types/validation.js").CombinedSpec<TOutput, TOutput>;
+    } & {
+        execute: (input: null, processingMeta?: import("../types/utils.js").KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput: TToModelOutput;
+    }): import("../index.js").VovkTool<null, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>;
+    <TOutput>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: import("../index.js").VovkTool<null, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: import("../index.js").VovkTool<null, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>) => void) | undefined;
+        target?: import("../types/validation.js").CombinedSpec.Target;
+    } & {
+        inputSchema?: undefined;
+    } & {
+        outputSchema: import("../types/validation.js").CombinedSpec<TOutput, TOutput>;
+    } & {
+        execute: (input: null, processingMeta?: import("../types/utils.js").KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput?: undefined;
+    }): import("../index.js").VovkTool<null, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>;
+    <TOutput, TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => import("../types/utils.js").KnownAny>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: import("../index.js").VovkTool<null, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>) => void) | undefined;
+        onError?: ((error: Error, tool: import("../index.js").VovkTool<null, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>) => void) | undefined;
+        target?: import("../types/validation.js").CombinedSpec.Target;
+    } & {
+        inputSchema?: undefined;
+    } & {
+        outputSchema?: undefined;
+    } & {
+        execute: (input: null, processingMeta?: import("../types/utils.js").KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput: TToModelOutput;
+    }): import("../index.js").VovkTool<null, TOutput, TToModelOutput extends import("./to-model-output-default.js").ToModelOutputDefaultFn ? import("./to-model-output-default.js").DefaultModelOutput<TOutput> : TToModelOutput extends (...args: import("../types/utils.js").KnownAny[]) => infer R ? R extends Promise<infer U> ? U : R : unknown>;
+    <TOutput>(options: {
+        name: string;
+        title?: string;
+        description: string;
+        onExecute?: ((result: unknown, tool: import("../index.js").VovkTool<null, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>) => void) | undefined;
+        onError?: ((error: Error, tool: import("../index.js").VovkTool<null, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>) => void) | undefined;
+        target?: import("../types/validation.js").CombinedSpec.Target;
+    } & {
+        inputSchema?: undefined;
+    } & {
+        outputSchema?: undefined;
+    } & {
+        execute: (input: null, processingMeta?: import("../types/utils.js").KnownAny) => TOutput | Promise<TOutput>;
+        toModelOutput?: undefined;
+    }): import("../index.js").VovkTool<null, TOutput, import("./to-model-output-default.js").DefaultModelOutput<TOutput>>;
+};

package/dist/tools/create-tool.js

@@ -0,0 +1,6 @@
+import { procedure } from '../validation/procedure.js';
+/**
+ * Function to create a standalone AI tool.
+ * @see https://vovk.dev/tools
+ */
+export const createTool = procedure.createTool;

package/dist/tools/derive-tools.d.ts

@@ -0,0 +1,46 @@
+import type { DefaultModelOutput } from './to-model-output-default.js';
+import type { VovkRequest } from '../types/request.js';
+import type { VovkTool, ToModelOutputFn } from '../types/tools.js';
+type DerivedToolInput = {
+    body?: unknown;
+    query?: unknown;
+    params?: unknown;
+};
+type DeriveToolsBaseOptions<TOutput = unknown, TFormattedOutput = unknown> = {
+    modules: Record<string, object>;
+    meta?: Record<string, unknown>;
+    onExecute?: (result: unknown, tool: VovkTool<DerivedToolInput, TOutput, TFormattedOutput>, req: Pick<VovkRequest, 'vovk'> | null) => void;
+    onError?: (error: Error, tool: VovkTool<DerivedToolInput, TOutput, TFormattedOutput>, req: Pick<VovkRequest, 'vovk'> | null) => void;
+};
+type DeriveToolsResult<TOutput, TFormattedOutput> = {
+    tools: VovkTool<DerivedToolInput, TOutput, TFormattedOutput>[];
+    toolsByName: Record<string, VovkTool<DerivedToolInput, TOutput, TFormattedOutput>>;
+};
+/**
+ * Derives AI tools from controllers and RPC modules.
+ * @see https://vovk.dev/tools
+ * @example
+ * ```ts
+ * import { deriveTools, ToModelOutput } from 'vovk';
+ * import { UserRPC } from 'vovk-client';
+ *
+ * // Derive AI tools from the UserRPC module
+ * const { tools, toolsByName } = deriveTools({
+ *   modules: { UserRPC },
+ *   toModelOutput: ToModelOutput.MCP,
+ *   onExecute: (result, tool) => {
+ *     console.log(`Tool ${tool.name} executed successfully.`);
+ *   },
+ *   onError: (error, tool) => {
+ *     console.error(`Tool ${tool.name} execution failed:`, error);
+ *   },
+ * });
+ * ```
+ */
+export declare function deriveTools<TOutput = unknown, TFormattedOutput = DefaultModelOutput<TOutput>>(options: DeriveToolsBaseOptions & {
+    toModelOutput?: never;
+}): DeriveToolsResult<TOutput, TFormattedOutput>;
+export declare function deriveTools<TOutput = unknown, TFormattedOutput = unknown>(options: DeriveToolsBaseOptions & {
+    toModelOutput: ToModelOutputFn<unknown, TOutput, TFormattedOutput>;
+}): DeriveToolsResult<TOutput, TFormattedOutput>;
+export {};

package/dist/tools/derive-tools.js

@@ -0,0 +1,131 @@
+import { ToModelOutput } from './to-model-output.js';
+import { validationSchemasObjectToSingleValidationSchema } from '../validation/validation-schemas-object-to-single-validation-schema.js';
+async function caller({ handler, handlerName, body, query, params, meta, toModelOutput }, tool) {
+    if (!handler.isRPC && !handler.fn) {
+        throw new Error('Handler is not a valid RPC or controller method');
+    }
+    try {
+        let result;
+        let req = null;
+        if (handler.isRPC) {
+            result = await handler({
+                handler,
+                body,
+                query,
+                params,
+                meta,
+            });
+        }
+        else if (handler.fn) {
+            [result, req] = await handler.fn({
+                body,
+                query,
+                params,
+                meta,
+                transform: (result, req) => [result, req],
+            });
+        }
+        else {
+            throw new Error(`Unable to call handler "${handlerName}". It's neither RPC nor controller method with "fn" interface.`);
+        }
+        return [await toModelOutput(result, tool, req), req];
+    }
+    catch (e) {
+        return [await toModelOutput(e, tool, null), null];
+    }
+}
+const makeTool = ({ moduleName, handlerName, module, meta, toModelOutput, onExecute, onError, }) => {
+    if (!module) {
+        throw new Error(`Module "${moduleName}" not found.`);
+    }
+    const handler = module[handlerName];
+    if (!handler) {
+        throw new Error(`Handler "${handlerName}" not found in module "${moduleName}".`);
+    }
+    const { schema, definition } = handler;
+    const inputSchemas = Object.fromEntries(['body', 'query', 'params'].map((key) => [key, definition?.[key]]).filter(([, value]) => Boolean(value)));
+    const inputSchema = Object.keys(inputSchemas).length > 0 ? validationSchemasObjectToSingleValidationSchema(inputSchemas) : undefined;
+    if (!schema?.operationObject) {
+        throw new Error(`Handler "${handlerName}" in module "${moduleName}" does not have a valid schema.`);
+    }
+    const execute = async (input) => {
+        const { body, query, params } = input;
+        const callerInput = {
+            schema,
+            inputSchemas,
+            handler,
+            body,
+            query,
+            params,
+            meta,
+            handlerName,
+            moduleName,
+            toModelOutput,
+        };
+        const [result, req] = await caller(callerInput, tool);
+        if (result instanceof Error) {
+            onError(result, tool, req);
+        }
+        else {
+            onExecute(result, tool, req);
+        }
+        return result;
+    };
+    const parametersProperties = {
+        ...(schema?.validation?.body
+            ? {
+                body: schema.validation.body,
+            }
+            : {}),
+        ...(schema?.validation?.query
+            ? {
+                query: schema.validation.query,
+            }
+            : {}),
+        ...(schema?.validation?.params
+            ? {
+                params: schema.validation.params,
+            }
+            : {}),
+    };
+    const tool = {
+        type: 'function',
+        execute,
+        name: schema.operationObject?.['x-tool']?.name ?? `${moduleName}_${handlerName}`,
+        inputSchema: inputSchema,
+        outputSchema: definition?.output,
+        title: schema.operationObject?.['x-tool']?.title ?? schema.operationObject?.summary,
+        description: schema.operationObject?.['x-tool']?.description ??
+            ([schema.operationObject?.summary ?? '', schema.operationObject?.description ?? ''].filter(Boolean).join('\n') ||
+                handlerName),
+        parameters: {
+            type: 'object',
+            properties: parametersProperties,
+            required: Object.keys(parametersProperties),
+            additionalProperties: false,
+        },
+        inputSchemas,
+    };
+    return tool;
+};
+export function deriveTools(options) {
+    const { modules, meta, toModelOutput = ToModelOutput.DEFAULT, onExecute = (result) => result, onError = () => { }, } = options;
+    const tools = Object.entries(modules ?? {}).flatMap(([moduleName, module]) => {
+        return Object.entries(module ?? {})
+            .filter(([, handler]) => handler?.schema?.operationObject && !handler?.schema?.operationObject?.['x-tool']?.hidden)
+            .map(([handlerName]) => makeTool({
+            moduleName,
+            handlerName,
+            module,
+            meta,
+            toModelOutput,
+            onExecute,
+            onError,
+        }));
+    });
+    const toolsByName = Object.fromEntries(tools.map((tool) => [tool.name, tool]));
+    return {
+        tools,
+        toolsByName,
+    };
+}

package/dist/tools/to-model-output-default.d.ts

@@ -0,0 +1,7 @@
+import type { VovkRequest } from '../types/request.js';
+import type { VovkTool } from '../types/tools.js';
+export type DefaultModelOutput<T> = T | {
+    error: string;
+};
+export type ToModelOutputDefaultFn = <TInput, TOutput>(result: TOutput | Error, tool: VovkTool<TInput, TOutput, unknown>, req: Pick<VovkRequest, 'vovk'> | null) => DefaultModelOutput<TOutput>;
+export declare const toModelOutputDefault: ToModelOutputDefaultFn;

package/dist/tools/to-model-output-default.js

@@ -0,0 +1,7 @@
+export const toModelOutputDefault = (result, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_tool, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_req) => {
+    return result instanceof Error ? { error: result.message } : result;
+};

package/dist/tools/to-model-output-mcp.d.ts

@@ -0,0 +1,30 @@
+import type { VovkRequest } from '../types/request.js';
+import type { VovkTool } from '../types/tools.js';
+export type MCPModelOutput = {
+    content: [
+        {
+            type: 'audio';
+            mimeType: string;
+            data: string;
+        } | {
+            type: 'image';
+            mimeType: string;
+            data: string;
+        } | {
+            type: 'text';
+            text: string;
+        }
+    ];
+    annotations?: {
+        audience?: ('user' | 'assistant')[];
+        priority?: number;
+        lastModified?: string;
+    };
+    structuredContent?: {
+        [key: string]: unknown;
+    };
+    isError?: boolean;
+};
+type ToModelOutputMCPFn = <TOutput>(result: TOutput | Error, tool: VovkTool, req: Pick<VovkRequest, 'vovk'> | null) => Promise<MCPModelOutput>;
+export declare const toModelOutputMCP: ToModelOutputMCPFn;
+export {};

package/dist/tools/to-model-output-mcp.js

@@ -0,0 +1,54 @@
+import { reqMeta } from '../req/req-meta.js';
+// converts array to object with "items" key for MCP structured content
+const structuredContentToObject = (data) => {
+    if (Array.isArray(data)) {
+        return { items: data };
+    }
+    return data;
+};
+const toBase64 = (buf) => typeof Buffer !== 'undefined'
+    ? Buffer.from(buf).toString('base64')
+    : btoa([...new Uint8Array(buf)].map((b) => String.fromCharCode(b)).join(''));
+async function responseToMCP(res) {
+    const mimeType = res.headers.get('Content-Type')?.split(';')[0].trim() || '';
+    if (mimeType.startsWith('audio/')) {
+        return { content: [{ type: 'audio', mimeType, data: toBase64(await res.arrayBuffer()) }] };
+    }
+    if (mimeType.startsWith('image/')) {
+        return { content: [{ type: 'image', mimeType, data: toBase64(await res.arrayBuffer()) }] };
+    }
+    if (mimeType === 'application/json') {
+        const structuredContent = await res.json();
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
+            structuredContent: structuredContentToObject(structuredContent),
+        };
+    }
+    if (mimeType.startsWith('text/') || /xml|javascript|yaml/.test(mimeType)) {
+        return { content: [{ type: 'text', text: await res.text() }] };
+    }
+    return {
+        content: [{ type: 'text', text: `Unsupported response content type ${mimeType}` }],
+        isError: true,
+    };
+}
+export const toModelOutputMCP = async (result, _tool, req) => {
+    const mcpOutputMeta = req ? reqMeta(req).mcpOutput : null;
+    if (result instanceof Response) {
+        return { ...(await responseToMCP(result)), ...(mcpOutputMeta || {}) };
+    }
+    const isError = result instanceof Error;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: isError ? result.message : JSON.stringify(result),
+            },
+        ],
+        ...(isError ? { isError: true } : {}),
+        ...(!isError && typeof result === 'object' && result !== null
+            ? { structuredContent: structuredContentToObject(result) }
+            : {}),
+        ...(mcpOutputMeta || {}),
+    };
+};

package/dist/tools/to-model-output.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Collection of functions to convert model outputs into different formats.
+ * @see https://vovk.dev/tools
+ */
+export declare const ToModelOutput: {
+    readonly DEFAULT: import("./to-model-output-default.js").ToModelOutputDefaultFn;
+    readonly MCP: <TOutput>(result: TOutput | Error, tool: import("../index.js").VovkTool, req: Pick<import("../index.js").VovkRequest, "vovk"> | null) => Promise<import("./to-model-output-mcp.js").MCPModelOutput>;
+};

package/dist/tools/to-model-output.js

@@ -0,0 +1,10 @@
+import { toModelOutputDefault } from './to-model-output-default.js';
+import { toModelOutputMCP } from './to-model-output-mcp.js';
+/**
+ * Collection of functions to convert model outputs into different formats.
+ * @see https://vovk.dev/tools
+ */
+export const ToModelOutput = {
+    DEFAULT: toModelOutputDefault,
+    MCP: toModelOutputMCP,
+};

package/dist/types/client.d.ts

@@ -1,7 +1,7 @@
 import type { NextResponse } from 'next/server.js';
-import type { JSONLinesResponder } from '../core/JSONLinesResponder.js';
-import type { defaultStreamHandler } from '../client/defaultStreamHandler.js';
-import type { defaultHandler } from '../client/defaultHandler.js';
+import type { JSONLinesResponder } from '../core/json-lines-responder.js';
+import type { defaultStreamHandler } from '../client/default-stream-handler.js';
+import type { defaultHandler } from '../client/default-handler.js';
 import type { VovkRequest } from './request.js';
 import type { ControllerStaticMethod, VovkControllerSchema, VovkHandlerSchema, VovkSchema, VovkSegmentSchema } from './core.js';
 import type { IsEmptyObject, KnownAny, Prettify } from './utils.js';