@elevasis/core 0.1.0

package/src/execution/core/__tests__/archived-logs.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest'
+import { isArchivedLogs } from '../sse-executions'
+
+describe('isArchivedLogs', () => {
+  it('returns true for a valid archived pointer object', () => {
+    const pointer = {
+      __archived: true,
+      storage_path: 'org-123/executions/exec-456/logs.json',
+      archived_at: '2026-01-15T10:00:00Z',
+      original_count: 1500
+    }
+    expect(isArchivedLogs(pointer)).toBe(true)
+  })
+
+  it('returns false for null', () => {
+    expect(isArchivedLogs(null)).toBe(false)
+  })
+
+  it('returns false for undefined', () => {
+    expect(isArchivedLogs(undefined)).toBe(false)
+  })
+
+  it('returns false for an empty array (normal logs state)', () => {
+    expect(isArchivedLogs([])).toBe(false)
+  })
+
+  it('returns false for a non-empty array of log messages', () => {
+    const logs = [
+      { level: 'info', message: 'Starting execution', timestamp: 1700000000000 },
+      { level: 'info', message: 'Execution complete', timestamp: 1700000001000 }
+    ]
+    expect(isArchivedLogs(logs)).toBe(false)
+  })
+
+  it('returns false for an empty object', () => {
+    expect(isArchivedLogs({})).toBe(false)
+  })
+
+  it('returns false for an object with __archived: false', () => {
+    const obj = {
+      __archived: false,
+      storage_path: 'org-123/executions/exec-456/logs.json',
+      archived_at: '2026-01-15T10:00:00Z',
+      original_count: 42
+    }
+    expect(isArchivedLogs(obj)).toBe(false)
+  })
+
+  it('returns false for a string', () => {
+    expect(isArchivedLogs('archived')).toBe(false)
+  })
+
+  it('returns false for a number', () => {
+    expect(isArchivedLogs(42)).toBe(false)
+  })
+
+  it('narrows the type so storage_path and original_count are accessible after the guard', () => {
+    const value: unknown = {
+      __archived: true,
+      storage_path: 'org-123/executions/exec-789/logs.json',
+      archived_at: '2026-03-01T08:30:00Z',
+      original_count: 300
+    }
+
+    if (isArchivedLogs(value)) {
+      expect(value.storage_path).toBe('org-123/executions/exec-789/logs.json')
+      expect(value.original_count).toBe(300)
+    } else {
+      throw new Error('Expected isArchivedLogs to return true')
+    }
+  })
+})

package/src/execution/core/api-schemas.ts

