@elevasis/core 0.1.0

package/src/operations/sessions/api-schemas.ts

@@ -0,0 +1,166 @@
+/**
+ * Sessions Domain - Zod Validation Schemas
+ *
+ * Validation schemas for session management endpoints.
+ * Includes request bodies, query params, path params, and WebSocket messages.
+ *
+ * Security:
+ * - All schemas use .strict() to prevent mass assignment attacks
+ * - UUID validation prevents invalid references
+ * - String length limits prevent DoS (+ token counter at 10k tokens)
+ * - organizationId never accepted in request body (taken from JWT)
+ */
+
+import { z } from 'zod'
+import { UuidSchema } from '../../platform/utils/validation'
+
+// Re-export UuidSchema for convenience
+export { UuidSchema }
+
+// ============================================================================
+// Path Parameters
+// ============================================================================
+
+/**
+ * Validate sessionId in URL path
+ * Used by: GET/DELETE /sessions/:sessionId, GET /sessions/:sessionId/messages
+ */
+export const SessionIdParamSchema = z
+  .object({
+    sessionId: UuidSchema
+  })
+  .strict()
+
+/**
+ * Validate sessionId + executionId in URL path
+ * Used by: GET /sessions/:sessionId/executions/:executionId
+ */
+export const ExecutionIdParamsSchema = z
+  .object({
+    sessionId: UuidSchema,
+    executionId: UuidSchema
+  })
+  .strict()
+
+// ============================================================================
+// Request Bodies
+// ============================================================================
+
+/**
+ * Create new session
+ * POST /sessions
+ *
+ * Security:
+ * - resourceId is string identifier (e.g., 'basic-agent', 'linear-test-workflow')
+ * - userId optional (for user-specific sessions)
+ * - metadata optional (arbitrary JSON for agent use)
+ * - organizationId NOT accepted (taken from JWT)
+ */
+export const CreateSessionSchema = z
+  .object({
+    resourceId: z.string().min(1).max(100),
+    userId: UuidSchema.optional(),
+    metadata: z.any().optional()
+  })
+  .strict()
+
+/**
+ * Execute session turn
+ * POST /sessions/:sessionId/turns
+ *
+ * Supports string, object, and any JSON-serializable input formats
+ *
+ * Security:
+ * - Input length max 100k chars (supports long-form AI interactions)
+ * - Prompt injection blocked by input-sanitizer before execution
+ * - Strict mode prevents metadata injection
+ */
+export const ExecuteTurnSchema = z
+  .object({
+    input: z.unknown().refine(
+      (val) => {
+        let text: string
+        if (typeof val === 'string') {
+          text = val
+        } else if (val && typeof val === 'object' && 'message' in val) {
+          text = String((val as Record<string, unknown>).message)
+        } else {
+          text = JSON.stringify(val)
+        }
+        return text.length > 0 && text.length <= 100_000
+      },
+      { message: 'Input must be between 1 and 100,000 characters' }
+    ),
+    metadata: z.any().optional()
+  })
+  .strict()
+
+// ============================================================================
+// Query Parameters
+// ============================================================================
+
+/**
+ * List sessions with filters
+ * GET /sessions
+ *
+ * Filters:
+ * - userId: Filter by user (UUID)
+ * - resourceId: Filter by agent/resource (string identifier like 'executive-agent')
+ * - limit: Max results (1-100, default 20)
+ *
+ * Security:
+ * - userId validated as UUID (prevents SQL injection)
+ * - resourceId validated as string (resource identifiers)
+ * - Limit bounded (prevents DoS via large result sets)
+ */
+export const ListSessionsQuerySchema = z
+  .object({
+    userId: UuidSchema.optional(),
+    resourceId: z.string().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(20)
+  })
+  .strict()
+
+// ============================================================================
+// WebSocket Messages
+// ============================================================================
+
+/**
+ * WebSocket client message: Execute turn
+ *
+ * Client sends: { type: "session:turn", input: "..." }
+ *
+ * Security:
+ * - Same input validation as HTTP endpoint (100k char limit)
+ * - Token limit also validated separately (10k tokens for CHAT_MESSAGE)
+ * - Prompt injection blocked by input-sanitizer
+ */
+export const WebSocketSessionTurnSchema = z
+  .object({
+    type: z.literal('session:turn'),
+    input: z.unknown().refine(
+      (val) => {
+        let text: string
+        if (typeof val === 'string') {
+          text = val
+        } else if (val && typeof val === 'object' && 'message' in val) {
+          text = String((val as Record<string, unknown>).message)
+        } else {
+          text = JSON.stringify(val) || ''
+        }
+        return text && text.length > 0 && text.length <= 100_000
+      },
+      { message: 'Input must be between 1 and 100,000 characters' }
+    )
+  })
+  .strict()
+
+// ============================================================================
+// TypeScript Type Exports
+// ============================================================================
+
+// Export inferred types for use in route handlers
+export type CreateSessionInput = z.infer<typeof CreateSessionSchema>
+export type ExecuteTurnInput = z.infer<typeof ExecuteTurnSchema>
+export type ListSessionsQuery = z.infer<typeof ListSessionsQuerySchema>
+export type WebSocketSessionTurnMessage = z.infer<typeof WebSocketSessionTurnSchema>

