@od-oneapp/ai-platform 0.1.0

package/src/tools/core/factory.ts

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview Tool factory utilities with dependency injection pattern.
+ * @module @od-oneapp/ai-platform/tools/core
+ */
+
+import { type z } from 'zod';
+
+import { tool } from '../../shared';
+
+import type { SDKTool as Tool } from '../../shared';
+
+/**
+ * Tool execution context passed to tool handlers.
+ */
+export interface ToolExecutionContext {
+  /** User ID making the request */
+  userId?: string;
+  /** Session ID */
+  sessionId?: string;
+  /** Abort signal for cancellation */
+  abortSignal?: AbortSignal;
+  /** Additional context data */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Handler function signature for tool execution.
+ */
+export type ToolHandler<TInput, TOutput> = (
+  input: TInput,
+  context: ToolExecutionContext,
+) => Promise<TOutput>;
+
+/**
+ * Configuration for creating a tool with dependency injection.
+ */
+export interface ToolFactoryConfig<TSchema extends z.ZodObject<z.ZodRawShape>> {
+  /** Tool name */
+  name: string;
+  /** Tool description for the LLM */
+  description: string;
+  /** Zod schema for input parameters */
+  parameters: TSchema;
+  /** Handler function */
+  handler: ToolHandler<z.infer<TSchema>, unknown>;
+}
+
+/**
+ * Creates a tool with dependency-injected context.
+ *
+ * @param config - Tool configuration
+ * @param context - Execution context to inject
+ * @returns AI SDK tool
+ *
+ * @example
+ * ```ts
+ * const searchTool = createToolWithContext({
+ *   name: 'search',
+ *   description: 'Search documents',
+ *   parameters: z.object({ query: z.string() }),
+ *   handler: async ({ query }, ctx) => {
+ *     return searchDocs(query, ctx.userId);
+ *   },
+ * }, { userId: 'user-123' });
+ * ```
+ */
+export function createToolWithContext<TSchema extends z.ZodObject<z.ZodRawShape>>(
+  config: ToolFactoryConfig<TSchema>,
+  context: ToolExecutionContext,
+): Tool {
+  return tool({
+    description: config.description,
+    inputSchema: config.parameters,
+    execute: async input => {
+      return config.handler(input as z.infer<TSchema>, context);
+    },
+  });
+}
+
+/**
+ * Creates a tool factory that returns tools with injected context.
+ *
+ * @param config - Tool configuration without handler
+ * @returns Factory function that accepts handler and context
+ *
+ * @example
+ * ```ts
+ * const createSearchTool = createToolFactory({
+ *   name: 'search',
+ *   description: 'Search documents',
+ *   parameters: z.object({ query: z.string() }),
+ * });
+ *
+ * const searchTool = createSearchTool(
+ *   async ({ query }, ctx) => searchDocs(query, ctx.userId),
+ *   { userId: 'user-123' }
+ * );
+ * ```
+ */
+export function createToolFactory<TSchema extends z.ZodObject<z.ZodRawShape>>(config: {
+  name: string;
+  description: string;
+  parameters: TSchema;
+}) {
+  return function (
+    handler: ToolHandler<z.infer<TSchema>, unknown>,
+    context: ToolExecutionContext = {},
+  ): Tool {
+    return createToolWithContext({ ...config, handler }, context);
+  };
+}
+
+/**
+ * Wraps a tool handler with error handling and logging.
+ *
+ * @param handler - Original handler function
+ * @param options - Wrapper options
+ * @returns Wrapped handler
+ */
+export function wrapToolHandler<TInput, TOutput>(
+  handler: ToolHandler<TInput, TOutput>,
+  options: {
+    /** Tool name for logging */
+    name: string;
+    /** Custom error handler */
+    onError?: (error: Error, input: TInput) => TOutput | Promise<TOutput>;
+    /** Pre-execution hook */
+    onBefore?: (input: TInput, context: ToolExecutionContext) => void | Promise<void>;
+    /** Post-execution hook */
+    onAfter?: (
+      input: TInput,
+      output: TOutput,
+      context: ToolExecutionContext,
+    ) => void | Promise<void>;
+  },
+): ToolHandler<TInput, TOutput> {
+  return async (input, context) => {
+    try {
+      if (options.onBefore) {
+        await options.onBefore(input, context);
+      }
+
+      const result = await handler(input, context);
+
+      if (options.onAfter) {
+        await options.onAfter(input, result, context);
+      }
+
+      return result;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      // Tool execution failed
+
+      if (options.onError) {
+        return options.onError(err, input);
+      }
+
+      throw err;
+    }
+  };
+}
+
+/**
+ * Creates multiple tools from a configuration object.
+ *
+ * @param configs - Map of tool names to configurations
+ * @param context - Shared execution context
+ * @returns Record of tools
+ *
+ * @example
+ * ```ts
+ * const tools = createTools({
+ *   search: {
+ *     description: 'Search documents',
+ *     parameters: z.object({ query: z.string() }),
+ *     handler: async ({ query }) => searchDocs(query),
+ *   },
+ *   create: {
+ *     description: 'Create document',
+ *     parameters: z.object({ title: z.string() }),
+ *     handler: async ({ title }) => createDoc(title),
+ *   },
+ * }, { userId: 'user-123' });
+ * ```
+ */
+export function createTools(
+  configs: Record<string, ToolFactoryConfig<z.ZodObject<z.ZodRawShape>>>,
+  context: ToolExecutionContext = {},
+): Record<string, Tool> {
+  const tools: Record<string, Tool> = {};
+
+  for (const [name, config] of Object.entries(configs)) {
+    tools[name] = createToolWithContext(config, context);
+  }
+
+  return tools;
+}

package/src/tools/core/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Tool core utilities - factory, abort handling, safety.
+ * @module @od-oneapp/ai-platform/tools/core
+ */
+
+export * from './factory';
+export * from './abort';
+export * from './tool-safety';

package/src/tools/core/tool-safety.ts

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Tool safety utilities — retry logic and fallback patterns.
+ * @module @od-oneapp/ai-platform/tools/core/tool-safety
+ */
+
+/**
+ * Execute a tool safely with basic retry logic.
+ * Simple wrapper that reduces error handling boilerplate across monorepo.
+ *
+ * @template T - Return type of the tool function
+ * @param toolFn - Async function to execute
+ * @param options - Retry and error handling options
+ * @returns Promise resolving to the tool function result
+ *
+ * @example
+ * ```typescript
+ * const response = await executeToolSafely(() => myTool.invoke(), {
+ *   retries: 2,
+ *   onRetry: (attempt) => console.info(`Retrying attempt ${attempt}`),
+ * });
+ * ```
+ */
+export async function executeToolSafely<T>(
+  toolFn: () => Promise<T>,
+  options: {
+    retries?: number;
+    delay?: number;
+    onRetry?: (attempt: number, error: unknown) => void;
+    onError?: (error: unknown) => void;
+    fallback?: T;
+  } = {},
+): Promise<T> {
+  const { retries = 3, delay = 1000, onRetry, onError, fallback } = options;
+
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      return await toolFn();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt === retries) {
+        // eslint-disable-next-line no-console -- intentional tool execution error logging
+        console.error('[Tools] Tool execution failed after all retries', {
+          attempts: retries,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        break;
+      }
+
+      if (onRetry) {
+        onRetry(attempt, error);
+      }
+
+      // eslint-disable-next-line no-console -- intentional tool retry logging
+      console.warn('[Tools] Tool execution failed, retrying', {
+        attempt,
+        retries,
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      // Simple delay before retry
+      if (delay > 0) {
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  // Return fallback if provided, otherwise throw
+  if (fallback !== undefined) {
+    // eslint-disable-next-line no-console -- intentional fallback logging
+    console.warn('[Tools] Returning fallback value after all retries failed');
+    if (onError) {
+      onError(lastError);
+    }
+    return fallback;
+  }
+
+  throw lastError;
+}
+
+/**
+ * Execute tool with fallback function.
+ * Simple DRY helper for common fallback pattern.
+ *
+ * @template T - Return type of the tool functions
+ * @param primaryFn - Primary async function to execute
+ * @param fallbackFn - Fallback async function to execute on failure
+ * @returns Promise resolving to the result of either primary or fallback
+ *
+ * @example
+ * ```typescript
+ * const primary = () => aiTool.invoke();
+ * const fallback = () => cachedResult();
+ * const result = await executeWithFallback(primary, fallback);
+ * ```
+ */
+export async function executeWithFallback<T>(
+  primaryFn: () => Promise<T>,
+  fallbackFn: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await primaryFn();
+  } catch (error) {
+    // eslint-disable-next-line no-console -- intentional fallback logging
+    console.warn('[Tools] Primary execution failed, using fallback', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return await fallbackFn();
+  }
+}

package/src/tools/generic/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Generic tool utilities - dynamic creation, registry.
+ * @module @od-oneapp/ai-platform/tools/generic
+ */
+
+export * from './json-schema-tool';
+export * from './web-search';
+export * from './web-search-tool';
+export * from './tiptap-context';

package/src/tools/generic/json-schema-tool.ts

@@ -0,0 +1,301 @@
+/**
+ * @fileoverview JSON Schema tool creation utilities.
+ *
+ * Creates AI SDK tools from plain JSON-style schema definitions
+ * (as opposed to pre-built Zod schemas). Useful for tools defined
+ * at runtime or loaded from configuration files.
+ *
+ * @module @od-oneapp/ai-platform/tools/generic/json-schema-tool
+ */
+
+import { z } from 'zod';
+
+import { tool } from '../../shared';
+
+import type { SDKTool as Tool } from '../../shared';
+
+/**
+ * Schema definition for dynamic tools.
+ */
+export interface DynamicToolSchema {
+  /** Tool name */
+  name: string;
+  /** Tool description */
+  description: string;
+  /** Parameter definitions */
+  parameters: Record<string, ParameterDefinition>;
+  /** Required parameters */
+  required?: string[];
+}
+
+/**
+ * Parameter definition for dynamic tools.
+ */
+export interface ParameterDefinition {
+  /** Parameter type */
+  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  /** Parameter description */
+  description: string;
+  /** Enum values (for string type) */
+  enum?: string[];
+  /** Default value */
+  default?: unknown;
+  /** Minimum (for number type) */
+  minimum?: number;
+  /** Maximum (for number type) */
+  maximum?: number;
+  /** Items schema (for array type) */
+  items?: ParameterDefinition;
+  /** Properties (for object type) */
+  properties?: Record<string, ParameterDefinition>;
+}
+
+/**
+ * Mutable shape type for building schemas.
+ */
+type MutableZodShape = { [key: string]: z.ZodTypeAny };
+
+/**
+ * Creates a Zod schema from a parameter definition.
+ */
+function parameterToZod(param: ParameterDefinition): z.ZodTypeAny {
+  let schema: z.ZodTypeAny;
+
+  switch (param.type) {
+    case 'string':
+      if (param.enum) {
+        schema = z.enum(param.enum as [string, ...string[]]);
+      } else {
+        schema = z.string();
+      }
+      break;
+    case 'number': {
+      let numSchema = z.number();
+      if (param.minimum !== undefined) {
+        numSchema = numSchema.min(param.minimum);
+      }
+      if (param.maximum !== undefined) {
+        numSchema = numSchema.max(param.maximum);
+      }
+      schema = numSchema;
+      break;
+    }
+    case 'boolean':
+      schema = z.boolean();
+      break;
+    case 'array':
+      schema = z.array(param.items ? parameterToZod(param.items) : z.unknown());
+      break;
+    case 'object':
+      if (param.properties) {
+        const shape: MutableZodShape = {};
+        for (const [key, prop] of Object.entries(param.properties)) {
+          shape[key] = parameterToZod(prop);
+        }
+        schema = z.object(shape);
+      } else {
+        schema = z.record(z.string(), z.unknown());
+      }
+      break;
+    default:
+      schema = z.unknown();
+  }
+
+  return schema.describe(param.description);
+}
+
+/**
+ * Creates a Zod schema from a dynamic tool schema.
+ */
+function schemaToZod(schema: DynamicToolSchema): z.ZodObject<z.ZodRawShape> {
+  const shape: MutableZodShape = {};
+
+  for (const [name, param] of Object.entries(schema.parameters)) {
+    const zodParam = parameterToZod(param);
+    shape[name] = schema.required?.includes(name) ? zodParam : zodParam.optional();
+  }
+
+  return z.object(shape);
+}
+
+/**
+ * Creates an AI SDK tool from a JSON-style schema definition.
+ *
+ * Converts the plain-object schema to Zod internally, so callers
+ * don't need to depend on Zod directly. For pre-built Zod schemas,
+ * use {@link createToolFromZodSchema} from `tools/simple-factory` instead.
+ *
+ * @param schema - Tool schema with name, description, and parameter definitions
+ * @param execute - Async function that receives validated params and returns a result
+ * @returns AI SDK tool instance
+ *
+ * @example
+ * ```ts
+ * const calcTool = createJsonSchemaTool({
+ *   name: 'calculate',
+ *   description: 'Perform calculations',
+ *   parameters: {
+ *     operation: { type: 'string', description: 'Operation', enum: ['add', 'sub'] },
+ *     a: { type: 'number', description: 'First number' },
+ *     b: { type: 'number', description: 'Second number' },
+ *   },
+ *   required: ['operation', 'a', 'b'],
+ * }, async ({ operation, a, b }) => {
+ *   return operation === 'add' ? a + b : a - b;
+ * });
+ * ```
+ */
+export function createJsonSchemaTool<T = Record<string, unknown>>(
+  schema: DynamicToolSchema,
+  execute: (params: T) => Promise<unknown>,
+): Tool {
+  return tool({
+    description: schema.description,
+    inputSchema: schemaToZod(schema),
+    execute: async params => execute(params as T),
+  });
+}
+
+/**
+ * Registry for managing tools created from JSON schema definitions.
+ *
+ * Stores tools and their schemas by name, supporting lookup, filtering,
+ * and bulk retrieval. For tools created from Zod schemas, use them directly
+ * without a registry.
+ */
+export class JsonSchemaToolRegistry {
+  private tools = new Map<string, Tool>();
+  private schemas = new Map<string, DynamicToolSchema>();
+
+  /**
+   * Registers a tool with schema.
+   */
+  register<T = Record<string, unknown>>(
+    schema: DynamicToolSchema,
+    execute: (params: T) => Promise<unknown>,
+  ): void {
+    const t = createJsonSchemaTool(schema, execute);
+    this.tools.set(schema.name, t);
+    this.schemas.set(schema.name, schema);
+  }
+
+  /**
+   * Gets a tool by name.
+   */
+  get(name: string): Tool | undefined {
+    return this.tools.get(name);
+  }
+
+  /**
+   * Gets schema by name.
+   */
+  getSchema(name: string): DynamicToolSchema | undefined {
+    return this.schemas.get(name);
+  }
+
+  /**
+   * Gets all tools.
+   */
+  all(): Record<string, Tool> {
+    return Object.fromEntries(this.tools);
+  }
+
+  /**
+   * Gets all schemas.
+   */
+  allSchemas(): DynamicToolSchema[] {
+    return Array.from(this.schemas.values());
+  }
+
+  /**
+   * Filters tools by pattern.
+   * Note: String patterns are escaped to prevent ReDoS attacks.
+   * To use regex patterns, pass a RegExp object directly.
+   */
+  filter(pattern: string | RegExp): Record<string, Tool> {
+    // Escape string patterns to prevent ReDoS attacks (CWE-1333)
+    const regex =
+      typeof pattern === 'string'
+        ? new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        : pattern;
+    const filtered: Record<string, Tool> = {};
+
+    for (const [name, t] of this.tools) {
+      if (regex.test(name)) {
+        filtered[name] = t;
+      }
+    }
+
+    return filtered;
+  }
+
+  /**
+   * Removes a tool.
+   */
+  remove(name: string): boolean {
+    this.schemas.delete(name);
+    return this.tools.delete(name);
+  }
+
+  /**
+   * Clears all tools.
+   */
+  clear(): void {
+    this.tools.clear();
+    this.schemas.clear();
+  }
+}
+
+/**
+ * Creates a tool that can be dynamically enabled/disabled.
+ *
+ * @param baseTool - The base tool
+ * @param isEnabled - Function to check if tool is enabled
+ * @returns Conditional tool
+ */
+export function createConditionalTool(
+  baseTool: Tool,
+  isEnabled: () => boolean | Promise<boolean>,
+): Tool {
+  const { execute } = baseTool;
+  return {
+    ...baseTool,
+    execute: execute
+      ? async (...args: Parameters<NonNullable<typeof baseTool.execute>>) => {
+          const enabled = await isEnabled();
+          if (!enabled) {
+            return { error: 'Tool is currently disabled' };
+          }
+          return execute(...args);
+        }
+      : undefined,
+  };
+}
+
+/**
+ * Composes multiple tools into a single tool with routing.
+ *
+ * @param tools - Map of route patterns to tools
+ * @param router - Function to determine route from input
+ * @returns Composed tool
+ */
+export function composeTools(
+  tools: Record<string, Tool>,
+  router: (input: Record<string, unknown>) => string,
+): Tool {
+  return tool({
+    description: `Composed tool with routes: ${Object.keys(tools).join(', ')}`,
+    inputSchema: z.object({}).passthrough(),
+    execute: async (input, options) => {
+      const typedInput = input as Record<string, unknown>;
+      const route = router(typedInput);
+      const selectedTool = tools[route];
+
+      if (!selectedTool) {
+        return { error: `Unknown route: ${route}` };
+      }
+
+      return selectedTool.execute?.(typedInput, options);
+    },
+  });
+}