@od-oneapp/ai-platform 0.1.0

package/src/tools/compliance/tool-wrapper.ts

@@ -0,0 +1,306 @@
+/**
+ * @fileoverview Tool Wrapper for Compliance
+ * Tool Wrapper for Compliance
+ * Wraps AI SDK tools with audit logging, ABAC, and approval workflows
+ */
+
+import { logInfo } from '@repo/shared/logs';
+
+
+// Note: Tool types simplified due to AI SDK v6 API changes
+import { logToolCall } from '../../governance/audit/audit-logger';
+import { evaluatePolicy } from '../../governance/compliance/abac/policy-engine';
+import { getApprovalQueue } from '../../governance/compliance/approval/compliance-approval-queue';
+import { tool } from '../../shared';
+
+import type { RiskLevel } from '../../governance/compliance/schemas';
+import type { ABACContext } from '../../governance/compliance/types';
+import type {
+  SDKTool as Tool,
+  SDKToolExecutionOptions as ToolExecutionOptions,
+} from '../../shared';
+
+type ToolRiskLevel = RiskLevel | 'critical';
+
+/**
+ * Tool compliance options
+ */
+interface ToolComplianceOptions {
+  riskLevel?: ToolRiskLevel;
+  enableApproval?: boolean;
+  requiresApproval?: boolean;
+  enableAuditLogging?: boolean;
+  requireExplicitConsent?: boolean;
+  abacResource?: string;
+  auditAction?: string;
+  timeout?: number;
+}
+
+/**
+ * Risk level configuration
+ */
+const RISK_LEVEL_CONFIG = {
+  low: { requiresApproval: false, auditLevel: 'info' as const, maxExecutionTime: 5000 },
+  medium: { requiresApproval: false, auditLevel: 'warn' as const, maxExecutionTime: 10000 },
+  high: { requiresApproval: true, auditLevel: 'warn' as const, maxExecutionTime: 30000 },
+  critical: { requiresApproval: true, auditLevel: 'error' as const, maxExecutionTime: 60000 },
+};
+
+/**
+ * Wrap a tool with compliance features
+ *
+ * @param baseTool - The base CoreTool to wrap
+ * @param options - Compliance options
+ * @param abacContext - ABAC context for access control (optional)
+ * @returns Wrapped tool with compliance features
+ *
+ * @example
+ * ```ts
+ * const sendEmailTool = wrapToolWithCompliance(
+ *   tool({
+ *     description: 'Send an email',
+ *     inputSchema: z.object({ to: z.string(), body: z.string() }),
+ *     execute: async ({ to, body }) => { ... }
+ *   }),
+ *   {
+ *     riskLevel: 'high',
+ *     requiresApproval: true,
+ *     abacResource: 'email_service',
+ *     auditAction: 'send_email',
+ *   }
+ * );
+ * ```
+ */
+export function wrapToolWithCompliance<TInput, TOutput>(
+  baseTool: Tool<TInput, TOutput>,
+  options: ToolComplianceOptions,
+  abacContext?: ABACContext,
+): Tool<TInput, TOutput> {
+  const { requiresApproval = false, enableApproval, riskLevel, abacResource, timeout } = options;
+
+  const effectiveRiskLevel: ToolRiskLevel = riskLevel ?? 'medium';
+  const riskConfig = RISK_LEVEL_CONFIG[effectiveRiskLevel];
+  const effectiveTimeout = timeout ?? riskConfig.maxExecutionTime;
+  const effectiveRequiresApproval =
+    requiresApproval || enableApproval === true || riskConfig.requiresApproval;
+  const normalizedRiskLevel: RiskLevel =
+    effectiveRiskLevel === 'critical' ? 'high' : effectiveRiskLevel;
+
+  const wrappedTool = { ...baseTool };
+  wrappedTool.execute = async (args: TInput, toolExecutionOptions: ToolExecutionOptions) => {
+    const startTime = Date.now();
+    const toolName = baseTool.description ?? 'unknown_tool';
+    const actor = abacContext?.actor.id || 'system';
+
+    try {
+      // Step 1: ABAC Check
+      if (abacContext) {
+        const resourceType = abacResource ?? toolName;
+        const resourceId = abacResource ?? toolName;
+        const abacResult = await evaluatePolicy(
+          abacContext,
+          {
+            id: resourceId,
+            type: resourceType,
+            sensitivity:
+              effectiveRiskLevel === 'critical' || effectiveRiskLevel === 'high'
+                ? 'restricted'
+                : 'confidential',
+          },
+          'execute',
+        );
+
+        if (!abacResult.decision.allowed) {
+          const error = new Error(
+            `Access denied: ${abacResult.decision.reason ?? 'Policy violation'}`,
+          );
+
+          // Log denial
+          await logToolCall(
+            actor,
+            toolName,
+            args,
+            { error: error.message, abac_decision: abacResult.decision },
+            {
+              riskLevel: normalizedRiskLevel,
+              abacDenied: true,
+            },
+          );
+
+          throw error;
+        }
+      }
+
+      // Step 2: Approval Workflow (if required)
+      if (effectiveRequiresApproval) {
+        const queue = getApprovalQueue();
+
+        logInfo(`[TOOL APPROVAL REQUIRED] ${toolName}`, {
+          riskLevel: normalizedRiskLevel,
+          args,
+          toolName,
+        });
+
+        const approvalArgs =
+          typeof args === 'object' && args !== null
+            ? (args as Record<string, unknown>)
+            : { value: args };
+
+        const decision = await queue.submitForApproval(
+          toolName,
+          approvalArgs,
+          actor,
+          normalizedRiskLevel,
+          effectiveTimeout,
+        );
+
+        if (!decision.approved) {
+          const error = new Error(
+            `Tool execution denied: ${decision.reason ?? 'Approval rejected'}`,
+          );
+
+          await logToolCall(
+            actor,
+            toolName,
+            args,
+            { error: error.message, approval_decision: decision },
+            {
+              riskLevel: normalizedRiskLevel,
+              approvalDenied: true,
+            },
+          );
+
+          throw error;
+        }
+
+        // Log approval
+        await logToolCall(
+          actor,
+          toolName,
+          args,
+          { approval_decision: decision },
+          {
+            riskLevel: normalizedRiskLevel,
+            approvalGranted: true,
+          },
+        );
+      }
+
+      // Step 3: Execute the actual tool with timeout
+      if (!baseTool.execute) {
+        throw new Error(`Tool ${toolName} does not define an execute function`);
+      }
+      const result = baseTool.execute(args, toolExecutionOptions);
+      if (isAsyncIterable(result)) {
+        throw new Error('Compliance wrapper does not support streaming tool outputs');
+      }
+      const resolvedResult = await executeWithTimeout(
+        Promise.resolve(result),
+        effectiveTimeout,
+        `Tool ${toolName} execution timed out after ${effectiveTimeout}ms`,
+      );
+
+      // Step 4: Audit log successful execution
+      const executionTime = Date.now() - startTime;
+      await logToolCall(actor, toolName, args, resolvedResult, {
+        riskLevel: normalizedRiskLevel,
+        executionTimeMs: executionTime,
+        success: true,
+      });
+
+      return resolvedResult;
+    } catch (error) {
+      // Log failed execution
+      const executionTime = Date.now() - startTime;
+      await logToolCall(
+        actor,
+        toolName,
+        args,
+        {
+          error: error instanceof Error ? error.message : 'Unknown error',
+        },
+        {
+          riskLevel: normalizedRiskLevel,
+          executionTimeMs: executionTime,
+          success: false,
+        },
+      );
+
+      throw error;
+    }
+  };
+  return wrappedTool;
+}
+
+/**
+ * Execute a promise with timeout
+ */
+async function executeWithTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  timeoutMessage: string,
+): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((resolve, reject) => {
+      void resolve;
+      setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+    }),
+  ]);
+}
+
+/**
+ * Create a high-risk tool with built-in approval requirement
+ */
+export function createHighRiskTool<TInput extends Record<string, unknown>, TOutput>(
+  config: Tool<TInput, TOutput>,
+  complianceOptions: Omit<ToolComplianceOptions, 'requiresApproval'>,
+  abacContext?: ABACContext,
+): Tool<TInput, TOutput> {
+  const baseTool = tool(config);
+
+  return wrapToolWithCompliance(
+    baseTool,
+    {
+      ...complianceOptions,
+      requiresApproval: true,
+    },
+    abacContext,
+  );
+}
+
+/**
+ * Batch wrap multiple tools
+ */
+export function wrapTools<T extends Record<string, Tool<unknown, unknown>>>(
+  tools: T,
+  defaultOptions: Partial<ToolComplianceOptions>,
+  abacContext?: ABACContext,
+): T {
+  const wrappedTools = {} as T;
+
+  for (const name of Object.keys(tools) as Array<keyof T>) {
+    const toolInstance = tools[name];
+    if (!toolInstance) {
+      continue;
+    }
+    wrappedTools[name] = wrapToolWithCompliance(
+      toolInstance,
+      {
+        riskLevel: 'medium',
+        abacResource: String(name),
+        auditAction: String(name),
+        ...defaultOptions,
+      },
+      abacContext,
+    ) as T[typeof name];
+  }
+
+  return wrappedTools;
+}
+
+function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+  return (
+    value != null && typeof (value as AsyncIterable<unknown>)[Symbol.asyncIterator] === 'function'
+  );
+}