package/src/operations/sessions/index.ts

@@ -0,0 +1,26 @@
+// Session classes are server-only - import from @repo/core/server
+// Only types are exported here for browser-safe access
+export type {
+  SessionTurnResult,
+  SessionTokenUsage,
+  CreateSessionParams,
+  ListSessionsFilters,
+  SessionRow,
+  SessionInsert,
+  ExecuteTurnRequest
+} from './types'
+
+// Export validation schemas
+export {
+  CreateSessionSchema,
+  ExecuteTurnSchema,
+  ListSessionsQuerySchema,
+  SessionIdParamSchema,
+  ExecutionIdParamsSchema,
+  WebSocketSessionTurnSchema,
+  UuidSchema,
+  type CreateSessionInput,
+  type ExecuteTurnInput,
+  type ListSessionsQuery,
+  type WebSocketSessionTurnMessage
+} from './api-schemas'

package/src/operations/sessions/server/manager.ts

@@ -0,0 +1,90 @@
+import type { SupabaseClient } from '../../../supabase'
+import { Session } from './session'
+import type { CreateSessionParams, ListSessionsFilters } from '../types'
+
+export class SessionManager {
+  constructor(private db: SupabaseClient) {}
+
+  async create(params: CreateSessionParams): Promise<Session> {
+    const { resourceId, organizationId, userId, metadata, contextWindowSize } = params
+
+    const { data, error } = await this.db
+      .from('sessions')
+      .insert({
+        resource_id: resourceId,
+        organization_id: organizationId,
+        user_id: userId ?? null,
+        memory_snapshot: { sessionMemory: {}, history: [] },
+        metadata: (metadata as Record<string, never> | null) ?? null,
+        session_total_turns: 0,
+        ...(contextWindowSize !== undefined && { context_window_size: contextWindowSize })
+      })
+      .select()
+      .single()
+
+    if (error) {
+      throw new Error(`Failed to create session: ${error.message}`)
+    }
+
+    return new Session(this.db, data)
+  }
+
+  async get(sessionId: string, organizationId: string): Promise<Session | null> {
+    const { data, error } = await this.db
+      .from('sessions')
+      .select()
+      .eq('session_id', sessionId)
+      .eq('organization_id', organizationId)
+      .is('deleted_at', null)
+      .single()
+
+    if (error) {
+      if (error.code === 'PGRST116') {
+        return null // Not found
+      }
+      throw new Error(`Failed to get session: ${error.message}`)
+    }
+
+    return new Session(this.db, data)
+  }
+
+  async list(filters: ListSessionsFilters): Promise<Session[]> {
+    const { organizationId, userId, resourceId, limit = 50 } = filters
+
+    let query = this.db
+      .from('sessions')
+      .select()
+      .eq('organization_id', organizationId)
+      .is('deleted_at', null)
+      .order('created_at', { ascending: false })
+      .limit(limit)
+
+    if (userId) {
+      query = query.eq('user_id', userId)
+    }
+
+    if (resourceId) {
+      query = query.eq('resource_id', resourceId)
+    }
+
+    const { data, error } = await query
+
+    if (error) {
+      throw new Error(`Failed to list sessions: ${error.message}`)
+    }
+
+    return data.map((row) => new Session(this.db, row))
+  }
+
+  async delete(sessionId: string, organizationId: string): Promise<void> {
+    const { error } = await this.db
+      .from('sessions')
+      .update({ deleted_at: new Date().toISOString() })
+      .eq('session_id', sessionId)
+      .eq('organization_id', organizationId)
+
+    if (error) {
+      throw new Error(`Failed to delete session: ${error.message}`)
+    }
+  }
+}

package/src/operations/sessions/server/session.ts