@@ -0,0 +1,312 @@
+/**
+ * Zod validation schemas for execution and workflow domain API endpoints
+ * @module execution/api-schemas
+ *
+ * These schemas provide runtime validation for the most critical API endpoints:
+ * - External API /execute (public-facing, API key auth)
+ * - Execution Engine /execute (internal, JWT auth)
+ * - Command Queue (human-in-the-loop approvals)
+ * - Sessions (conversational agents)
+ *
+ * Security Features:
+ * - UUID validation prevents injection attacks
+ * - Payload size limits prevent DoS attacks
+ * - Strict mode blocks field injection (e.g., organizationId)
+ * - Enum validation ensures type safety at runtime
+ */
+
+import { z } from 'zod'
+import {
+  UuidSchema,
+  NonEmptyStringSchema,
+  ResourceTypeSchema,
+  OriginResourceTypeSchema,
+  createPayloadSizeValidator
+} from '../../platform/utils/validation'
+
+// Payload size constraint (500KB limit for execution payloads)
+const PayloadSchema = createPayloadSizeValidator(500_000) // Required by default
+const OptionalPayloadSchema = createPayloadSizeValidator(500_000, { optional: true })
+
+// ============================================================================
+// EXECUTION TARGET SCHEMAS
+// ============================================================================
+
+/**
+ * Execution target validation
+ * Used by: Task Scheduler, Command Queue, Direct Execution
+ *
+ * Security:
+ * - resourceId validated as non-empty string (allows workflow/agent names)
+ * - resourceType enum validated at runtime
+ * - payload size limited to 500KB (prevents DoS)
+ */
+export const ExecutionTargetSchema = z
+  .object({
+    resourceType: ResourceTypeSchema,
+    resourceId: NonEmptyStringSchema.max(255),
+    payload: OptionalPayloadSchema
+  })
+  .strict()
+
+/**
+ * Origin tracking validation
+ * Required for audit trails and execution lineage
+ *
+ * Security:
+ * - originExecutionId validated as UUID
+ * - originResourceType enum validated
+ * - originResourceId length limited
+ */
+export const OriginTrackingSchema = z
+  .object({
+    originExecutionId: UuidSchema,
+    originResourceType: OriginResourceTypeSchema,
+    originResourceId: NonEmptyStringSchema.max(100)
+  })
+  .strict()
+
+// ============================================================================
+// EXTERNAL API SCHEMAS (CRITICAL - PUBLIC FACING)
+// ============================================================================
+
+/**
+ * External API /execute endpoint validation
+ * CRITICAL: This is a public-facing endpoint using API key auth
+ *
+ * Only production workflows can be executed via external API (in production env).
+ * Production status check happens at service layer after resource lookup.
+ *
+ * Security Features:
+ * - resourceId validated as non-empty string (kebab-case resource names)
+ * - 500KB payload limit prevents memory exhaustion
+ * - Strict mode blocks organizationId injection
+ *
+ * @example
+ * ```typescript
+ * // Valid request
+ * {
+ *   resourceId: "lead-qualification-agent",
+ *   input: { message: "Hello" }
+ * }
+ *
+ * // Invalid - will be rejected
+ * {
+ *   resourceId: "", // Empty string not allowed
+ *   input: "x".repeat(600_000) // Exceeds 500KB
+ * }
+ * ```
+ */
+export const ExternalExecuteRequestSchema = z
+  .object({
+    resourceId: NonEmptyStringSchema.max(100),
+    input: OptionalPayloadSchema
+  })
+  .strict()
+
+/**
+ * External API /execute response schema
+ * Validates success/error response structure
+ */
+export const ExternalExecuteResponseSchema = z.union([
+  z.object({
+    executionId: UuidSchema,
+    success: z.literal(true),
+    data: z.unknown()
+  }),
+  z.object({
+    success: z.literal(false),
+    error: z.string(),
+    message: z.string()
+  })
+])
+
+// ============================================================================
+// AI ENGINE SCHEMAS (CRITICAL - INTERNAL EXECUTION)
+// ============================================================================
+
+/**
+ * Execution Engine /execute endpoint validation
+ * CRITICAL: Controls agent/workflow execution in authenticated context
+ *
+ * Security Features:
+ * - resourceType enum validated at runtime (not just TypeScript)
+ * - resourceId validated as non-empty string (kebab-case pattern)
+ * - Optional input with size constraint (500KB)
+ * - Strict mode prevents field injection
+ *
+ * @example
+ * ```typescript
+ * // Valid workflow execution
+ * {
+ *   resourceType: "workflow",
+ *   resourceId: "linear-test-workflow",
+ *   input: { data: "test" }
+ * }
+ *
+ * // Valid agent execution (no input)
+ * {
+ *   resourceType: "agent",
+ *   resourceId: "basic-agent"
+ * }
+ *
+ * // Invalid - will be rejected
+ * {
+ *   resourceType: "malicious", // Invalid enum
+ *   resourceId: "" // Empty string not allowed
+ * }
+ * ```
+ */
+export const ExecutionEngineExecuteRequestSchema = z
+  .object({
+    resourceType: ResourceTypeSchema,
+    resourceId: NonEmptyStringSchema.max(100),
+    input: OptionalPayloadSchema
+  })
+  .strict()
+
+/**
+ * Execution Engine /execute response schema
+ * Validates success/error response structure with execution logs
+ */
+export const ExecutionEngineExecuteResponseSchema = z.union([
+  z.object({
+    success: z.literal(true),
+    executionId: UuidSchema,
+    logs: z.array(z.unknown()),
+    data: z.unknown().nullable()
+  }),
+  z.object({
+    success: z.literal(false),
+    executionId: UuidSchema,
+    logs: z.array(z.unknown()),
+    error: z.object({
+      message: z.string(),
+      code: z.string(),
+      details: z.string().optional(),
+      suggestions: z.array(z.string()).optional()
+    })
+  })
+])
+
+// ============================================================================
+// COMMAND QUEUE SCHEMAS (HUMAN-IN-THE-LOOP)
+// ============================================================================
+
+/**
+ * Create command queue task (approval request)
+ *
+ * Security Features:
+ * - All UUIDs validated
+ * - Execution targets validated (nested validation)
+ * - Payload sizes limited (both initial and targets)
+ * - Description and notes length limited
+ *
+ * @example
+ * ```typescript
+ * {
+ *   originExecutionId: "550e8400-e29b-41d4-a716-446655440000",
+ *   originResourceType: "agent",
+ *   originResourceId: "approval-agent",
+ *   approveTarget: {
+ *     resourceType: "workflow",
+ *     resourceId: "550e8400-e29b-41d4-a716-446655440001",
+ *     payload: { approved: true }
+ *   },
+ *   payloadInitial: { request: "approval needed" },
+ *   description: "Approve workflow execution",
+ *   priority: 5
+ * }
+ * ```
+ */
+export const CreateCommandQueueTaskSchema = z
+  .object({
+    // Origin tracking
+    originExecutionId: UuidSchema,
+    originResourceType: OriginResourceTypeSchema,
+    originResourceId: NonEmptyStringSchema.max(100),
+
+    // Approval targets
+    approveTarget: ExecutionTargetSchema,
+    rejectTarget: ExecutionTargetSchema.optional(),
+
+    // Task metadata
+    description: NonEmptyStringSchema.max(1000).optional(),
+    priority: z.number().int().min(1).max(10).default(5),
+    expiresAt: z.string().datetime().optional(),
+
+    // Initial payload
+    payloadInitial: PayloadSchema
+  })
+  .strict()
+
+/**
+ * Submit decision on command queue task
+ *
+ * Security Features:
+ * - Decision enum validated (only 'approve' | 'reject')
+ * - Notes length limited to 5000 characters
+ * - Payload override size limited to 500KB
+ *
+ * @example
+ * ```typescript
+ * // Approval with notes
+ * {
+ *   decision: "approve",
+ *   notes: "Looks good to proceed"
+ * }
+ *
+ * // Rejection with payload override
+ * {
+ *   decision: "reject",
+ *   notes: "Missing required data",
+ *   payloadOverride: { reason: "incomplete" }
+ * }
+ * ```
+ */
+export const SubmitDecisionSchema = z
+  .object({
+    decision: z.enum(['approve', 'reject']),
+    notes: NonEmptyStringSchema.max(5000).optional(),
+    payloadOverride: OptionalPayloadSchema
+  })
+  .strict()
+
+/**
+ * List command queue tasks
+ * Query parameters for filtering tasks by status
+ */
+export const ListCommandQueueTasksSchema = z
+  .object({
+    status: z.enum(['pending', 'approved', 'rejected', 'expired']).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(20)
+  })
+  .strict()
+
+// ============================================================================
+// SESSION SCHEMAS (CONVERSATIONAL AGENTS)
+// ============================================================================
+
+// ============================================================================
+// EXECUTION MANAGEMENT SCHEMAS
+// ============================================================================
+
+/**
+ * List executions query parameters
+ * Filter executions by resource status (dev/prod/all)
+ */
+export const ListExecutionsSchema = z
+  .object({
+    resourceStatus: z.enum(['dev', 'prod', 'all']).default('all')
+  })
+  .strict()
+
+/**
+ * Delete execution(s) query parameters
+ * Optional filter by resource status when bulk deleting
+ */
+export const DeleteExecutionsSchema = z
+  .object({
+    resourceStatus: z.enum(['dev', 'prod']).optional()
+  })
+  .strict()

