@elevasis/core 0.1.0

package/src/platform/api/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Standard API error response format
+ * Returned by APIError.toJSON() in apps/api
+ * Consumed by Command Center UI for type-safe error handling
+ */
+export interface APIErrorResponse {
+  /** Human-readable error message */
+  error: string
+
+  /** Machine-readable error code */
+  code: APIErrorCode
+
+  /** Request ID for debugging (optional) */
+  requestId?: string
+
+  /** Field-level validation errors (only present for VALIDATION_ERROR code) */
+  fields?: Record<string, string[]>
+
+  /** Seconds until the rate limit resets (only present for RATE_LIMIT_EXCEEDED code) */
+  retryAfter?: number
+}
+
+/**
+ * Type-safe error codes
+ * MUST match API_ERROR_CODES in apps/api/src/errors/error-codes.ts
+ */
+export type APIErrorCode =
+  | 'VALIDATION_ERROR'
+  | 'AUTHENTICATION_FAILED'
+  | 'FORBIDDEN'
+  | 'NOT_FOUND'
+  | 'CONFLICT'
+  | 'RATE_LIMIT_EXCEEDED'
+  | 'INTERNAL_SERVER_ERROR'
+  | 'SERVICE_UNAVAILABLE'

package/src/platform/constants/http.ts

@@ -0,0 +1,37 @@
+/**
+ * HTTP-related constants used across the application
+ */
+
+/**
+ * HTTP Headers
+ */
+export const HTTP_HEADERS = {
+  /**
+   * Organization context header
+   * Note: Node.js normalizes all headers to lowercase, so we use lowercase consistently
+   */
+  WORKOS_ORGANIZATION_ID: 'workos-organization-id',
+  AGENT_ORGANIZATION: 'x-agent-organization',
+  AGENT_MODE: 'x-agent-mode'
+} as const
+
+/**
+ * HTTP Status Codes for organization-related operations
+ */
+export const ORG_HTTP_STATUS = {
+  ORG_ACCESS_DENIED: 403,
+  ORG_CONTEXT_REQUIRED: 400,
+  USER_NOT_FOUND: 404,
+  ORG_NOT_FOUND: 404
+} as const
+
+/**
+ * Organization-related error codes
+ */
+export const ORG_ERROR_CODES = {
+  ORG_ACCESS_DENIED: 'ORG_ACCESS_DENIED',
+  ORG_CONTEXT_REQUIRED: 'ORG_CONTEXT_REQUIRED',
+  USER_NOT_FOUND: 'USER_NOT_FOUND',
+  AUTH_REQUIRED: 'AUTH_REQUIRED',
+  ORG_NOT_FOUND: 'ORG_NOT_FOUND'
+} as const

package/src/platform/constants/index.ts

@@ -0,0 +1,5 @@
+export * from './versions'
+export * from './http'
+export * from './timeouts'
+export * from './limits'
+export * from './resilience'

package/src/platform/constants/limits.ts

@@ -0,0 +1,32 @@
+/**
+ * Limit Constants
+ * All "how many before we stop?" defaults.
+ * Quantities (not durations).
+ */
+
+/** Max concurrent session memory keys before oldest are evicted. */
+export const MAX_SESSION_MEMORY_KEYS = 25
+
+/** Total token budget for agent memory (history + session). */
+export const MAX_MEMORY_TOKENS = 32_000
+
+/** Max tokens for a single memory entry before truncation. */
+export const MAX_SINGLE_ENTRY_TOKENS = 2_000
+
+/** Max tokens for a single tool result stored in history before truncation. */
+export const MAX_TOOL_RESULT_TOKENS = 4_000
+
+/** Max execution requests per org per minute (token bucket refill rate + capacity). */
+export const EXECUTION_RATE_LIMIT_PER_MINUTE = 120
+
+/** Global WebSocket connection limit across all orgs. */
+export const WS_MAX_GLOBAL_CONNECTIONS = 5_000
+
+/** Max WebSocket connections per session (covers tabs, reconnect overlap). */
+export const WS_MAX_CONNECTIONS_PER_SESSION = 5
+
+/** Max inbound WebSocket messages per connection per minute. */
+export const WS_MAX_MESSAGES_PER_MINUTE = 60
+
+/** Minimum interval between WebSocket messages in ms (burst protection). */
+export const WS_MIN_MESSAGE_INTERVAL_MS = 1_000

package/src/platform/constants/resilience.ts