@@ -0,0 +1,180 @@
+import type { SupabaseClient, Json } from '../../../supabase'
+import type { ExecutionContext } from '../../../execution/engine/base/types'
+import type { AgentDefinition } from '../../../execution/engine/agent/core/types'
+import type { AgentMemory } from '../../../execution/engine/agent/memory/types'
+import type { SessionRow, SessionTurnResult } from '../types'
+import { createLLMAdapter } from '../../../execution/engine/llm/adapters/server/adapter-factory'
+
+export class Session {
+  constructor(
+    private db: SupabaseClient,
+    private data: SessionRow
+  ) {}
+
+  // Getters
+  get sessionId(): string {
+    return this.data.session_id
+  }
+
+  get organizationId(): string {
+    return this.data.organization_id
+  }
+
+  get userId(): string | null {
+    return this.data.user_id
+  }
+
+  get resourceId(): string {
+    return this.data.resource_id
+  }
+
+  get totalTurns(): number {
+    return this.data.session_total_turns ?? 0
+  }
+
+  get memorySnapshot(): AgentMemory {
+    return this.data.memory_snapshot as unknown as AgentMemory
+  }
+
+  get metadata(): Record<string, unknown> | null {
+    return this.data.metadata as Record<string, unknown> | null
+  }
+
+  /** Title derived from the first user message, stored in metadata */
+  get title(): string | null {
+    const meta = this.data.metadata as Record<string, unknown> | null
+    return (meta?.title as string) ?? null
+  }
+
+  get createdAt(): Date {
+    return new Date(this.data.created_at!)
+  }
+
+  get updatedAt(): Date {
+    return new Date(this.data.updated_at!)
+  }
+
+  get isEnded(): boolean {
+    return !!this.data.ended_at
+  }
+
+  get contextWindowSize(): number {
+    return this.data.context_window_size
+  }
+
+  /**
+   * Execute a turn in this session
+   *
+   * Uses database transaction with row-level lock to prevent concurrent turn execution.
+   * Pattern: Lock → Read → Validate → Execute → Save
+   *
+   * @param agentDefinition - Agent definition to execute
+   * @param input - Input for this turn
+   * @param context - Full execution context (including sessionTurnMessages if streaming)
+   * @returns Turn result with output and metadata
+   */
+  async executeTurn<TInput, TOutput>(
+    agentDefinition: AgentDefinition,
+    input: TInput,
+    context: ExecutionContext
+  ): Promise<SessionTurnResult<TOutput>> {
+    const turnStartTime = Date.now()
+
+    // NOTE: Using RPC to acquire row-level lock and get fresh state
+    // This ensures atomic lock acquisition for concurrent turn prevention
+    const { data, error } = await this.db.rpc('execute_session_turn', {
+      p_session_id: this.sessionId
+    })
+
+    if (error) {
+      throw new Error(`Failed to acquire session lock: ${error.message}`)
+    }
+
+    // Reload fresh state from lock result
+    const lockResult = (Array.isArray(data) ? data[0] : data) as unknown
+    if (!lockResult) {
+      throw new Error('Session not found')
+    }
+
+    this.data = lockResult as SessionRow
+
+    // Validate
+    if (this.isEnded) {
+      throw new Error('Cannot execute turn on ended session')
+    }
+
+    // Create agent instance (stateless, recreated per turn)
+    const { Agent } = await import('../../../execution/engine/agent/core/agent')
+    const agent = new Agent<TInput, TOutput>(agentDefinition, createLLMAdapter)
+
+    // Execute agent (preloadMemory callback will restore session memory)
+    const output = await agent.execute(input, context)
+
+    // Update state and persist
+    const snapshot = agent.getMemorySnapshot()
+    if (!snapshot) {
+      throw new Error('Agent did not produce memory snapshot')
+    }
+
+    // Complete turn (messages already persisted immediately via onMessageEvent)
+    await this.completeTurn(snapshot)
+
+    return {
+      sessionId: this.sessionId,
+      executionId: context.executionId,
+      turnNumber: this.data.session_total_turns ?? 0,
+      output,
+      duration: Date.now() - turnStartTime
+    }
+  }
+
+  /**
+   * End this session (marks as ended, prevents future turns)
+   */
+  async end(): Promise<void> {
+    this.data.ended_at = new Date().toISOString()
+    this.data.updated_at = new Date().toISOString()
+    await this.save()
+  }
+
+  /**
+   * Convert to JSON representation
+   */
+  toJSON(): SessionRow {
+    return { ...this.data }
+  }
+
+  /**
+   * Save current state to database
+   */
+  private async save(): Promise<void> {
+    const { error } = await this.db
+      .from('sessions')
+      .update({
+        memory_snapshot: this.data.memory_snapshot,
+        session_total_turns: this.data.session_total_turns,
+        updated_at: this.data.updated_at,
+        ended_at: this.data.ended_at
+      })
+      .eq('session_id', this.sessionId)
+
+    if (error) {
+      throw new Error(`Failed to save session: ${error.message}`)
+    }
+  }
+
+  /**
+   * Complete turn by updating session state
+   * Messages already persisted immediately via onMessageEvent callback
+   * @param snapshot - Agent memory snapshot
+   */
+  private async completeTurn(snapshot: AgentMemory): Promise<void> {
+    // Update session state
+    this.data.memory_snapshot = snapshot as unknown as Json
+    this.data.session_total_turns = (this.data.session_total_turns ?? 0) + 1
+    this.data.updated_at = new Date().toISOString()
+
+    // Persist session state (messages already in DB)
+    await this.save()
+  }
+}

