@od-oneapp/ai-platform 0.1.0

package/src/tools/advanced/generator.ts

@@ -0,0 +1,267 @@
+/**
+ * @fileoverview Async generator tools for streaming tool results.
+ * @module @od-oneapp/ai-platform/tools/advanced
+ */
+
+import { type z } from 'zod';
+
+import { tool } from '../../shared';
+
+import type { SDKTool as Tool } from '../../shared';
+
+/**
+ * Configuration for generator tool.
+ */
+export interface GeneratorToolConfig<TSchema extends z.ZodObject<z.ZodRawShape>, TChunk, TFinal> {
+  /** Tool name */
+  name: string;
+  /** Tool description */
+  description: string;
+  /** Input parameters schema */
+  parameters: TSchema;
+  /** Async generator function */
+  generator: (input: z.infer<TSchema>) => AsyncGenerator<TChunk, TFinal, unknown>;
+  /** Optional chunk transformer */
+  transformChunk?: (chunk: TChunk, index: number) => unknown;
+  /** Optional final result transformer */
+  transformFinal?: (final: TFinal, chunks: TChunk[]) => unknown;
+}
+
+/**
+ * Creates a tool that streams results via async generator.
+ *
+ * Note: The tool collects all chunks and returns the final result.
+ * For true streaming, use with streamText's onToolCall.
+ *
+ * @param config - Generator tool configuration
+ * @returns AI SDK tool
+ *
+ * @example
+ * ```ts
+ * const processFileTool = createGeneratorTool({
+ *   name: 'processFile',
+ *   description: 'Process a large file in chunks',
+ *   parameters: z.object({ path: z.string() }),
+ *   generator: async function* ({ path }) {
+ *     const chunks = await readFileChunks(path);
+ *     for (const chunk of chunks) {
+ *       yield { processed: processChunk(chunk) };
+ *     }
+ *     return { totalChunks: chunks.length };
+ *   },
+ * });
+ * ```
+ */
+export function createGeneratorTool<TSchema extends z.ZodObject<z.ZodRawShape>, TChunk, TFinal>(
+  config: GeneratorToolConfig<TSchema, TChunk, TFinal>,
+): Tool {
+  return tool({
+    description: config.description,
+    inputSchema: config.parameters,
+    execute: async input => {
+      const typedInput = input as z.infer<TSchema>;
+      const chunks: TChunk[] = [];
+      let index = 0;
+      let finalResult: TFinal | undefined;
+
+      const gen = config.generator(typedInput);
+
+      for (;;) {
+        const { value, done } = await gen.next();
+
+        if (done) {
+          finalResult = value;
+          break;
+        }
+
+        const chunk = value;
+        chunks.push(chunk);
+
+        if (config.transformChunk) {
+          config.transformChunk(chunk, index);
+        }
+        index++;
+      }
+
+      if (config.transformFinal && finalResult !== undefined) {
+        return config.transformFinal(finalResult, chunks);
+      }
+
+      return { chunks, final: finalResult };
+    },
+  });
+}
+
+/**
+ * Creates a paginated tool that fetches results in pages.
+ *
+ * @param config - Pagination tool configuration
+ * @returns AI SDK tool
+ *
+ * @example
+ * ```ts
+ * const listUsersTool = createPaginatedTool({
+ *   name: 'listUsers',
+ *   description: 'List users with pagination',
+ *   parameters: z.object({ filter: z.string().optional() }),
+ *   pageSize: 100,
+ *   maxPages: 10,
+ *   fetchPage: async ({ filter }, page, pageSize) => {
+ *     return fetchUsers({ filter, page, pageSize });
+ *   },
+ * });
+ * ```
+ */
+export function createPaginatedTool<TSchema extends z.ZodObject<z.ZodRawShape>, TItem>(config: {
+  name: string;
+  description: string;
+  parameters: TSchema;
+  pageSize: number;
+  maxPages?: number;
+  fetchPage: (
+    input: z.infer<TSchema>,
+    page: number,
+    pageSize: number,
+  ) => Promise<{ items: TItem[]; hasMore: boolean }>;
+}): Tool {
+  const { pageSize, maxPages = 10 } = config;
+
+  return tool({
+    description: config.description,
+    inputSchema: config.parameters,
+    execute: async input => {
+      const typedInput = input as z.infer<TSchema>;
+      const allItems: TItem[] = [];
+      let page = 0;
+      let hasMore = true;
+
+      while (hasMore && page < maxPages) {
+        const { items, hasMore: pageHasMore } = await config.fetchPage(typedInput, page, pageSize);
+
+        allItems.push(...items);
+        hasMore = pageHasMore;
+        page++;
+      }
+
+      return {
+        items: allItems,
+        totalPages: page,
+        truncated: hasMore,
+      };
+    },
+  });
+}
+
+/**
+ * Creates a tool that retries on failure with exponential backoff.
+ *
+ * @param config - Retry tool configuration
+ * @returns AI SDK tool
+ *
+ * @example
+ * ```ts
+ * const fetchDataTool = createRetryTool({
+ *   name: 'fetchData',
+ *   description: 'Fetch data with retry',
+ *   parameters: z.object({ url: z.string() }),
+ *   maxRetries: 3,
+ *   baseDelay: 1000,
+ *   execute: async ({ url }) => fetch(url).then(r => r.json()),
+ * });
+ * ```
+ */
+export function createRetryTool<TSchema extends z.ZodObject<z.ZodRawShape>>(config: {
+  name: string;
+  description: string;
+  parameters: TSchema;
+  maxRetries: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  execute: (input: z.infer<TSchema>) => Promise<unknown>;
+  shouldRetry?: (error: Error, attempt: number) => boolean;
+}): Tool {
+  const { maxRetries, baseDelay = 1000, maxDelay = 30000, shouldRetry = () => true } = config;
+
+  return tool({
+    description: config.description,
+    inputSchema: config.parameters,
+    execute: async input => {
+      const typedInput = input as z.infer<TSchema>;
+      let lastError: Error | undefined;
+
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          return await config.execute(typedInput);
+        } catch (e) {
+          lastError = e instanceof Error ? e : new Error(String(e));
+
+          if (attempt < maxRetries && shouldRetry(lastError, attempt)) {
+            const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+            await sleep(delay);
+          }
+        }
+      }
+
+      throw lastError;
+    },
+  });
+}
+
+/**
+ * Helper to create a polling tool that waits for a condition.
+ *
+ * @param config - Polling tool configuration
+ * @returns AI SDK tool
+ *
+ * @example
+ * ```ts
+ * const waitForJobTool = createPollingTool({
+ *   name: 'waitForJob',
+ *   description: 'Wait for a job to complete',
+ *   parameters: z.object({ jobId: z.string() }),
+ *   poll: async ({ jobId }) => getJobStatus(jobId),
+ *   isComplete: (status) => status.state === 'complete',
+ *   interval: 2000,
+ *   timeout: 60000,
+ * });
+ * ```
+ */
+export function createPollingTool<TSchema extends z.ZodObject<z.ZodRawShape>, TStatus>(config: {
+  name: string;
+  description: string;
+  parameters: TSchema;
+  poll: (input: z.infer<TSchema>) => Promise<TStatus>;
+  isComplete: (status: TStatus) => boolean;
+  interval?: number;
+  timeout?: number;
+}): Tool {
+  const { interval = 1000, timeout = 30000 } = config;
+
+  return tool({
+    description: config.description,
+    inputSchema: config.parameters,
+    execute: async input => {
+      const typedInput = input as z.infer<TSchema>;
+      const startTime = Date.now();
+
+      while (Date.now() - startTime < timeout) {
+        const status = await config.poll(typedInput);
+
+        if (config.isComplete(status)) {
+          return { complete: true, status };
+        }
+
+        await sleep(interval);
+      }
+
+      return { complete: false, timedOut: true };
+    },
+  });
+}
+
+/**
+ * Sleep helper.
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/tools/advanced/hitl.ts

@@ -0,0 +1,251 @@
+/**
+ * @fileoverview Human-in-the-Loop (HITL) tool approval patterns.
+ * @module @od-oneapp/ai-platform/tools/advanced
+ */
+
+import { type z } from 'zod';
+
+import { tool } from '../../shared';
+
+import type { SDKTool as Tool } from '../../shared';
+
+/**
+ * Approval decision from human.
+ */
+export interface ApprovalDecision {
+  /** Whether the action is approved */
+  approved: boolean;
+  /** Optional reason for decision */
+  reason?: string;
+  /** Modified parameters (if human adjusted) */
+  modifiedParams?: Record<string, unknown>;
+}
+
+/**
+ * Configuration for HITL-wrapped tools.
+ */
+export interface HITLConfig<TSchema extends z.ZodObject<z.ZodRawShape>> {
+  /** Tool name */
+  name: string;
+  /** Tool description */
+  description: string;
+  /** Parameters schema */
+  parameters: TSchema;
+  /** The actual tool execution function */
+  execute: (params: z.infer<TSchema>) => Promise<unknown>;
+  /** Function to request human approval */
+  requestApproval: (params: z.infer<TSchema>) => Promise<ApprovalDecision>;
+  /** Risk level for this tool (affects approval UI) */
+  riskLevel?: 'low' | 'medium' | 'high' | 'critical';
+  /** Whether approval can be auto-granted based on policy */
+  allowAutoApproval?: boolean;
+  /** Callback when approval is denied */
+  onDenied?: (params: z.infer<TSchema>, reason?: string) => void | Promise<void>;
+}
+
+/**
+ * Creates a tool that requires human approval before execution.
+ *
+ * @param config - HITL tool configuration
+ * @returns Tool with approval gate
+ *
+ * @example
+ * ```ts
+ * const deleteFileTool = createHITLTool({
+ *   name: 'deleteFile',
+ *   description: 'Delete a file from the system',
+ *   parameters: z.object({ path: z.string() }),
+ *   execute: async ({ path }) => deleteFile(path),
+ *   requestApproval: async ({ path }) => {
+ *     return await showApprovalModal({
+ *       title: 'Delete File?',
+ *       message: `Are you sure you want to delete ${path}?`,
+ *     });
+ *   },
+ *   riskLevel: 'high',
+ * });
+ * ```
+ */
+export function createHITLTool<TSchema extends z.ZodObject<z.ZodRawShape>>(
+  config: HITLConfig<TSchema>,
+): Tool {
+  return tool({
+    description: `${config.description} (Requires approval${config.riskLevel ? ` - ${config.riskLevel} risk` : ''})`,
+    inputSchema: config.parameters,
+    execute: async params => {
+      const typedParams = params as z.infer<TSchema>;
+      // Request approval
+      const decision = await config.requestApproval(typedParams);
+
+      if (!decision.approved) {
+        if (config.onDenied) {
+          await config.onDenied(typedParams, decision.reason);
+        }
+        return {
+          success: false,
+          error: 'Action denied by user',
+          reason: decision.reason,
+        };
+      }
+
+      // Use modified params if provided
+      const finalParams = decision.modifiedParams
+        ? { ...params, ...decision.modifiedParams }
+        : params;
+
+      // Execute with approved params
+      const result = await config.execute(finalParams as z.infer<TSchema>);
+      return { success: true, result };
+    },
+  });
+}
+
+/**
+ * Approval policy for automatic approval decisions.
+ */
+export interface ApprovalPolicy {
+  /** Policy name */
+  name: string;
+  /** Tools this policy applies to */
+  toolPatterns: string[];
+  /** Conditions for auto-approval */
+  conditions: ApprovalCondition[];
+  /** Maximum risk level to auto-approve */
+  maxRiskLevel: 'low' | 'medium' | 'high';
+}
+
+/**
+ * Condition for automatic approval.
+ */
+export interface ApprovalCondition {
+  /** Parameter path (e.g., 'path', 'options.force') */
+  paramPath: string;
+  /** Operator for comparison */
+  operator: 'equals' | 'contains' | 'matches' | 'lessThan' | 'greaterThan';
+  /** Value to compare against */
+  value: unknown;
+}
+
+/**
+ * Creates an approval policy checker.
+ *
+ * @param policies - Array of approval policies
+ * @returns Function to check if params satisfy any policy
+ *
+ * @example
+ * ```ts
+ * const checkPolicy = createPolicyChecker([
+ *   {
+ *     name: 'safe-paths',
+ *     toolPatterns: ['deleteFile', 'moveFile'],
+ *     conditions: [
+ *       { paramPath: 'path', operator: 'contains', value: '/tmp/' },
+ *     ],
+ *     maxRiskLevel: 'medium',
+ *   },
+ * ]);
+ *
+ * const canAutoApprove = checkPolicy('deleteFile', { path: '/tmp/test.txt' }, 'low');
+ * ```
+ */
+export function createPolicyChecker(policies: ApprovalPolicy[]) {
+  return function checkPolicy(
+    toolName: string,
+    params: Record<string, unknown>,
+    riskLevel: 'low' | 'medium' | 'high' | 'critical',
+  ): { approved: boolean; policy?: string } {
+    const riskOrder = { low: 1, medium: 2, high: 3, critical: 4 };
+    const currentRisk = riskOrder[riskLevel];
+
+    for (const policy of policies) {
+      // Check if policy applies to this tool
+      const matchesTool = policy.toolPatterns.some(pattern => {
+        if (pattern === '*') return true;
+        if (pattern.endsWith('*')) {
+          return toolName.startsWith(pattern.slice(0, -1));
+        }
+        return toolName === pattern;
+      });
+
+      if (!matchesTool) continue;
+
+      // Check risk level
+      const policyMaxRisk = riskOrder[policy.maxRiskLevel];
+      if (currentRisk > policyMaxRisk) continue;
+
+      // Check all conditions
+      const allConditionsMet = policy.conditions.every(condition => {
+        const value = getNestedValue(params, condition.paramPath);
+        return evaluateCondition(value, condition.operator, condition.value);
+      });
+
+      if (allConditionsMet) {
+        return { approved: true, policy: policy.name };
+      }
+    }
+
+    return { approved: false };
+  };
+}
+
+/**
+ * Gets a nested value from an object using dot notation.
+ */
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  return path.split('.').reduce<unknown>((curr, key) => {
+    if (curr && typeof curr === 'object' && key in curr) {
+      return (curr as Record<string, unknown>)[key];
+    }
+    return undefined;
+  }, obj);
+}
+
+/**
+ * Evaluates a condition against a value.
+ */
+function evaluateCondition(
+  value: unknown,
+  operator: ApprovalCondition['operator'],
+  target: unknown,
+): boolean {
+  switch (operator) {
+    case 'equals':
+      return value === target;
+    case 'contains':
+      return typeof value === 'string' && typeof target === 'string' && value.includes(target);
+    case 'matches':
+      return (
+        typeof value === 'string' && typeof target === 'string' && new RegExp(target).test(value)
+      );
+    case 'lessThan':
+      return typeof value === 'number' && typeof target === 'number' && value < target;
+    case 'greaterThan':
+      return typeof value === 'number' && typeof target === 'number' && value > target;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Creates a batch approval request for multiple tool calls.
+ *
+ * @param requests - Array of tool call requests
+ * @param batchApproval - Function to approve batch
+ * @returns Filtered array of approved requests
+ */
+export async function batchApproval<
+  T extends { toolName: string; params: Record<string, unknown> },
+>(
+  requests: T[],
+  batchApprovalFn: (requests: T[]) => Promise<{ approved: boolean; approvedIndices: number[] }>,
+): Promise<T[]> {
+  const result = await batchApprovalFn(requests);
+
+  if (!result.approved) {
+    return [];
+  }
+
+  return result.approvedIndices
+    .map(i => requests[i])
+    .filter((item): item is T => item !== undefined);
+}

package/src/tools/advanced/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Advanced tool utilities - LLM-powered, HITL, caching, generators.
+ * @module @od-oneapp/ai-platform/tools/advanced
+ */
+
+export * from './llm-tool';
+export * from './hitl';
+export * from './caching';
+export * from './generator';