@od-oneapp/ai-platform 0.1.0

package/src/tools/approval/with-approval.ts

@@ -0,0 +1,366 @@
+/**
+ * Core approval logic for the Human-In-The-Loop (HITL) Approval System.
+ * Provides tool wrapping, approval checking, handler creation, and middleware.
+ */
+
+import { logInfo } from '@repo/shared/logs';
+
+import type {
+  ApprovalBackend,
+  ApprovalHandler,
+  ApprovalOptions,
+  ApprovalQueue,
+  ApprovalRequest,
+  ApprovalResult,
+  ApprovalRule,
+  QueueStats,
+  Tool,
+} from './types';
+
+/**
+ * Tool wrapper that requires approval
+ *
+ * @param tool - Tool to wrap
+ * @param options - Approval options
+ * @returns Wrapped tool that requires approval
+ *
+ * @example
+ * ```typescript
+ * const deleteTool = {
+ *   name: 'deleteDatabase',
+ *   execute: async (args) => { ... }
+ * };
+ *
+ * const approvedDeleteTool = withApproval(deleteTool, {
+ *   rules: [{
+ *     toolPattern: 'delete*',
+ *     priority: 'critical',
+ *     reason: 'Database operations require approval'
+ *   }],
+ *   handler: myApprovalHandler
+ * });
+ * ```
+ */
+export function withApproval<T = unknown>(tool: Tool<T>, options?: ApprovalOptions): Tool<T> {
+  const logger = options?.enableLogging ? logInfo : () => {};
+  let approvalQueue: ApprovalQueue | null = null;
+
+  return {
+    name: tool.name,
+    description: tool.description,
+
+    async execute(args: Record<string, unknown>): Promise<T> {
+      // Check if approval is needed
+      const needsApprovalResult = needsApproval(tool.name, args, options?.rules);
+
+      if (!needsApprovalResult.required) {
+        logger(`[Approval] Tool '${tool.name}' does not require approval`);
+        return tool.execute(args);
+      }
+
+      logger(`[Approval] Tool '${tool.name}' requires approval`);
+
+      // Create approval request
+      const requestId = generateRequestId();
+      const request: ApprovalRequest = {
+        id: requestId,
+        toolName: tool.name,
+        args,
+        reason: needsApprovalResult.reason,
+        context: needsApprovalResult.context,
+        requestedAt: new Date(),
+        expiresAt: options?.defaultExpirationMs
+          ? new Date(Date.now() + options.defaultExpirationMs)
+          : undefined,
+        priority: needsApprovalResult.priority || options?.defaultPriority || 'normal',
+        status: 'pending',
+      };
+
+      // Store in queue
+      approvalQueue =
+        approvalQueue || (options?.backend ? createQueueFromBackend(options.backend) : null);
+      if (approvalQueue) {
+        await approvalQueue.enqueue(request);
+        logger(`[Approval] Request ${requestId} enqueued`);
+      }
+
+      // Request approval from handler
+      const handler = options?.handler;
+      if (!handler) {
+        throw new Error(`No approval handler configured for tool '${tool.name}'`);
+      }
+
+      const result = await handler.requestApproval(request);
+
+      if (!result.approved) {
+        logger(`[Approval] Request ${requestId} rejected: ${result.reason}`);
+        throw new Error(`Approval denied for tool '${tool.name}': ${result.reason}`);
+      }
+
+      logger(`[Approval] Request ${requestId} approved`);
+
+      // Apply modifications if any
+      const finalArgs = result.modifications ? { ...args, ...result.modifications } : args;
+
+      // Notify approval
+      try {
+        await handler.notifyApproval(request, result);
+      } catch (error) {
+        logger(`[Approval] Notification failed: ${error}`);
+      }
+
+      // Update queue status
+      if (approvalQueue) {
+        await approvalQueue.updateStatus(requestId, 'approved', result);
+      }
+
+      // Execute tool with approved args
+      return tool.execute(finalArgs);
+    },
+
+    validate: tool.validate,
+  };
+}
+
+/**
+ * Check if a tool needs approval based on rules
+ *
+ * @param toolName - Name of the tool
+ * @param args - Tool arguments
+ * @param rules - Approval rules
+ * @returns Object indicating if approval is needed and metadata
+ *
+ * @example
+ * ```typescript
+ * const result = needsApproval('deleteUser', { userId: '123' }, [
+ *   {
+ *     toolPattern: 'delete*',
+ *     priority: 'critical',
+ *     reason: 'Delete operations require approval'
+ *   }
+ * ]);
+ *
+ * if (result.required) {
+ *   logInfo(`Approval needed: ${result.reason}`);
+ * }
+ * ```
+ */
+export function needsApproval(
+  toolName: string,
+  args: unknown,
+  rules?: ApprovalRule[],
+): {
+  required: boolean;
+  reason: string;
+  priority?: ApprovalRequest['priority'];
+  context?: Record<string, unknown>;
+} {
+  if (!rules || rules.length === 0) {
+    return { required: false, reason: 'No approval rules defined' };
+  }
+
+  for (const rule of rules) {
+    const matches = matchPattern(toolName, rule.toolPattern);
+    if (!matches) continue;
+
+    // Check condition if provided
+    if (rule.condition && !rule.condition(args)) {
+      continue;
+    }
+
+    // Tool matches this rule
+    const reason =
+      typeof rule.reason === 'function'
+        ? rule.reason(args)
+        : rule.reason || `Tool '${toolName}' requires approval`;
+
+    return {
+      required: true,
+      reason,
+      priority: rule.priority,
+      context: { toolName, argsPreview: JSON.stringify(args).substring(0, 200) },
+    };
+  }
+
+  return { required: false, reason: 'No matching approval rules' };
+}
+
+/**
+ * Create a basic approval handler (stub for user implementation)
+ *
+ * @param implementation - Custom implementation
+ * @returns ApprovalHandler
+ *
+ * @example
+ * ```typescript
+ * const handler = createApprovalHandler({
+ *   requestApproval: async (request) => {
+ *     // Notify user via email/Slack/etc
+ *     await notifyUser(request);
+ *     // Wait for approval...
+ *     return { approved: true, approvedBy: 'user@example.com' };
+ *   }
+ * });
+ * ```
+ */
+export function createApprovalHandler(implementation: Partial<ApprovalHandler>): ApprovalHandler {
+  return {
+    requestApproval: implementation.requestApproval || (async () => ({ approved: false })),
+    notifyApproval: implementation.notifyApproval || (async () => {}),
+  };
+}
+
+/**
+ * Creates a reusable tool-approval wrapper from a fixed set of approval options.
+ * Returns a function that wraps any tool with approval gates using {@link withApproval}.
+ *
+ * @param options - Approval options (rules, handler, logging).
+ * @returns A function that wraps a {@link Tool} with approval logic.
+ *
+ * @example
+ * ```typescript
+ * const wrapper = createToolApprovalWrapper({
+ *   rules: approvalRules,
+ *   handler: approvalHandler,
+ *   enableLogging: true
+ * });
+ *
+ * // Wrap each tool with the same approval options
+ * tools = tools.map(tool => wrapper(tool));
+ * ```
+ */
+export function createToolApprovalWrapper(options: ApprovalOptions) {
+  return function toolApprovalWrapper<T>(tool: Tool<T>): Tool<T> {
+    return withApproval(tool, options);
+  };
+}
+
+// ============================================================================
+// INTERNAL HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Generate a unique approval request ID
+ */
+function generateRequestId(): string {
+  return `apr_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+
+/**
+ * Match tool name against pattern (supports wildcards)
+ */
+function matchPattern(toolName: string, pattern: string | RegExp): boolean {
+  if (pattern instanceof RegExp) {
+    return pattern.test(toolName);
+  }
+
+  // Convert wildcard pattern to regex
+  const regexPattern = pattern.replace(/\./g, '\\.').replace(/\*/g, '.*').replace(/\?/g, '.');
+
+  return new RegExp(`^${regexPattern}$`).test(toolName);
+}
+
+/**
+ * Create queue from backend
+ */
+export function createQueueFromBackend(
+  backend: ApprovalBackend,
+  options?: { enableLogging?: boolean },
+): ApprovalQueue {
+  const logger = options?.enableLogging ? logInfo : () => {};
+  const processedRequests = new Map<string, ApprovalResult>();
+
+  return {
+    async enqueue(request: ApprovalRequest): Promise<void> {
+      logger(`[Queue] Enqueuing request ${request.id}`);
+      await backend.store(request);
+    },
+
+    async dequeue(): Promise<ApprovalRequest | null> {
+      const pending = await backend.listPending();
+      if (pending.length === 0) return null;
+
+      // Sort by priority (critical > high > normal > low) and requestedAt
+      pending.sort((a, b) => {
+        const priorityOrder: Record<string, number> = {
+          critical: 0,
+          high: 1,
+          normal: 2,
+          low: 3,
+        };
+        const defaultPriority = priorityOrder.normal ?? 2;
+        const aPriority = priorityOrder[a.priority ?? 'normal'];
+        const bPriority = priorityOrder[b.priority ?? 'normal'];
+        const aValue = typeof aPriority === 'number' ? aPriority : defaultPriority;
+        const bValue = typeof bPriority === 'number' ? bPriority : defaultPriority;
+
+        if (aValue !== bValue) return aValue - bValue;
+        return a.requestedAt.getTime() - b.requestedAt.getTime();
+      });
+
+      return pending[0] ?? null;
+    },
+
+    async get(requestId: string): Promise<ApprovalRequest | null> {
+      return backend.get(requestId);
+    },
+
+    async listPending(limit = 100, offset = 0): Promise<ApprovalRequest[]> {
+      const pending = await backend.listPending();
+      return pending.slice(offset, offset + limit);
+    },
+
+    async updateStatus(
+      requestId: string,
+      status: ApprovalRequest['status'],
+      result?: ApprovalResult,
+    ): Promise<void> {
+      await backend.updateStatus(requestId, status);
+      if (result) {
+        processedRequests.set(requestId, result);
+      }
+    },
+
+    async remove(requestId: string): Promise<void> {
+      await backend.delete(requestId);
+      processedRequests.delete(requestId);
+    },
+
+    async getStats(): Promise<QueueStats> {
+      const pending = await backend.listPending();
+      const byPriority: Record<string, number> = {
+        critical: 0,
+        high: 0,
+        normal: 0,
+        low: 0,
+      };
+
+      let oldestTime = Date.now();
+      for (const req of pending) {
+        const priority = req.priority ?? 'normal';
+        const key = priority in byPriority ? priority : 'normal';
+        byPriority[key] = (byPriority[key] ?? 0) + 1;
+        oldestTime = Math.min(oldestTime, req.requestedAt.getTime());
+      }
+
+      const oldestRequestAgeMs = pending.length > 0 ? Date.now() - oldestTime : undefined;
+      const totalProcessed = processedRequests.size;
+      const approvalRate =
+        totalProcessed > 0
+          ? Array.from(processedRequests.values()).filter(r => r.approved).length / totalProcessed
+          : 0;
+
+      return {
+        totalPending: pending.length,
+        byPriority,
+        oldestRequestAgeMs,
+        totalProcessed,
+        approvalRate,
+      };
+    },
+
+    async clearExpired(): Promise<number> {
+      return backend.clearExpired();
+    },
+  };
+}

package/src/tools/artifacts/artifact-tools.ts

@@ -0,0 +1,273 @@
+/**
+ * @fileoverview Artifact-specific tool factories.
+ * @module @od-oneapp/ai-platform/tools/artifacts
+ */
+
+import { z } from 'zod';
+
+import { tool } from '../../shared';
+
+import type { SDKTool as Tool } from '../../shared';
+
+/**
+ * Artifact types supported by the system.
+ */
+export const ArtifactType = z.enum([
+  'document',
+  'code',
+  'presentation',
+  'spreadsheet',
+  'canvas',
+  'image',
+  'diagram',
+]);
+
+export type ArtifactType = z.infer<typeof ArtifactType>;
+
+/**
+ * Base artifact metadata.
+ */
+export const ArtifactMetadataSchema = z.object({
+  id: z.string(),
+  type: ArtifactType,
+  title: z.string(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  version: z.number(),
+});
+
+export type ArtifactMetadata = z.infer<typeof ArtifactMetadataSchema>;
+
+/**
+ * Artifact operation result.
+ */
+export interface ArtifactOperationResult<T = unknown> {
+  success: boolean;
+  artifact?: ArtifactMetadata;
+  data?: T;
+  error?: string;
+}
+
+/**
+ * Handler type for artifact operations.
+ */
+export type ArtifactHandler<TInput, TOutput> = (
+  input: TInput,
+) => Promise<ArtifactOperationResult<TOutput>>;
+
+/**
+ * Creates a tool for creating artifacts.
+ *
+ * @param config - Creation tool configuration
+ * @returns AI SDK tool
+ *
+ * @example
+ * ```ts
+ * const createDocTool = createArtifactCreationTool({
+ *   artifactType: 'document',
+ *   description: 'Create a new document',
+ *   handler: async ({ title, content }) => {
+ *     const doc = await createDocument({ title, content });
+ *     return { success: true, artifact: doc.metadata, data: doc };
+ *   },
+ * });
+ * ```
+ */
+export function createArtifactCreationTool<TContent>(config: {
+  artifactType: ArtifactType;
+  description: string;
+  contentSchema?: z.ZodType<TContent>;
+  handler: ArtifactHandler<{ title: string; content: TContent }, unknown>;
+}): Tool {
+  const contentSchema = config.contentSchema ?? z.unknown();
+
+  return tool({
+    description: config.description,
+    inputSchema: z.object({
+      title: z.string().describe('Artifact title'),
+      content: contentSchema.describe('Artifact content'),
+    }),
+    execute: async input => {
+      return config.handler(input as { title: string; content: TContent });
+    },
+  });
+}
+
+/**
+ * Creates a tool for updating artifacts.
+ *
+ * @param config - Update tool configuration
+ * @returns AI SDK tool
+ */
+export function createArtifactUpdateTool<TUpdate>(config: {
+  artifactType: ArtifactType;
+  description: string;
+  updateSchema?: z.ZodType<TUpdate>;
+  handler: ArtifactHandler<{ id: string; update: TUpdate }, unknown>;
+}): Tool {
+  const updateSchema = config.updateSchema ?? z.unknown();
+
+  return tool({
+    description: config.description,
+    inputSchema: z.object({
+      id: z.string().describe('Artifact ID'),
+      update: updateSchema.describe('Update payload'),
+    }),
+    execute: async input => {
+      return config.handler(input as { id: string; update: TUpdate });
+    },
+  });
+}
+
+/**
+ * Creates a tool for reading artifacts.
+ *
+ * @param config - Read tool configuration
+ * @returns AI SDK tool
+ */
+export function createArtifactReadTool(config: {
+  artifactType: ArtifactType;
+  description: string;
+  handler: ArtifactHandler<{ id: string }, unknown>;
+}): Tool {
+  return tool({
+    description: config.description,
+    inputSchema: z.object({
+      id: z.string().describe('Artifact ID'),
+    }),
+    execute: async input => {
+      return config.handler(input as { id: string });
+    },
+  });
+}
+
+/**
+ * Creates a tool for deleting artifacts.
+ *
+ * @param config - Delete tool configuration
+ * @returns AI SDK tool
+ */
+export function createArtifactDeleteTool(config: {
+  artifactType: ArtifactType;
+  description: string;
+  handler: ArtifactHandler<{ id: string }, void>;
+}): Tool {
+  return tool({
+    description: config.description,
+    inputSchema: z.object({
+      id: z.string().describe('Artifact ID'),
+    }),
+    execute: async input => {
+      return config.handler(input as { id: string });
+    },
+  });
+}
+
+/**
+ * Creates a complete CRUD tool set for an artifact type.
+ *
+ * @param config - CRUD configuration
+ * @returns Record of CRUD tools
+ *
+ * @example
+ * ```ts
+ * const docTools = createArtifactCRUDTools({
+ *   artifactType: 'document',
+ *   handlers: {
+ *     create: async ({ title, content }) => createDoc(title, content),
+ *     read: async ({ id }) => readDoc(id),
+ *     update: async ({ id, update }) => updateDoc(id, update),
+ *     delete: async ({ id }) => deleteDoc(id),
+ *   },
+ * });
+ * ```
+ */
+export function createArtifactCRUDTools<TContent, TUpdate>(config: {
+  artifactType: ArtifactType;
+  contentSchema?: z.ZodType<TContent>;
+  updateSchema?: z.ZodType<TUpdate>;
+  handlers: {
+    create: ArtifactHandler<{ title: string; content: TContent }, unknown>;
+    read: ArtifactHandler<{ id: string }, unknown>;
+    update: ArtifactHandler<{ id: string; update: TUpdate }, unknown>;
+    delete: ArtifactHandler<{ id: string }, void>;
+  };
+}): Record<string, Tool> {
+  const { artifactType, handlers } = config;
+  const typeLabel = artifactType.charAt(0).toUpperCase() + artifactType.slice(1);
+
+  return {
+    [`create${typeLabel}`]: createArtifactCreationTool({
+      artifactType,
+      description: `Create a new ${artifactType}`,
+      contentSchema: config.contentSchema,
+      handler: handlers.create,
+    }),
+    [`read${typeLabel}`]: createArtifactReadTool({
+      artifactType,
+      description: `Read a ${artifactType} by ID`,
+      handler: handlers.read,
+    }),
+    [`update${typeLabel}`]: createArtifactUpdateTool({
+      artifactType,
+      description: `Update a ${artifactType}`,
+      updateSchema: config.updateSchema,
+      handler: handlers.update,
+    }),
+    [`delete${typeLabel}`]: createArtifactDeleteTool({
+      artifactType,
+      description: `Delete a ${artifactType}`,
+      handler: handlers.delete,
+    }),
+  };
+}
+
+/**
+ * Creates tools for artifact versioning.
+ */
+export function createVersioningTools(config: {
+  artifactType: ArtifactType;
+  handlers: {
+    listVersions: (id: string) => Promise<ArtifactMetadata[]>;
+    getVersion: (id: string, version: number) => Promise<unknown>;
+    revertToVersion: (id: string, version: number) => Promise<ArtifactOperationResult>;
+  };
+}): Record<string, Tool> {
+  const { artifactType, handlers } = config;
+  const typeLabel = artifactType.charAt(0).toUpperCase() + artifactType.slice(1);
+
+  return {
+    [`list${typeLabel}Versions`]: tool({
+      description: `List all versions of a ${artifactType}`,
+      inputSchema: z.object({
+        id: z.string().describe('Artifact ID'),
+      }),
+      execute: async input => {
+        const { id } = input;
+        return handlers.listVersions(id);
+      },
+    }),
+    [`get${typeLabel}Version`]: tool({
+      description: `Get a specific version of a ${artifactType}`,
+      inputSchema: z.object({
+        id: z.string().describe('Artifact ID'),
+        version: z.number().describe('Version number'),
+      }),
+      execute: async input => {
+        const { id, version } = input;
+        return handlers.getVersion(id, version);
+      },
+    }),
+    [`revert${typeLabel}`]: tool({
+      description: `Revert a ${artifactType} to a previous version`,
+      inputSchema: z.object({
+        id: z.string().describe('Artifact ID'),
+        version: z.number().describe('Version to revert to'),
+      }),
+      execute: async input => {
+        const { id, version } = input;
+        return handlers.revertToVersion(id, version);
+      },
+    }),
+  };
+}

package/src/tools/artifacts/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Artifact-specific tool utilities.
+ * @module @od-oneapp/ai-platform/tools/artifacts
+ */
+
+export * from './artifact-tools';