package/src/operations/sessions/types.ts

@@ -0,0 +1,98 @@
+import type { Tables, TablesInsert } from '../../supabase/database.types'
+import type { MessageEvent } from '../../execution/engine/base/types'
+import type { AgentMemory } from '../../execution/engine/agent/memory/types'
+
+// Database table types (use imported Supabase types)
+export type SessionRow = Tables<'sessions'>
+export type SessionInsert = TablesInsert<'sessions'>
+export type SessionMessageRow = Tables<'session_messages'>
+export type SessionMessageInsert = TablesInsert<'session_messages'>
+
+// Extract all event types from MessageEvent discriminated union
+export type MessageType = MessageEvent['type']
+
+/**
+ * Session Data Transfer Object (DTO)
+ * Transform type for API responses (snake_case DB → camelCase frontend)
+ * Used by frontend apps to display session data
+ */
+export interface SessionDTO {
+  sessionId: string
+  resourceId: string
+  organizationId: string
+  userId?: string | null
+  turnCount: number
+  isEnded: boolean
+  title?: string | null
+  memorySnapshot?: AgentMemory
+  metadata?: Record<string, unknown> | null
+  createdAt: Date
+  updatedAt: Date
+  endedAt?: Date | null
+}
+
+// Transform type (snake_case DB → camelCase domain)
+export interface ChatMessage {
+  id: string
+  role: 'user' | 'assistant'
+  messageType: MessageType
+  text: string
+  metadata?: MessageEvent
+  turnNumber: number
+  messageIndex?: number // Optional - auto-generated by DB trigger, may be undefined for temp messages
+  createdAt: Date
+}
+
+export interface SessionTurnResult<TOutput> {
+  sessionId: string
+  executionId: string
+  turnNumber: number
+  output: TOutput | null // Null for side-effect agents with no output schema
+  duration: number
+}
+
+export interface CreateSessionParams {
+  resourceId: string
+  organizationId: string
+  userId?: string
+  metadata?: Record<string, unknown>
+  /** Context window size from the agent's model config (tokens) */
+  contextWindowSize?: number
+}
+
+export interface ListSessionsFilters {
+  organizationId: string
+  userId?: string
+  resourceId?: string
+  limit?: number
+}
+
+// API Request/Response Types
+
+/**
+ * Execute turn request body
+ * Supports both object format (with message key) and plain string
+ */
+export interface ExecuteTurnRequest {
+  input:
+    | {
+        message: string
+      }
+    | string
+}
+
+/** Token usage data sent with turn:complete WebSocket events */
+export interface SessionTokenUsage {
+  /** Tokens consumed by this turn's input */
+  turnInputTokens: number
+  /** Tokens generated by this turn's output */
+  turnOutputTokens: number
+  /** Total tokens for this turn (turnInputTokens + turnOutputTokens) */
+  turnTotalTokens: number
+  /** Cumulative input tokens across all turns in this session */
+  cumulativeInputTokens: number
+  /** Cumulative output tokens across all turns in this session */
+  cumulativeOutputTokens: number
+  /** The model's context window size for this session (e.g., 200K) */
+  contextWindowSize: number
+}

package/src/operations/triggers/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Triggers Module
+ *
+ * Triggers start workflow executions. Types of triggers:
+ * - Webhook: External services send HTTP requests (Cal.com, Fillout, Instantly, etc.)
+ * - Scheduled: Cron-based execution (future)
+ * - Manual: User-initiated execution (future)
+ * - Event: Internal event-based execution (future)
+ */
+
+// Webhook triggers (providers + definitions)
+export * from './webhook/index'