package/src/execution/core/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Execution utilities and resource validation
+ *
+ * NOTE: canExecuteResource and detectEnvironment are server-only (use process.env)
+ * Import from @repo/core/server instead
+ */
+
+export * from './types'
+export * from './sse-executions'
+export * from './api-schemas'
+export * from './runner-types'

package/src/execution/core/resource-validator.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Resource validator usage examples
+ * Tests moved to server/environment to match new location
+ */
+
+import { describe, it, expect } from 'vitest'
+import { canExecuteResource, detectEnvironment } from './server/environment'
+
+// Example usage with AIResource
+const devResource = {
+  resourceId: 'basic-agent',
+  name: 'Basic Agent',
+  description: 'A basic agent',
+  version: '1.0.0',
+  type: 'agent' as const,
+  status: 'dev' as const
+}
+
+const prodResource = {
+  resourceId: 'prod-agent',
+  name: 'Production Agent',
+  description: 'A production agent',
+  version: '1.0.0',
+  type: 'agent' as const,
+  status: 'prod' as const
+}
+
+describe('resource-validator', () => {
+  describe('canExecuteResource', () => {
+    it('should block dev resources in production', () => {
+      expect(canExecuteResource(devResource, 'production')).toBe(false)
+    })
+
+    it('should allow prod resources in production', () => {
+      expect(canExecuteResource(prodResource, 'production')).toBe(true)
+    })
+
+    it('should allow dev resources in development', () => {
+      expect(canExecuteResource(devResource, 'development')).toBe(true)
+    })
+
+    it('should allow dev resources in staging', () => {
+      expect(canExecuteResource(devResource, 'staging')).toBe(true)
+    })
+
+    it('should allow prod resources in all environments', () => {
+      expect(canExecuteResource(prodResource, 'production')).toBe(true)
+      expect(canExecuteResource(prodResource, 'development')).toBe(true)
+      expect(canExecuteResource(prodResource, 'staging')).toBe(true)
+    })
+  })
+
+  describe('detectEnvironment', () => {
+    it('should detect environment from process.env.NODE_ENV', () => {
+      // Note: detectEnvironment now reads directly from process.env.NODE_ENV
+      // In test environment, this will be 'test' which defaults to 'development'
+      const result = detectEnvironment()
+      expect(['development', 'staging', 'production']).toContain(result)
+      // Test environment typically returns 'development'
+      expect(result).toBe('development')
+    })
+  })
+})