package/src/tools/computer/index.ts

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview Computer Use Tool
+ *
+ * Provides the 'computer' tool for Anthropic's beta computer use capability.
+ * WARNING: This is a high-risk capability. Ensure strict sandboxing.
+ *
+ * @module @od-oneapp/ai-platform/computer/index
+ */
+
+import { z } from 'zod';
+
+import { tool } from '../../shared';
+
+import type { ComputerAction, ComputerResult } from './types';
+
+// Re-export types
+export * from './types';
+
+/**
+ * Configuration for the computer tool.
+ */
+export interface ComputerToolOptions {
+  /** Screen width in pixels. */
+  displayWidth: number;
+  /** Screen height in pixels. */
+  displayHeight: number;
+  /** Display number (for multi-monitor setups). */
+  displayNumber?: number;
+  /**
+   * Executor function that performs the actual OS interaction.
+   * You must inject a safe implementation (e.g. via Docker/VM).
+   */
+  execute: (
+    action: ComputerAction,
+    coordinate?: [number, number],
+    text?: string,
+  ) => Promise<ComputerResult>;
+}
+
+/**
+ * Creates a 'computer' tool compatible with Anthropic Beta.
+ *
+ * @param options - Configuration including the potentially dangerous executor.
+ * @returns The Vercel AI SDK tool definition.
+ */
+export const createComputerTool = (options: ComputerToolOptions) => {
+  return tool({
+    description: `computer_use_20241022 - interact with a computer screen.
+    Display: ${options.displayWidth}x${options.displayHeight} (Num: ${options.displayNumber ?? 0})
+    Available actions: key, type, cursor_position, mouse_move, left_click, etc.`,
+
+    inputSchema: z.object({
+      action: z.enum([
+        'key',
+        'type',
+        'mouse_move',
+        'left_click',
+        'left_click_drag',
+        'right_click',
+        'middle_click',
+        'double_click',
+        'screenshot',
+        'cursor_position',
+      ]),
+      coordinate: z.tuple([z.number(), z.number()]).optional().describe('(x, y) coordinates'),
+      text: z.string().optional().describe('Text to type or key sequence'),
+    }),
+
+    execute: async ({ action, coordinate, text }) => {
+      // Pass through to the injected executor
+      // The executor is responsible for safety checks and implementation
+      return options.execute(action as ComputerAction, coordinate, text);
+    },
+  });
+};
+
+/**
+ * Creates 'bash' tool for command line execution.
+ *
+ * @param executeBash - Injected executor for bash commands.
+ */
+export const createBashTool = (
+  executeBash: (command: string) => Promise<{ stdout: string; stderr: string; exitCode: number }>,
+) => {
+  return tool({
+    description:
+      'bash_20241022 - Execute bash commands. Use for file operations, running scripts, etc.',
+    inputSchema: z.object({
+      command: z.string().describe('The bash command to run'),
+    }),
+    execute: async ({ command }) => {
+      const result = await executeBash(command);
+      if (result.exitCode !== 0) {
+        return `Exit code ${result.exitCode}:\n${result.stderr}\n${result.stdout}`;
+      }
+      return result.stdout;
+    },
+  });
+};