package/src/operations/triggers/webhook/definitions/__tests__/instantly-reply-received.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Test: Instantly Reply Received Trigger Definition
+ *
+ * Tests for the Instantly webhook trigger definition.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  instantlyReplyReceivedTrigger,
+  type InstantlyReplyWebhookPayload
+} from '../instantly-reply-received'
+
+describe('instantlyReplyReceivedTrigger', () => {
+  describe('trigger definition structure', () => {
+    it('has correct triggerType', () => {
+      expect(instantlyReplyReceivedTrigger.triggerType).toBe('webhook')
+    })
+
+    it('has correct config provider', () => {
+      expect(instantlyReplyReceivedTrigger.config).toBeDefined()
+      expect((instantlyReplyReceivedTrigger.config as { provider: string }).provider).toBe('instantly')
+    })
+
+    it('has correct config event', () => {
+      expect(instantlyReplyReceivedTrigger.config).toBeDefined()
+      expect((instantlyReplyReceivedTrigger.config as { event: string }).event).toBe('reply_received')
+    })
+
+    it('has correct resourceId', () => {
+      expect(instantlyReplyReceivedTrigger.resourceId).toBe('trigger-instantly-reply-received')
+    })
+
+    it('has correct type', () => {
+      expect(instantlyReplyReceivedTrigger.type).toBe('trigger')
+    })
+
+    it('has required metadata fields', () => {
+      expect(instantlyReplyReceivedTrigger.name).toBe('Instantly Reply Received')
+      expect(instantlyReplyReceivedTrigger.description).toBeDefined()
+      expect(instantlyReplyReceivedTrigger.version).toBe('1.0.0')
+      expect(instantlyReplyReceivedTrigger.status).toBe('dev')
+    })
+
+    it('has webhookPath defined', () => {
+      expect(instantlyReplyReceivedTrigger.webhookPath).toBe('/webhooks/instantly/reply-received')
+    })
+  })
+
+  describe('type exports', () => {
+    it('exports InstantlyReplyWebhookPayload type', () => {
+      // Type assertion test - if this compiles, the type is exported
+      const payload: InstantlyReplyWebhookPayload = {
+        timestamp: '2025-01-15T10:30:00Z',
+        event_type: 'reply_received',
+        workspace: 'test',
+        campaign_id: 'camp-1',
+        lead_email: 'test@example.com',
+        email_account: 'sender@example.com',
+        unibox_url: 'https://instantly.ai/unibox/1',
+        reply_to_uuid: 'uuid-1',
+        reply_subject: 'Re: Test',
+        reply_text: 'Test reply',
+        reply_text_snippet: 'Test...',
+        reply_html: '<p>Test reply</p>',
+        step: 1,
+        variant: 0,
+        is_first: true
+      }
+      expect(payload.event_type).toBe('reply_received')
+    })
+  })
+})

package/src/operations/triggers/webhook/definitions/instantly-account-error.ts

@@ -0,0 +1,44 @@
+/**
+ * Instantly Account Error Trigger Definition
+ *
+ * Webhook trigger for Instantly email account error events.
+ * Uses Instantly's native snake_case format - no transformation needed.
+ */
+
+import type { TriggerDefinition, WebhookTriggerConfig } from '../../../../platform/registry/types'
+
+/**
+ * Instantly account error webhook payload structure
+ *
+ * Uses snake_case matching Instantly's API. Workflows receive this directly.
+ */
+export interface InstantlyAccountErrorPayload {
+  timestamp: string
+  event_type: 'account_error'
+  workspace: string
+  email_account: string
+  error_type?: string
+  error_message?: string
+}
+
+/**
+ * Instantly Account Error Trigger Definition
+ *
+ * Trigger type: webhook
+ * Provider: instantly
+ * Event: account_error
+ */
+export const instantlyAccountErrorTrigger: TriggerDefinition = {
+  resourceId: 'trigger-instantly-account-error',
+  type: 'trigger',
+  triggerType: 'webhook',
+  name: 'Instantly Account Error',
+  description: 'Webhook fired when an Instantly sending account encounters an error',
+  version: '1.0.0',
+  status: 'dev',
+  webhookPath: '/webhooks/instantly/account-error',
+  config: {
+    provider: 'instantly',
+    event: 'account_error'
+  } as WebhookTriggerConfig
+}