package/src/execution/core/runner-types.ts

@@ -0,0 +1,80 @@
+/**
+ * Execution Runner Types
+ *
+ * Shared types for the Execution Runner UI feature.
+ * Used by both API (apps/api) and frontend (apps/command-center).
+ */
+
+import type { SerializedExecutionInterface } from '../../platform/registry/serialized-types'
+import type { ExecutionStatus } from './sse-executions'
+
+// ============================================================================
+// PAGINATION
+// ============================================================================
+
+export interface PaginationMetadata {
+  total: number
+  limit: number
+  offset: number
+  hasMore: boolean
+}
+
+// ============================================================================
+// EXECUTION METRICS
+// ============================================================================
+
+export interface ExecutionMetrics {
+  tokenCount?: number
+  stepCount?: number
+  toolCallCount?: number
+}
+
+// ============================================================================
+// CATALOG TYPES
+// ============================================================================
+
+export interface ExecutionRunnerCatalogItem {
+  resourceId: string
+  resourceName: string
+  resourceType: 'workflow' | 'agent'
+  description?: string
+  status: 'dev' | 'prod'
+  version: string
+  interface: SerializedExecutionInterface
+}
+
+export interface ExecutionRunnerCatalogResponse {
+  resources: ExecutionRunnerCatalogItem[]
+}
+
+// ============================================================================
+// EXECUTION HISTORY TYPES
+// ============================================================================
+
+export interface ExecutionSummary {
+  id: string
+  resourceId: string
+  resourceName: string
+  status: ExecutionStatus
+  startedAt: string
+  completedAt?: string
+  durationMs?: number
+  metrics?: ExecutionMetrics
+  input?: unknown
+  output?: unknown
+  error?: { message: string }
+}
+
+export interface ExecutionListResponse {
+  executions: ExecutionSummary[]
+  pagination: PaginationMetadata
+}
+
+// ============================================================================
+// RUN RESOURCE TYPES
+// ============================================================================
+
+export interface RunResourceResponse {
+  executionId: string
+  status: ExecutionStatus
+}

package/src/execution/core/server/environment.ts

