@elevasis/core 0.1.0

package/src/execution/engine/tools/platform/storage/index.ts

@@ -0,0 +1,370 @@
+/**
+ * Platform Storage Tools
+ *
+ * Factory functions for creating storage tools that interact with
+ * Supabase Storage for org-scoped file management.
+ *
+ * Usage:
+ * ```typescript
+ * const uploadTool = createStorageUploadTool({
+ *   name: 'save_proposal',
+ *   description: 'Save generated proposal PDF to storage'
+ * })
+ *
+ * const signedUrlTool = createStorageSignedUrlTool({
+ *   name: 'get_proposal_url',
+ *   description: 'Get signed URL for proposal download'
+ * })
+ * ```
+ */
+
+import type { Tool, ToolExecutionOptions } from '../../types'
+import { serviceUnavailable } from '../../types'
+import { getToolServices } from '../../registry'
+import {
+  StorageUploadInputSchema,
+  StorageUploadOutputSchema,
+  StorageSignedUrlInputSchema,
+  StorageSignedUrlOutputSchema,
+  StorageDownloadInputSchema,
+  StorageDownloadOutputSchema,
+  StorageDeleteInputSchema,
+  StorageDeleteOutputSchema,
+  StorageListInputSchema,
+  StorageListOutputSchema,
+  type StorageUploadInput,
+  type StorageUploadOutput,
+  type StorageSignedUrlInput,
+  type StorageSignedUrlOutput,
+  type StorageDownloadInput,
+  type StorageDownloadOutput,
+  type StorageDeleteInput,
+  type StorageDeleteOutput,
+  type StorageListInput,
+  type StorageListOutput,
+  type StorageToolConfig
+} from './types'
+
+/**
+ * Create storage upload tool for workflows/agents
+ *
+ * @param config - Tool configuration (name, description)
+ * @returns Tool that uploads files to org-scoped storage
+ *
+ * @example
+ * const uploadTool = createStorageUploadTool({
+ *   name: 'save_proposal',
+ *   description: 'Save generated proposal PDF to storage'
+ * })
+ *
+ * // In agent execution:
+ * await uploadTool.execute({
+ *   input: {
+ *     bucket: 'acquisition',
+ *     path: 'proposals/deal-123/proposal.pdf',
+ *     content: base64EncodedPdf,
+ *     contentType: 'application/pdf'
+ *   },
+ *   executionContext: context
+ * })
+ */
+export function createStorageUploadTool(config: StorageToolConfig): Tool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: StorageUploadInputSchema,
+    outputSchema: StorageUploadOutputSchema,
+
+    async execute(options: ToolExecutionOptions): Promise<StorageUploadOutput> {
+      if (!options.executionContext) {
+        throw serviceUnavailable('ExecutionContext', { tool: config.name, reason: 'organizationId required for multi-tenant isolation' })
+      }
+
+      const { storageService } = getToolServices()
+      if (!storageService) {
+        throw serviceUnavailable('StorageService', {
+          message: 'Ensure toolServicesRegistry.initialize() was called in apps/api/src/main.ts',
+          tool: config.name
+        })
+      }
+
+      const input = options.input as StorageUploadInput
+      const buffer = Buffer.from(input.content, 'base64')
+
+      const result = await storageService.upload({
+        organizationId: options.executionContext.organizationId,
+        bucket: input.bucket,
+        path: input.path,
+        file: buffer,
+        contentType: input.contentType,
+        upsert: input.upsert
+      })
+
+      return {
+        success: true,
+        path: result.path,
+        fullPath: result.fullPath
+      }
+    }
+  }
+}
+
+/**
+ * Create storage signed URL tool for workflows/agents
+ *
+ * @param config - Tool configuration (name, description)
+ * @returns Tool that creates signed URLs for temporary file access
+ *
+ * @example
+ * const signedUrlTool = createStorageSignedUrlTool({
+ *   name: 'get_proposal_url',
+ *   description: 'Get signed URL for proposal download'
+ * })
+ *
+ * // In agent execution:
+ * await signedUrlTool.execute({
+ *   input: {
+ *     bucket: 'acquisition',
+ *     path: 'proposals/deal-123/proposal.pdf',
+ *     expiresIn: 604800  // 7 days
+ *   },
+ *   executionContext: context
+ * })
+ */
+export function createStorageSignedUrlTool(config: StorageToolConfig): Tool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: StorageSignedUrlInputSchema,
+    outputSchema: StorageSignedUrlOutputSchema,
+
+    async execute(options: ToolExecutionOptions): Promise<StorageSignedUrlOutput> {
+      if (!options.executionContext) {
+        throw serviceUnavailable('ExecutionContext', { tool: config.name, reason: 'organizationId required for multi-tenant isolation' })
+      }
+
+      const { storageService } = getToolServices()
+      if (!storageService) {
+        throw serviceUnavailable('StorageService', {
+          message: 'Ensure toolServicesRegistry.initialize() was called in apps/api/src/main.ts',
+          tool: config.name
+        })
+      }
+
+      const input = options.input as StorageSignedUrlInput
+
+      const result = await storageService.createSignedUrl({
+        organizationId: options.executionContext.organizationId,
+        bucket: input.bucket,
+        path: input.path,
+        expiresIn: input.expiresIn
+      })
+
+      return {
+        success: true,
+        signedUrl: result.signedUrl,
+        expiresAt: result.expiresAt.toISOString()
+      }
+    }
+  }
+}
+
+/**
+ * Create storage download tool for workflows/agents
+ *
+ * @param config - Tool configuration (name, description)
+ * @returns Tool that downloads files from org-scoped storage
+ *
+ * @example
+ * const downloadTool = createStorageDownloadTool({
+ *   name: 'get_proposal_content',
+ *   description: 'Download proposal PDF content'
+ * })
+ *
+ * // In agent execution:
+ * await downloadTool.execute({
+ *   input: {
+ *     bucket: 'acquisition',
+ *     path: 'proposals/deal-123/proposal.pdf'
+ *   },
+ *   executionContext: context
+ * })
+ */
+export function createStorageDownloadTool(config: StorageToolConfig): Tool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: StorageDownloadInputSchema,
+    outputSchema: StorageDownloadOutputSchema,
+
+    async execute(options: ToolExecutionOptions): Promise<StorageDownloadOutput> {
+      if (!options.executionContext) {
+        throw serviceUnavailable('ExecutionContext', { tool: config.name, reason: 'organizationId required for multi-tenant isolation' })
+      }
+
+      const { storageService } = getToolServices()
+      if (!storageService) {
+        throw serviceUnavailable('StorageService', {
+          message: 'Ensure toolServicesRegistry.initialize() was called in apps/api/src/main.ts',
+          tool: config.name
+        })
+      }
+
+      const input = options.input as StorageDownloadInput
+
+      const blob = await storageService.download({
+        organizationId: options.executionContext.organizationId,
+        bucket: input.bucket,
+        path: input.path
+      })
+
+      // Convert blob to base64
+      const arrayBuffer = await blob.arrayBuffer()
+      const content = Buffer.from(arrayBuffer).toString('base64')
+
+      return {
+        success: true,
+        content,
+        contentType: blob.type || undefined
+      }
+    }
+  }
+}
+
+/**
+ * Create storage delete tool for workflows/agents
+ *
+ * @param config - Tool configuration (name, description)
+ * @returns Tool that deletes files from org-scoped storage
+ *
+ * @example
+ * const deleteTool = createStorageDeleteTool({
+ *   name: 'remove_draft',
+ *   description: 'Delete draft proposal file'
+ * })
+ *
+ * // In agent execution:
+ * await deleteTool.execute({
+ *   input: {
+ *     bucket: 'acquisition',
+ *     path: 'proposals/deal-123/draft.pdf'
+ *   },
+ *   executionContext: context
+ * })
+ */
+export function createStorageDeleteTool(config: StorageToolConfig): Tool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: StorageDeleteInputSchema,
+    outputSchema: StorageDeleteOutputSchema,
+
+    async execute(options: ToolExecutionOptions): Promise<StorageDeleteOutput> {
+      if (!options.executionContext) {
+        throw serviceUnavailable('ExecutionContext', { tool: config.name, reason: 'organizationId required for multi-tenant isolation' })
+      }
+
+      const { storageService } = getToolServices()
+      if (!storageService) {
+        throw serviceUnavailable('StorageService', {
+          message: 'Ensure toolServicesRegistry.initialize() was called in apps/api/src/main.ts',
+          tool: config.name
+        })
+      }
+
+      const input = options.input as StorageDeleteInput
+
+      await storageService.delete({
+        organizationId: options.executionContext.organizationId,
+        bucket: input.bucket,
+        path: input.path
+      })
+
+      return {
+        success: true
+      }
+    }
+  }
+}
+
+/**
+ * Create storage list tool for workflows/agents
+ *
+ * @param config - Tool configuration (name, description)
+ * @returns Tool that lists files in org-scoped storage
+ *
+ * @example
+ * const listTool = createStorageListTool({
+ *   name: 'list_proposals',
+ *   description: 'List all proposals for a deal'
+ * })
+ *
+ * // In agent execution:
+ * await listTool.execute({
+ *   input: {
+ *     bucket: 'acquisition',
+ *     prefix: 'proposals/deal-123/'
+ *   },
+ *   executionContext: context
+ * })
+ */
+export function createStorageListTool(config: StorageToolConfig): Tool {
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: StorageListInputSchema,
+    outputSchema: StorageListOutputSchema,
+
+    async execute(options: ToolExecutionOptions): Promise<StorageListOutput> {
+      if (!options.executionContext) {
+        throw serviceUnavailable('ExecutionContext', { tool: config.name, reason: 'organizationId required for multi-tenant isolation' })
+      }
+
+      const { storageService } = getToolServices()
+      if (!storageService) {
+        throw serviceUnavailable('StorageService', {
+          message: 'Ensure toolServicesRegistry.initialize() was called in apps/api/src/main.ts',
+          tool: config.name
+        })
+      }
+
+      const input = options.input as StorageListInput
+
+      const files = await storageService.list({
+        organizationId: options.executionContext.organizationId,
+        bucket: input.bucket,
+        prefix: input.prefix
+      })
+
+      return {
+        success: true,
+        files
+      }
+    }
+  }
+}
+
+// Re-export types for consumers
+export {
+  StorageUploadInputSchema,
+  StorageUploadOutputSchema,
+  StorageSignedUrlInputSchema,
+  StorageSignedUrlOutputSchema,
+  StorageDownloadInputSchema,
+  StorageDownloadOutputSchema,
+  StorageDeleteInputSchema,
+  StorageDeleteOutputSchema,
+  StorageListInputSchema,
+  StorageListOutputSchema,
+  type StorageUploadInput,
+  type StorageUploadOutput,
+  type StorageSignedUrlInput,
+  type StorageSignedUrlOutput,
+  type StorageDownloadInput,
+  type StorageDownloadOutput,
+  type StorageDeleteInput,
+  type StorageDeleteOutput,
+  type StorageListInput,
+  type StorageListOutput,
+  type StorageToolConfig
+} from './types'