@@ -0,0 +1,51 @@
+/**
+ * Resilience Constants
+ * All "how do we recover from failure?" defaults.
+ * Retry policies, backoff, rate limiting, circuit breaker thresholds.
+ *
+ * Note: import type avoids runtime circular dependency with ../resilience/
+ * (constants/ provides values, resilience/ provides types).
+ */
+
+import type { RetryPolicy } from '../resilience/rate-limiter-types'
+
+/** Max LLM call attempts (initial + retries). */
+export const LLM_MAX_ATTEMPTS = 3
+
+/** Exponential backoff delays between LLM retries. */
+export const LLM_RETRY_DELAYS = [1_000, 2_000, 4_000] as const // 1s, 2s, 4s
+
+/** Default retry policy for rate-limited operations. */
+export const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  maxRetries: 3,
+  initialDelayMs: 1_000,
+  maxDelayMs: 10_000,
+  jitterFactor: 0.3
+}
+
+/** Default rate limiter bucket capacity (requests per window). */
+export const DEFAULT_RATE_LIMIT_CAPACITY = 300
+
+/** Integration service rate limit: requests per org per integration per window. */
+export const INTEGRATION_RATE_LIMIT_CAPACITY = 300
+
+/** Integration service rate limit window. */
+export const INTEGRATION_RATE_LIMIT_WINDOW_MS = 60_000 // 1min
+
+/** Rate limiter refill window. */
+export const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000 // 1min
+
+/** Rate limiter: evict buckets inactive for N * refill interval. */
+export const STALE_BUCKET_MULTIPLIER = 5
+
+/** Circuit breaker: failures before opening. */
+export const CIRCUIT_BREAKER_FAILURE_THRESHOLD = 5
+
+/** Circuit breaker: cooldown before half-open probe. */
+export const CIRCUIT_BREAKER_COOLDOWN_MS = 60_000 // 60s
+
+/** Circuit breaker: successes in half-open to close. */
+export const CIRCUIT_BREAKER_SUCCESS_THRESHOLD = 2
+
+/** Circuit breaker: max concurrent requests in half-open state. */
+export const CIRCUIT_BREAKER_HALF_OPEN_MAX_REQUESTS = 3

package/src/platform/constants/timeouts.ts

@@ -0,0 +1,20 @@
+/**
+ * Timeout Constants
+ * All "how long before we give up?" defaults.
+ * Values in milliseconds.
+ *
+ * Philosophy: "Detect failure, not limit duration."
+ * @see /in-progress/active-development/execution-engine-audit/timeout-strategy
+ */
+
+/** LLM API call timeout. Reasoning models + structured output take 60-180s. Matches SDK vendor default. */
+export const DEFAULT_LLM_TIMEOUT = 600_000 // 10min
+
+/** Tool execution timeout. Most HTTP tools complete in 5-30s. Integration tools that poll external services (e.g. Apify) may need up to 30min. */
+export const DEFAULT_TOOL_TIMEOUT = 1_800_000 // 30min
+
+/** Nested agent/workflow execution timeout. */
+export const DEFAULT_RESOURCE_INVOCATION_TIMEOUT = 1_800_000 // 30min
+
+/** Agent execution ceiling. Safety net for runaway loops. Override via constraints.timeout. */
+export const DEFAULT_EXECUTION_TIMEOUT = 7_200_000 // 2hr

package/src/platform/constants/versions.ts

@@ -0,0 +1,3 @@
+export const VERSION = {
+  CURRENT: '1.5.5'
+}

package/src/platform/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Platform group barrel - browser-safe exports
+ *
+ * Infrastructure foundation: constants, utilities, registry, SSE, API types
+ */
+
+// Shared constants
+export * from './constants/index'
+
+// Core utilities
+export * from './utils/index'
+
+// Resource Registry
+export * from './registry/index'
+
+// Serialized types (for CLI and frontend usage)
+export type {
+  SerializedAgentDefinition,
+  SerializedWorkflowDefinition,
+  SerializedExecutionInterface
+} from './registry/serialized-types'
+
+// SSE event types (shared between backend and frontend)
+export * from './sse/index'
+
+// API types (error responses shared with frontend)
+export * from './api/index'

package/src/platform/registry/__tests__/command-view.test.ts