@@ -0,0 +1,31 @@
+/**
+ * Server-only environment detection
+ * Uses process.env.NODE_ENV (Node.js API)
+ */
+
+import type { ResourceDefinition } from '../../../platform/registry/types'
+
+export type Environment = 'development' | 'staging' | 'production'
+
+/**
+ * Detect current environment from Node.js process.env
+ * Server-only - do not import in browser code
+ */
+export function detectEnvironment(): Environment {
+  const env = process.env.NODE_ENV || 'development'
+  if (env === 'production') return 'production'
+  if ((env as string) === 'staging') return 'staging'
+  return 'development'
+}
+
+/**
+ * Check if resource can execute in current environment
+ * Production: only 'prod' resources allowed
+ * Staging/Development: both 'dev' and 'prod' allowed
+ *
+ * Server-only - uses detectEnvironment() which accesses process.env
+ */
+export function canExecuteResource(resource: ResourceDefinition, environment?: Environment): boolean {
+  const env = environment || detectEnvironment()
+  return env === 'production' ? resource.status === 'prod' : true
+}

package/src/execution/core/sse-executions.ts

@@ -0,0 +1,119 @@
+import type { ExecutionLogMessage } from '../engine/base/logging'
+import type { ResourceStatus } from '../../platform/registry/types'
+
+// Execution status type shared between API and UI
+export type ExecutionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'warning'
+
+/**
+ * Event sent when new execution starts
+ */
+export interface ExecutionStartedEvent {
+  type: 'new-execution'
+  resourceId: string
+  executionId: string
+  timestamp: number
+  data?: undefined
+}
+
+/**
+ * Event sent when execution log message is emitted
+ */
+export interface ExecutionLogEvent {
+  type: 'log'
+  resourceId: string
+  executionId: string
+  timestamp: number
+  data: {
+    log: ExecutionLogMessage
+  }
+}
+
+/**
+ * Event sent when execution completes (success or failure)
+ */
+export interface ExecutionCompleteEvent {
+  type: 'execution-complete'
+  resourceId: string
+  executionId: string
+  timestamp: number
+  data: {
+    success: boolean
+    status?: ExecutionStatus
+    result?: unknown
+    error?: string
+  }
+}
+
+/**
+ * Connection confirmation event
+ */
+export interface ExecutionConnectedEvent {
+  type: 'connected'
+  resourceId: string
+  executionId?: undefined
+  timestamp: number
+  data?: undefined
+}
+
+/**
+ * Union of all execution SSE events
+ */
+export type ExecutionSSEEvent =
+  | ExecutionStartedEvent
+  | ExecutionLogEvent
+  | ExecutionCompleteEvent
+  | ExecutionConnectedEvent
+
+// API execution types
+export interface APIExecutionSummary {
+  id: string
+  status: ExecutionStatus
+  startTime: number
+  endTime?: number
+  resourceStatus?: ResourceStatus // 'dev' | 'prod' - optional for backward compatibility
+}
+
+export interface APIExecutionDetail extends APIExecutionSummary {
+  executionLogs: ExecutionLogMessage[]
+  input?: unknown
+  result?: unknown
+  error?: string
+  resourceStatus: ResourceStatus // Required in detail view
+  apiVersion?: string | null
+  resourceVersion?: string | null
+  sdkVersion?: string | null
+  isArchived?: boolean
+  archivedLogCount?: number
+}
+
+// Archived logs pointer stored in execution_logs.logs column after archival
+export interface ArchivedLogsPointer {
+  __archived: true
+  storage_path: string
+  archived_at: string
+  original_count: number
+}
+
+export function isArchivedLogs(logs: unknown): logs is ArchivedLogsPointer {
+  return (
+    typeof logs === 'object' &&
+    logs !== null &&
+    !Array.isArray(logs) &&
+    (logs as Record<string, unknown>).__archived === true
+  )
+}
+
+// API request/response types
+export interface APIExecutionListResponse {
+  executions: APIExecutionSummary[]
+}
+
+// Organization -> Resource -> Execution structure
+export type ExecutionMap = Map<string, APIExecutionDetail>
+export type ResourceExecutionMap = Map<string, ExecutionMap>
+export type OrganizationExecutionStore = Map<string, ResourceExecutionMap>
+
+// SSE client types - generic to avoid Fastify dependency in core
+export type ClientSet<T = unknown> = Set<T>
+export type ResourceClientMap<T = unknown> = Map<string, ClientSet<T>>
+export type OrganizationClientStore<T = unknown> = Map<string, ResourceClientMap<T>>