package/src/execution/engine/tools/platform/storage/types.ts

@@ -0,0 +1,128 @@
+/**
+ * Platform Storage Tool Types
+ * Zod schemas and TypeScript types for storage platform tools
+ */
+
+import { z } from 'zod'
+
+// =============================================================================
+// Input Schemas
+// =============================================================================
+
+/**
+ * Schema for storage upload tool input
+ */
+export const StorageUploadInputSchema = z.object({
+  bucket: z.string().describe('Storage bucket name (e.g., "acquisition", "org-files", "assets")'),
+  path: z.string().describe('File path within org folder (e.g., "proposals/deal-123/proposal.pdf")'),
+  content: z.string().describe('Base64 encoded file content'),
+  contentType: z.string().describe('MIME type (e.g., "application/pdf", "image/png")'),
+  upsert: z.boolean().optional().describe('Overwrite if file exists (default: false)')
+})
+
+/**
+ * Schema for storage signed URL tool input
+ */
+export const StorageSignedUrlInputSchema = z.object({
+  bucket: z.string().describe('Storage bucket name'),
+  path: z.string().describe('File path within org folder'),
+  expiresIn: z.number().default(86400).describe('URL expiration in seconds (default: 86400 = 24 hours)')
+})
+
+/**
+ * Schema for storage download tool input
+ */
+export const StorageDownloadInputSchema = z.object({
+  bucket: z.string().describe('Storage bucket name'),
+  path: z.string().describe('File path within org folder')
+})
+
+/**
+ * Schema for storage delete tool input
+ */
+export const StorageDeleteInputSchema = z.object({
+  bucket: z.string().describe('Storage bucket name'),
+  path: z.string().describe('File path within org folder')
+})
+
+/**
+ * Schema for storage list tool input
+ */
+export const StorageListInputSchema = z.object({
+  bucket: z.string().describe('Storage bucket name'),
+  prefix: z.string().optional().describe('Path prefix to filter files (e.g., "proposals/")')
+})
+
+// =============================================================================
+// Output Schemas
+// =============================================================================
+
+/**
+ * Schema for storage upload tool output
+ */
+export const StorageUploadOutputSchema = z.object({
+  success: z.boolean(),
+  path: z.string().describe('Relative file path'),
+  fullPath: z.string().describe('Full path including org prefix')
+})
+
+/**
+ * Schema for storage signed URL tool output
+ */
+export const StorageSignedUrlOutputSchema = z.object({
+  success: z.boolean(),
+  signedUrl: z.string().describe('Temporary signed URL for file access'),
+  expiresAt: z.string().describe('ISO date when URL expires')
+})
+
+/**
+ * Schema for storage download tool output
+ */
+export const StorageDownloadOutputSchema = z.object({
+  success: z.boolean(),
+  content: z.string().describe('Base64 encoded file content'),
+  contentType: z.string().optional().describe('MIME type if known')
+})
+
+/**
+ * Schema for storage delete tool output
+ */
+export const StorageDeleteOutputSchema = z.object({
+  success: z.boolean()
+})
+
+/**
+ * Schema for storage list tool output
+ */
+export const StorageListOutputSchema = z.object({
+  success: z.boolean(),
+  files: z.array(z.string()).describe('List of file names')
+})
+
+// =============================================================================
+// TypeScript Types
+// =============================================================================
+
+export type StorageUploadInput = z.infer<typeof StorageUploadInputSchema>
+export type StorageSignedUrlInput = z.infer<typeof StorageSignedUrlInputSchema>
+export type StorageDownloadInput = z.infer<typeof StorageDownloadInputSchema>
+export type StorageDeleteInput = z.infer<typeof StorageDeleteInputSchema>
+export type StorageListInput = z.infer<typeof StorageListInputSchema>
+
+export type StorageUploadOutput = z.infer<typeof StorageUploadOutputSchema>
+export type StorageSignedUrlOutput = z.infer<typeof StorageSignedUrlOutputSchema>
+export type StorageDownloadOutput = z.infer<typeof StorageDownloadOutputSchema>
+export type StorageDeleteOutput = z.infer<typeof StorageDeleteOutputSchema>
+export type StorageListOutput = z.infer<typeof StorageListOutputSchema>
+
+// =============================================================================
+// Tool Configuration Types
+// =============================================================================
+
+/**
+ * Configuration for storage tool factories
+ */
+export interface StorageToolConfig {
+  name: string
+  description: string
+}