@@ -0,0 +1,410 @@
+/**
+ * Test: Command View Type Guards and Helper Functions
+ * Tests for type guards and utility functions in command-view.ts
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  isAgent,
+  isWorkflow,
+  isTrigger,
+  isIntegration,
+  isExternalResource,
+  isHumanCheckpoint,
+  getNodeId,
+  getNodeType,
+  type CommandViewAgent,
+  type CommandViewWorkflow,
+  type CommandViewNode
+} from '../command-view'
+import type {
+  TriggerDefinition,
+  IntegrationDefinition,
+  ExternalResourceDefinition,
+  HumanCheckpointDefinition
+} from '../types'
+
+// ============================================================================
+// Mock Data - All resources follow new unified schema
+// ============================================================================
+
+const mockAgent: CommandViewAgent = {
+  resourceId: 'test-agent-123',
+  name: 'Test Agent',
+  description: 'A test agent for unit testing',
+  version: '1.0.0',
+  type: 'agent',
+  status: 'dev',
+  modelProvider: 'anthropic',
+  modelId: 'claude-sonnet-4-20250514',
+  toolCount: 5,
+  hasKnowledgeMap: true,
+  hasMemory: false,
+  domains: ['support', 'sales']
+}
+
+const mockWorkflow: CommandViewWorkflow = {
+  resourceId: 'test-workflow-456',
+  name: 'Test Workflow',
+  description: 'A test workflow for unit testing',
+  version: '2.1.0',
+  type: 'workflow',
+  status: 'prod',
+  stepCount: 3,
+  entryPoint: 'start',
+  domains: ['support']
+}
+
+const mockTrigger: TriggerDefinition = {
+  resourceId: 'test-trigger-789',
+  name: 'Test Webhook Trigger',
+  description: 'A test webhook trigger',
+  version: '1.0.0',
+  type: 'trigger',
+  status: 'prod',
+  triggerType: 'webhook',
+  webhookPath: '/webhooks/shopify/orders',
+  triggers: {
+    workflows: ['test-workflow-456']
+  }
+}
+
+const mockIntegration: IntegrationDefinition = {
+  resourceId: 'integration-shopify-prod',
+  name: 'Shopify Production',
+  description: 'E-commerce platform integration',
+  version: '1.0.0',
+  type: 'integration',
+  status: 'prod',
+  provider: 'shopify',
+  credentialName: 'shopify-prod'
+}
+
+const mockExternalResource: ExternalResourceDefinition = {
+  resourceId: 'external-n8n-sync',
+  name: 'N8N Order Sync',
+  description: 'Legacy n8n workflow for syncing orders',
+  version: '1.0.0',
+  type: 'external',
+  status: 'prod',
+  platform: 'n8n',
+  platformUrl: 'https://n8n.client.com/workflow/123',
+  externalId: 'n8n-workflow-123',
+  triggers: {
+    workflows: ['test-workflow-456']
+  },
+  uses: {
+    integrations: ['integration-shopify-prod']
+  }
+}
+
+const mockHumanCheckpoint: HumanCheckpointDefinition = {
+  resourceId: 'sales-approval',
+  name: 'Sales Approval Queue',
+  description: 'High-value order approvals for sales team',
+  version: '1.0.0',
+  type: 'human',
+  status: 'prod',
+  requestedBy: {
+    agents: ['test-agent-123']
+  },
+  routesTo: {
+    workflows: ['test-workflow-456']
+  }
+}
+
+// ============================================================================
+// Type Guard Tests
+// ============================================================================
+
+describe('Command View Type Guards', () => {
+  describe('isAgent', () => {
+    it('returns true for agent nodes', () => {
+      expect(isAgent(mockAgent)).toBe(true)
+    })
+
+    it('returns false for workflow nodes', () => {
+      expect(isAgent(mockWorkflow)).toBe(false)
+    })
+
+    it('returns false for trigger nodes', () => {
+      expect(isAgent(mockTrigger)).toBe(false)
+    })
+
+    it('returns false for integration nodes', () => {
+      expect(isAgent(mockIntegration)).toBe(false)
+    })
+
+    it('returns false for external resource nodes', () => {
+      expect(isAgent(mockExternalResource)).toBe(false)
+    })
+
+    it('returns false for human checkpoint nodes', () => {
+      expect(isAgent(mockHumanCheckpoint)).toBe(false)
+    })
+  })
+
+  describe('isWorkflow', () => {
+    it('returns true for workflow nodes', () => {
+      expect(isWorkflow(mockWorkflow)).toBe(true)
+    })
+
+    it('returns false for agent nodes', () => {
+      expect(isWorkflow(mockAgent)).toBe(false)
+    })
+
+    it('returns false for trigger nodes', () => {
+      expect(isWorkflow(mockTrigger)).toBe(false)
+    })
+
+    it('returns false for integration nodes', () => {
+      expect(isWorkflow(mockIntegration)).toBe(false)
+    })
+
+    it('returns false for external resource nodes', () => {
+      expect(isWorkflow(mockExternalResource)).toBe(false)
+    })
+
+    it('returns false for human checkpoint nodes', () => {
+      expect(isWorkflow(mockHumanCheckpoint)).toBe(false)
+    })
+  })
+
+  describe('isTrigger', () => {
+    it('returns true for webhook trigger nodes', () => {
+      expect(isTrigger(mockTrigger)).toBe(true)
+    })
+
+    it('verifies trigger detection uses triggerType field', () => {
+      // Trigger is identified by presence of triggerType field
+      expect('triggerType' in mockTrigger).toBe(true)
+      expect(mockTrigger.triggerType).toBe('webhook')
+    })
+
+    it('returns false for agent nodes', () => {
+      expect(isTrigger(mockAgent)).toBe(false)
+    })
+
+    it('returns false for workflow nodes', () => {
+      expect(isTrigger(mockWorkflow)).toBe(false)
+    })
+
+    it('returns false for integration nodes', () => {
+      expect(isTrigger(mockIntegration)).toBe(false)
+    })
+
+    it('returns false for external resource nodes', () => {
+      expect(isTrigger(mockExternalResource)).toBe(false)
+    })
+
+    it('returns false for human checkpoint nodes', () => {
+      expect(isTrigger(mockHumanCheckpoint)).toBe(false)
+    })
+  })
+
+  describe('isIntegration', () => {
+    it('returns true for integration nodes (type === integration)', () => {
+      expect(isIntegration(mockIntegration)).toBe(true)
+      expect(mockIntegration.type).toBe('integration')
+    })
+
+    it('returns false for agent nodes', () => {
+      expect(isIntegration(mockAgent)).toBe(false)
+    })
+
+    it('returns false for workflow nodes', () => {
+      expect(isIntegration(mockWorkflow)).toBe(false)
+    })
+
+    it('returns false for trigger nodes', () => {
+      expect(isIntegration(mockTrigger)).toBe(false)
+    })
+
+    it('returns false for external resource nodes', () => {
+      expect(isIntegration(mockExternalResource)).toBe(false)
+    })
+
+    it('returns false for human checkpoint nodes', () => {
+      expect(isIntegration(mockHumanCheckpoint)).toBe(false)
+    })
+  })
+
+  describe('isExternalResource', () => {
+    it('returns true for external resource nodes (has platform)', () => {
+      expect(isExternalResource(mockExternalResource)).toBe(true)
+      expect('platform' in mockExternalResource).toBe(true)
+      expect(mockExternalResource.platform).toBe('n8n')
+    })
+
+    it('returns false for agent nodes', () => {
+      expect(isExternalResource(mockAgent)).toBe(false)
+    })
+
+    it('returns false for workflow nodes', () => {
+      expect(isExternalResource(mockWorkflow)).toBe(false)
+    })
+
+    it('returns false for trigger nodes', () => {
+      expect(isExternalResource(mockTrigger)).toBe(false)
+    })
+
+    it('returns false for integration nodes', () => {
+      expect(isExternalResource(mockIntegration)).toBe(false)
+    })
+
+    it('returns false for human checkpoint nodes', () => {
+      expect(isExternalResource(mockHumanCheckpoint)).toBe(false)
+    })
+  })
+
+  describe('isHumanCheckpoint', () => {
+    it('returns true for human checkpoint nodes with requestedBy', () => {
+      const checkpoint: HumanCheckpointDefinition = {
+        resourceId: 'checkpoint-1',
+        name: 'Approval',
+        description: 'Approval checkpoint',
+        version: '1.0.0',
+        type: 'human',
+        status: 'prod',
+        requestedBy: {
+          agents: ['test-agent-123']
+        }
+      }
+      expect(isHumanCheckpoint(checkpoint)).toBe(true)
+    })
+
+    it('returns true for human checkpoint nodes with routesTo', () => {
+      const checkpoint: HumanCheckpointDefinition = {
+        resourceId: 'checkpoint-2',
+        name: 'Router',
+        description: 'Routing checkpoint',
+        version: '1.0.0',
+        type: 'human',
+        status: 'prod',
+        routesTo: {
+          workflows: ['test-workflow-456']
+        }
+      }
+      expect(isHumanCheckpoint(checkpoint)).toBe(true)
+    })
+
+    it('returns true for human checkpoint nodes with both requestedBy and routesTo', () => {
+      expect(isHumanCheckpoint(mockHumanCheckpoint)).toBe(true)
+      expect('requestedBy' in mockHumanCheckpoint).toBe(true)
+      expect('routesTo' in mockHumanCheckpoint).toBe(true)
+    })
+
+    it('returns false for agent nodes', () => {
+      expect(isHumanCheckpoint(mockAgent)).toBe(false)
+    })
+
+    it('returns false for workflow nodes', () => {
+      expect(isHumanCheckpoint(mockWorkflow)).toBe(false)
+    })
+
+    it('returns false for trigger nodes', () => {
+      expect(isHumanCheckpoint(mockTrigger)).toBe(false)
+    })
+
+    it('returns false for integration nodes', () => {
+      expect(isHumanCheckpoint(mockIntegration)).toBe(false)
+    })
+
+    it('returns false for external resource nodes', () => {
+      expect(isHumanCheckpoint(mockExternalResource)).toBe(false)
+    })
+  })
+})
+
+// ============================================================================
+// Helper Function Tests
+// ============================================================================
+
+describe('Command View Helper Functions', () => {
+  describe('getNodeId', () => {
+    it('returns resourceId for agent nodes', () => {
+      expect(getNodeId(mockAgent)).toBe('test-agent-123')
+    })
+
+    it('returns resourceId for workflow nodes', () => {
+      expect(getNodeId(mockWorkflow)).toBe('test-workflow-456')
+    })
+
+    it('returns resourceId for trigger nodes', () => {
+      expect(getNodeId(mockTrigger)).toBe('test-trigger-789')
+    })
+
+    it('returns resourceId for integration nodes', () => {
+      expect(getNodeId(mockIntegration)).toBe('integration-shopify-prod')
+    })
+
+    it('returns resourceId for external resource nodes', () => {
+      expect(getNodeId(mockExternalResource)).toBe('external-n8n-sync')
+    })
+
+    it('returns resourceId for human checkpoint nodes', () => {
+      expect(getNodeId(mockHumanCheckpoint)).toBe('sales-approval')
+    })
+
+    it('verifies all nodes use unified resourceId field', () => {
+      const nodes: CommandViewNode[] = [
+        mockAgent,
+        mockWorkflow,
+        mockTrigger,
+        mockIntegration,
+        mockExternalResource,
+        mockHumanCheckpoint
+      ]
+
+      nodes.forEach((node) => {
+        expect(node).toHaveProperty('resourceId')
+        expect(typeof node.resourceId).toBe('string')
+        expect(node.resourceId.length).toBeGreaterThan(0)
+      })
+    })
+  })
+
+  describe('getNodeType', () => {
+    it('returns "agent" for agent nodes', () => {
+      expect(getNodeType(mockAgent)).toBe('agent')
+    })
+
+    it('returns "workflow" for workflow nodes', () => {
+      expect(getNodeType(mockWorkflow)).toBe('workflow')
+    })
+
+    it('returns "trigger" for trigger nodes', () => {
+      expect(getNodeType(mockTrigger)).toBe('trigger')
+    })
+
+    it('returns "integration" for integration nodes', () => {
+      expect(getNodeType(mockIntegration)).toBe('integration')
+    })
+
+    it('returns "external" for external resource nodes', () => {
+      expect(getNodeType(mockExternalResource)).toBe('external')
+    })
+
+    it('returns "human" for human checkpoint nodes', () => {
+      expect(getNodeType(mockHumanCheckpoint)).toBe('human')
+    })
+
+    it('handles all node types in collection', () => {
+      const nodes: CommandViewNode[] = [
+        mockAgent,
+        mockWorkflow,
+        mockTrigger,
+        mockIntegration,
+        mockExternalResource,
+        mockHumanCheckpoint
+      ]
+
+      const expectedTypes = ['agent', 'workflow', 'trigger', 'integration', 'external', 'human']
+
+      nodes.forEach((node, index) => {
+        expect(getNodeType(node)).toBe(expectedTypes[index])
+      })
+    })
+  })
+})
+