@od-oneapp/ai-platform 0.1.0

package/src/tools/validation-wrapper.ts

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Tool Validation Wrapper
+ *
+ * Provides utilities for adding custom runtime validation to AI SDK tools.
+ * Useful for enforcing business rules beyond what Zod schemas express.
+ *
+ * @module @od-oneapp/ai-platform/tools/validation-wrapper
+ */
+
+import type { SDKTool, SDKToolExecuteFunction, SDKToolExecutionOptions } from '../shared';
+
+/**
+ * Wraps a tool with an additional runtime validation step.
+ *
+ * Vercel AI SDK v6 tools already validate input against Zod schemas.
+ * Use this wrapper when you need custom business-rule validation
+ * (e.g., authorization checks, rate limiting, cross-field constraints)
+ * that runs before the tool's execute function.
+ *
+ * @param t - The tool to wrap
+ * @param options - Validation options
+ * @param options.validate - Custom validator returning true/false (sync or async)
+ * @returns A new tool that validates input before executing
+ *
+ * @example
+ * ```ts
+ * const safeTool = withValidation(deleteTool, {
+ *   validate: (input) => input.userId === currentUser.id,
+ * });
+ * ```
+ */
+export function withValidation<TInput = unknown, TOutput = unknown>(
+  t: SDKTool<TInput, TOutput>,
+  options: {
+    validate?: (input: TInput) => boolean | Promise<boolean>;
+  } = {},
+): SDKTool<TInput, TOutput> {
+  // If no extra validation, return as is
+  if (!options.validate) return t;
+
+  const wrappedTool = { ...t };
+  const wrappedExecute: SDKToolExecuteFunction<TInput, TOutput> = (
+    input: TInput,
+    executionOptions: SDKToolExecutionOptions,
+  ) => {
+    const { validate } = options;
+    const run = (): ReturnType<SDKToolExecuteFunction<TInput, TOutput>> => {
+      if (!t.execute) {
+        throw new Error('Strict tool wrapper requires a tool execute function');
+      }
+      return t.execute(input, executionOptions);
+    };
+
+    const isAsyncIterable = (value: unknown): value is AsyncIterable<TOutput> => {
+      return (
+        typeof value === 'object' &&
+        value !== null &&
+        Symbol.asyncIterator in (value as Record<string, unknown>)
+      );
+    };
+
+    if (!validate) {
+      return run();
+    }
+
+    const validationResult = validate(input);
+    const isPromiseLike = (value: unknown): value is PromiseLike<boolean> =>
+      typeof (value as { then?: unknown })?.then === 'function';
+
+    if (isPromiseLike(validationResult)) {
+      return (async () => {
+        const valid = await validationResult;
+        if (!valid) {
+          throw new Error(`Strict validation failed for tool ${t.description?.slice(0, 20)}...`);
+        }
+
+        const result = run();
+        if (isAsyncIterable(result)) {
+          throw new Error('Async validation is not supported for streaming tool results');
+        }
+        return result;
+      })();
+    }
+
+    if (!validationResult) {
+      throw new Error(`Strict validation failed for tool ${t.description?.slice(0, 20)}...`);
+    }
+
+    const result = run();
+    if (isAsyncIterable(result)) {
+      return result;
+    }
+    return result;
+  };
+  wrappedTool.execute = wrappedExecute;
+  return wrappedTool;
+}