package/src/tools/computer/types.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Computer Use Types
+ *
+ * Definitions for Anthropic's Computer Use (Beta) capability.
+ *
+ * @module @od-oneapp/ai-platform/computer/types
+ */
+
+/**
+ * Supported computer interaction actions.
+ */
+export type ComputerAction =
+  | 'key'
+  | 'type'
+  | 'mouse_move'
+  | 'left_click'
+  | 'left_click_drag'
+  | 'right_click'
+  | 'middle_click'
+  | 'double_click'
+  | 'screenshot'
+  | 'cursor_position';
+
+/**
+ * Input schema for the computer tool.
+ */
+export interface ComputerLayoutInput {
+  action: ComputerAction;
+  coordinate?: [number, number];
+  text?: string;
+}
+
+/**
+ * Result of a computer action.
+ */
+export interface ComputerResult {
+  output?: string;
+  error?: string;
+  base64_image?: string;
+  system?: string; // e.g. "display_num_1"
+}

package/src/tools/core/abort.ts

@@ -0,0 +1,202 @@
+/**
+ * @fileoverview Tool abort handling with AbortSignal support.
+ * @module @od-oneapp/ai-platform/tools/core
+ */
+
+import type { ToolHandler, ToolExecutionContext } from './factory';
+
+/**
+ * Error thrown when a tool execution is aborted.
+ */
+export class ToolAbortError extends Error {
+  readonly name = 'ToolAbortError';
+  readonly toolName: string;
+
+  constructor(toolName: string, message = 'Tool execution aborted') {
+    super(message);
+    this.toolName = toolName;
+  }
+}
+
+/**
+ * Options for abort-aware tool execution.
+ */
+export interface AbortOptions {
+  /** Timeout in milliseconds */
+  timeoutMs?: number;
+  /** Custom abort signal to combine with context signal */
+  signal?: AbortSignal;
+  /** Whether to throw on abort (default: true) */
+  throwOnAbort?: boolean;
+  /** Fallback value to return on abort (requires throwOnAbort: false) */
+  fallbackValue?: unknown;
+}
+
+/**
+ * Wraps a tool handler with abort signal support.
+ *
+ * @param handler - Original handler
+ * @param toolName - Tool name for error reporting
+ * @param options - Abort options
+ * @returns Abort-aware handler
+ *
+ * @example
+ * ```ts
+ * const abortableSearch = withAbortHandling(
+ *   async ({ query }, ctx) => searchDocs(query),
+ *   'search',
+ *   { timeoutMs: 5000 }
+ * );
+ * ```
+ */
+export function withAbortHandling<TInput, TOutput>(
+  handler: ToolHandler<TInput, TOutput>,
+  toolName: string,
+  options: AbortOptions = {},
+): ToolHandler<TInput, TOutput> {
+  return async (input, context) => {
+    const { timeoutMs, signal, throwOnAbort = true, fallbackValue } = options;
+
+    // Combine signals
+    const signals: AbortSignal[] = [];
+    if (context.abortSignal) signals.push(context.abortSignal);
+    if (signal) signals.push(signal);
+
+    // Create timeout signal if specified
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    if (timeoutMs) {
+      const controller = new AbortController();
+      timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+      signals.push(controller.signal);
+    }
+
+    // Create combined signal
+    const combinedSignal = signals.length > 0 ? combineAbortSignals(signals) : undefined;
+
+    // Check if already aborted
+    if (combinedSignal?.aborted) {
+      if (throwOnAbort) {
+        throw new ToolAbortError(toolName);
+      }
+      return fallbackValue as TOutput;
+    }
+
+    try {
+      // Create context with combined signal
+      const abortContext: ToolExecutionContext = {
+        ...context,
+        abortSignal: combinedSignal,
+      };
+
+      // Execute with abort race
+      return await raceWithAbort(
+        handler(input, abortContext),
+        combinedSignal,
+        toolName,
+        throwOnAbort,
+        fallbackValue as TOutput,
+      );
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    }
+  };
+}
+
+/**
+ * Combines multiple abort signals into one.
+ *
+ * @param signals - Array of abort signals
+ * @returns Combined abort signal
+ */
+export function combineAbortSignals(signals: AbortSignal[]): AbortSignal {
+  const controller = new AbortController();
+
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      return controller.signal;
+    }
+
+    signal.addEventListener(
+      'abort',
+      () => {
+        controller.abort(signal.reason);
+      },
+      { once: true },
+    );
+  }
+
+  return controller.signal;
+}
+
+/**
+ * Races a promise against an abort signal.
+ */
+async function raceWithAbort<T>(
+  promise: Promise<T>,
+  signal: AbortSignal | undefined,
+  toolName: string,
+  throwOnAbort: boolean,
+  fallbackValue: T,
+): Promise<T> {
+  if (!signal) {
+    return promise;
+  }
+
+  return new Promise<T>((resolve, reject) => {
+    const abortHandler = () => {
+      if (throwOnAbort) {
+        reject(new ToolAbortError(toolName));
+      } else {
+        resolve(fallbackValue);
+      }
+    };
+
+    if (signal.aborted) {
+      abortHandler();
+      return;
+    }
+
+    signal.addEventListener('abort', abortHandler, { once: true });
+
+    void (async () => {
+      try {
+        const result = await promise;
+        signal.removeEventListener('abort', abortHandler);
+        resolve(result);
+      } catch (error) {
+        signal.removeEventListener('abort', abortHandler);
+        reject(error);
+      }
+    })();
+  });
+}
+
+/**
+ * Creates an abort controller that triggers after a timeout.
+ *
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Abort controller
+ *
+ * @example
+ * ```ts
+ * const controller = createTimeoutAbort(5000);
+ * await generateText({ ..., abortSignal: controller.signal });
+ * ```
+ */
+export function createTimeoutAbort(timeoutMs: number): AbortController {
+  const controller = new AbortController();
+  setTimeout(() => controller.abort('Timeout'), timeoutMs);
+  return controller;
+}
+
+/**
+ * Checks if an error is an abort error.
+ */
+export function isAbortError(error: unknown): error is ToolAbortError | DOMException {
+  if (error instanceof ToolAbortError) return true;
+  if (error instanceof DOMException && error.name === 'AbortError') return true;
+  return false;
+}