package/src/execution/engine/tools/platform/types.ts

@@ -0,0 +1,148 @@
+import type { z } from 'zod'
+import type { CreateTaskParams, Task } from '../../../../commands/queue/types'
+import type { CreateScheduleInput, TaskSchedule } from '../../../scheduler/types'
+import type { CreateNotificationParams, Notification } from '../../../../operations/notifications/types'
+
+/**
+ * Command Queue Service interface for platform tools.
+ * Matches the structure of CommandQueueService in apps/api.
+ */
+export interface ICommandQueueService {
+  createTask(params: CreateTaskParams): Promise<Task>
+
+  /**
+   * Delete pending HITL tasks matching metadata filter
+   * Uses JSONB containment (.contains()) for metadata-based batch deletion
+   */
+  deleteByMetadata(
+    organizationId: string,
+    metadata: Record<string, unknown>,
+    status?: string
+  ): Promise<{ deleted: number }>
+}
+
+/**
+ * Task Scheduler Service interface for platform tools.
+ * Matches the structure of TaskScheduleService in apps/api.
+ */
+export interface ITaskSchedulerService {
+  createSchedule(input: CreateScheduleInput): Promise<TaskSchedule>
+  deleteScheduleByIdempotencyKey(idempotencyKey: string, organizationId: string): Promise<void>
+
+  /**
+   * List schedules with optional metadata filtering
+   * Supports JSONB containment for metadata-based queries
+   */
+  listSchedules(params: {
+    organizationId: string
+    targetResourceId?: string
+    status?: string
+    metadata?: Record<string, unknown>
+    limit?: number
+    offset?: number
+  }): Promise<{ schedules: TaskSchedule[]; total: number }>
+
+  /**
+   * Get a single schedule by ID
+   */
+  getSchedule(id: string, organizationId: string): Promise<TaskSchedule | null>
+
+  /**
+   * Cancel a schedule (soft delete - sets status to 'cancelled')
+   */
+  cancelSchedule(id: string, organizationId: string): Promise<TaskSchedule>
+
+  /**
+   * Cancel all schedules matching metadata filter (batch soft delete)
+   * Uses JSONB containment (.contains()) for metadata-based filtering
+   */
+  cancelSchedulesByMetadata(
+    organizationId: string,
+    metadata: Record<string, unknown>,
+    status?: string
+  ): Promise<{ cancelled: number }>
+
+  /**
+   * Cancel a schedule by idempotency key (soft delete)
+   * Finds schedule by key and cancels it. No-op if schedule not found.
+   * @see TaskScheduleService.cancelScheduleByIdempotencyKey (apps/api/src/execution/task-scheduler/service.ts)
+   */
+  cancelScheduleByIdempotencyKey(idempotencyKey: string, organizationId: string): Promise<{ cancelled: boolean }>
+}
+
+/**
+ * Notifications Service interface for platform tools.
+ * Matches the structure of NotificationService in apps/api.
+ */
+export interface INotificationsService {
+  create(params: CreateNotificationParams): Promise<Notification>
+}
+
+/**
+ * Configuration for creating an approval tool.
+ * Approval tools create tasks in the command queue that require human approval.
+ */
+export interface ApprovalToolConfig {
+  /** Unique name for the tool */
+  name: string
+  /** Description of what the tool does */
+  description: string
+  /** Zod schema for validating input */
+  inputSchema: z.ZodSchema
+  /** Zod schema for validating output */
+  outputSchema: z.ZodSchema
+  /** Resource ID to execute when task is approved */
+  approveTargetResourceId: string
+  /** Optional resource ID to execute when task is rejected */
+  rejectTargetResourceId?: string
+  /** Task priority (1-10, default: 5) */
+  priority?: number
+  /** Optional expiration date for the task */
+  expiresAt?: Date
+}
+
+/**
+ * Configuration for creating a scheduler tool.
+ * Scheduler tools create scheduled tasks that execute at a specific time.
+ */
+export interface SchedulerToolConfig {
+  /** Unique name for the tool */
+  name: string
+  /** Description of what the tool does (shown to LLM) */
+  description: string
+  /** Zod schema for validating input */
+  inputSchema: z.ZodSchema
+  /** Zod schema for validating output */
+  outputSchema: z.ZodSchema
+  /** Resource ID to execute */
+  targetResourceId: string
+  /** Type of resource to execute */
+  targetResourceType: 'agent' | 'workflow'
+  /** Maximum number of retry attempts (default: 3) */
+  maxRetries?: number
+  /** When to run the scheduled task */
+  runAt: Date
+  /** Optional task description (for internal tracking) */
+  taskDescription?: string
+  /** Optional idempotency key */
+  idempotencyKey?: string
+}
+
+/**
+ * Configuration for creating a notification tool.
+ * Notification tools send platform notifications to users.
+ */
+export interface NotificationToolConfig {
+  /** Unique name for the tool */
+  name: string
+  /** Description of what the tool does (shown to LLM) */
+  description: string
+  /** Zod schema for validating input */
+  inputSchema: z.ZodSchema
+  /** Zod schema for validating output */
+  outputSchema: z.ZodSchema
+  /** User ID to send notification to (if static, otherwise from input) */
+  userId?: string
+  /** Notification category (if static, otherwise from input) */
+  category?: CreateNotificationParams['category']
+}