@elevasis/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1561 @@
+import { z } from 'zod';
+
+/**
+ * Error categories for observability grouping and classification.
+ * Used to categorize errors in the execution_errors table metadata.
+ */
+type ExecutionErrorCategory = 'llm' | 'tool' | 'workflow' | 'agent' | 'validation' | 'system';
+/**
+ * Abstract base class for all execution engine errors.
+ * Enforces contract for execution_errors table insertion with explicit type,
+ * severity, category, and context properties.
+ *
+ * All execution engine errors MUST extend this class to ensure proper error
+ * tracking and observability in the execution_errors table.
+ *
+ * @example
+ * ```typescript
+ * export class MyExecutionError extends ExecutionError {
+ *   readonly type = 'my_execution_error' as const
+ *   readonly severity = 'warning' as const
+ *   readonly category = 'workflow' as const
+ *
+ *   constructor(message: string, context?: Record<string, unknown>) {
+ *     super(message, context)
+ *   }
+ * }
+ * ```
+ */
+declare abstract class ExecutionError extends Error {
+    /**
+     * Error type identifier for execution_errors table.
+     * Should be a unique, snake_case string that identifies this specific error class.
+     * Used for filtering, aggregation, and error-specific handling in observability systems.
+     */
+    abstract readonly type: string;
+    /**
+     * Error severity level for execution_errors table.
+     * - critical: System failures, auth issues, resource exhaustion - execution cannot continue
+     * - warning: Transient failures, configuration errors - execution may retry or requires user correction
+     * - info: Validation failures, expected user errors - user/developer action needed
+     */
+    abstract readonly severity: 'critical' | 'warning' | 'info';
+    /**
+     * Error category for observability grouping.
+     * Used to categorize errors in dashboards and analytics.
+     */
+    abstract readonly category: ExecutionErrorCategory;
+    /**
+     * Additional context/metadata for the error.
+     * Stored in execution_errors.metadata JSONB column.
+     */
+    readonly context?: Record<string, unknown>;
+    /**
+     * @param message - Human-readable error message
+     * @param context - Additional context/metadata for observability
+     */
+    constructor(message: string, context?: Record<string, unknown>);
+    /**
+     * Indicates whether this error type is retryable.
+     * Default: false (safe default - only retry when explicitly safe to do so)
+     *
+     * Subclasses should override to return true for retryable scenarios:
+     * - Network/infrastructure errors (exponential backoff)
+     * - Rate limiting (linear backoff)
+     * - Service availability (exponential backoff)
+     * - Circuit breaker (circuit breaker's own delay)
+     *
+     * DO NOT retry:
+     * - Authentication/authorization errors
+     * - Validation errors
+     * - Configuration errors
+     * - Resource exhaustion errors
+     */
+    isRetryable(): boolean;
+}
+
+/**
+ * Workflow-specific logging types
+ */
+
+interface WorkflowExecutionContext {
+    type: 'workflow';
+    contextType: 'workflow-execution';
+    executionId: string;
+    workflowId: string;
+    workflowName?: string;
+    organizationId: string;
+    executionPath?: string[];
+}
+interface WorkflowFailureContext {
+    type: 'workflow';
+    contextType: 'workflow-failure';
+    executionId: string;
+    workflowId: string;
+    error: string;
+}
+interface StepStartedContext {
+    type: 'workflow';
+    contextType: 'step-started';
+    stepId: string;
+    stepStatus: 'started';
+    input: unknown;
+    startTime: number;
+}
+interface StepCompletedContext {
+    type: 'workflow';
+    contextType: 'step-completed';
+    stepId: string;
+    stepStatus: 'completed';
+    output: unknown;
+    duration: number;
+    isTerminal: boolean;
+    startTime: number;
+    endTime: number;
+}
+interface StepFailedContext {
+    type: 'workflow';
+    contextType: 'step-failed';
+    stepId: string;
+    stepStatus: 'failed';
+    error: string;
+    duration: number;
+    startTime: number;
+    endTime: number;
+}
+interface ConditionalRouteContext {
+    type: 'workflow';
+    contextType: 'conditional-route';
+    stepId: string;
+    target: string;
+    error?: string;
+}
+interface ExecutionPathContext {
+    type: 'workflow';
+    contextType: 'execution-path';
+    executionPath: string[];
+}
+type WorkflowLogContext = WorkflowExecutionContext | WorkflowFailureContext | StepStartedContext | StepCompletedContext | StepFailedContext | ConditionalRouteContext | ExecutionPathContext;
+
+/**
+ * Agent-specific logging types
+ * Simplified 2-event model: lifecycle, iteration
+ *
+ * Design Philosophy:
+ * - LIFECYCLE EVENTS: Structural checkpoints (initialization, iteration, completion)
+ * - ITERATION EVENTS: Execution activities (reasoning, actions during iterations)
+ */
+
+/**
+ * Agent lifecycle stages
+ * Universal checkpoints that apply to all agent executions
+ */
+type AgentLifecycle = 'initialization' | 'iteration' | 'completion';
+/**
+ * Iteration event types
+ * Activities that occur during agent iterations
+ */
+type IterationEventType = 'reasoning' | 'action' | 'tool-call';
+/**
+ * Base fields shared by all lifecycle events
+ */
+interface AgentLifecycleEventBase {
+    type: 'agent';
+    agentId: string;
+    lifecycle: AgentLifecycle;
+    sessionId?: string;
+}
+/**
+ * Lifecycle started event - emitted when a phase begins
+ * REQUIRED: startTime (phase has started, no end yet)
+ */
+interface AgentLifecycleStartedEvent extends AgentLifecycleEventBase {
+    stage: 'started';
+    startTime: number;
+    iteration?: number;
+}
+/**
+ * Lifecycle completed event - emitted when a phase succeeds
+ * REQUIRED: startTime, endTime, duration (phase has finished successfully)
+ */
+interface AgentLifecycleCompletedEvent extends AgentLifecycleEventBase {
+    stage: 'completed';
+    startTime: number;
+    endTime: number;
+    duration: number;
+    iteration?: number;
+    attempts?: number;
+    memorySize?: {
+        sessionMemoryKeys: number;
+        historyEntries: number;
+    };
+}
+/**
+ * Lifecycle failed event - emitted when a phase fails
+ * REQUIRED: startTime, endTime, duration, error (phase has finished with error)
+ */
+interface AgentLifecycleFailedEvent extends AgentLifecycleEventBase {
+    stage: 'failed';
+    startTime: number;
+    endTime: number;
+    duration: number;
+    error: string;
+    iteration?: number;
+}
+/**
+ * Union type for all lifecycle events
+ * Discriminated by 'stage' field for type narrowing
+ */
+type AgentLifecycleEvent = AgentLifecycleStartedEvent | AgentLifecycleCompletedEvent | AgentLifecycleFailedEvent;
+/**
+ * Placeholder data for MVP
+ * Will be typed per actionType in future
+ */
+interface ActionPlaceholderData {
+    message: string;
+}
+/**
+ * Iteration event - captures activities during agent iterations
+ * Consolidates reasoning (LLM thought process) and actions (tool use, memory ops, etc.)
+ */
+interface AgentIterationEvent {
+    type: 'agent';
+    agentId: string;
+    lifecycle: 'iteration';
+    eventType: IterationEventType;
+    iteration: number;
+    sessionId?: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    output?: string;
+    actionType?: string;
+    data?: ActionPlaceholderData;
+}
+/**
+ * Tool call event - captures individual tool executions during iterations
+ * Provides granular timing for each tool invocation
+ */
+interface AgentToolCallEvent {
+    type: 'agent';
+    agentId: string;
+    lifecycle: 'iteration';
+    eventType: 'tool-call';
+    iteration: number;
+    sessionId?: string;
+    toolName: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    success: boolean;
+    error?: string;
+    input?: Record<string, unknown>;
+    output?: unknown;
+}
+/**
+ * Union type for all agent log contexts
+ * 3 event types total (lifecycle, iteration, tool-call)
+ */
+type AgentLogContext = AgentLifecycleEvent | AgentIterationEvent | AgentToolCallEvent;
+/**
+ * Data for lifecycle 'started' events
+ */
+interface AgentLifecycleStartedData {
+    startTime: number;
+    iteration?: number;
+}
+/**
+ * Data for lifecycle 'completed' events
+ */
+interface AgentLifecycleCompletedData {
+    startTime: number;
+    endTime: number;
+    duration: number;
+    iteration?: number;
+    attempts?: number;
+    memorySize?: {
+        sessionMemoryKeys: number;
+        historyEntries: number;
+    };
+}
+/**
+ * Data for lifecycle 'failed' events
+ */
+interface AgentLifecycleFailedData {
+    startTime: number;
+    endTime: number;
+    duration: number;
+    error: string;
+    iteration?: number;
+}
+/**
+ * Scoped logger for agent execution
+ * Captures logger and agentId to eliminate repetitive parameter passing
+ *
+ * Type-safe lifecycle logging with stage-specific required fields
+ */
+interface AgentScopedLogger {
+    lifecycle(lifecycle: AgentLifecycle, stage: 'started', data: AgentLifecycleStartedData): void;
+    lifecycle(lifecycle: AgentLifecycle, stage: 'completed', data: AgentLifecycleCompletedData): void;
+    lifecycle(lifecycle: AgentLifecycle, stage: 'failed', data: AgentLifecycleFailedData): void;
+    reasoning(output: string, iteration: number, startTime: number, endTime: number, duration: number): void;
+    action(actionType: string, message: string, iteration: number, startTime: number, endTime: number, duration: number): void;
+    toolCall(toolName: string, iteration: number, startTime: number, endTime: number, duration: number, success: boolean, error?: string, input?: unknown, output?: unknown): void;
+}
+
+type LogContext = WorkflowLogContext | AgentLogContext;
+interface IExecutionLogger {
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext): void;
+}
+
+/**
+ * Shared form field types for dynamic form generation
+ * Used by: Command Queue, Execution Runner UI, future form-based features
+ */
+/**
+ * Supported form field types for action payloads
+ * Maps to Mantine form components
+ */
+type FormFieldType = 'text' | 'textarea' | 'number' | 'select' | 'checkbox' | 'radio' | 'richtext';
+/**
+ * Form field definition
+ */
+interface FormField {
+    /** Field key in payload object */
+    name: string;
+    /** Field label for UI */
+    label: string;
+    /** Field type (determines UI component) */
+    type: FormFieldType;
+    /** Default value */
+    defaultValue?: unknown;
+    /** Required field */
+    required?: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Help text */
+    description?: string;
+    /** Options for select/radio */
+    options?: Array<{
+        label: string;
+        value: string | number;
+    }>;
+    /** Min/max for number */
+    min?: number;
+    max?: number;
+    /** Path to context value for pre-filling (dot notation, e.g., 'proposal.summary') */
+    defaultValueFromContext?: string;
+}
+/**
+ * Form schema for action payload collection
+ */
+interface FormSchema {
+    /** Form title */
+    title?: string;
+    /** Form description */
+    description?: string;
+    /** Form fields */
+    fields: FormField[];
+    /** Layout (default: 'vertical') */
+    layout?: 'vertical' | 'horizontal' | 'grid';
+}
+
+/**
+ * Model Configuration
+ * Centralized model information, configuration, options, constraints, and validation
+ * Single source of truth for all model-related definitions
+ * Update manually when pricing changes or new models are added
+ */
+
+/**
+ * Supported Open AI models (direct SDK access)
+ */
+type OpenAIModel = 'gpt-5' | 'gpt-5-mini';
+/**
+ * Supported OpenRouter models (explicit union for type safety)
+ */
+type OpenRouterModel = 'openrouter/anthropic/claude-sonnet-4.5' | 'openrouter/deepseek/deepseek-v3.2' | 'openrouter/x-ai/grok-4.1-fast';
+/**
+ * Supported Google models (direct SDK access)
+ */
+type GoogleModel = 'gemini-3-flash-preview';
+/**
+ * Supported Anthropic models (direct SDK access via @anthropic-ai/sdk)
+ * Using aliases for automatic updates to latest versions
+ */
+type AnthropicModel = 'claude-opus-4-5' | 'claude-sonnet-4-5' | 'claude-haiku-4-5';
+/** Supported LLM models */
+type LLMModel = OpenAIModel | OpenRouterModel | GoogleModel | AnthropicModel | 'mock';
+/**
+ * GPT-5 model options schema
+ */
+declare const GPT5OptionsSchema: z.ZodObject<{
+    reasoning_effort: z.ZodOptional<z.ZodEnum<{
+        minimal: "minimal";
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+    verbosity: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+}, z.core.$strip>;
+/**
+ * OpenRouter model options schema
+ * OpenRouter-specific options for routing and transforms
+ */
+declare const OpenRouterOptionsSchema: z.ZodObject<{
+    transforms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    route: z.ZodOptional<z.ZodEnum<{
+        fallback: "fallback";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Google model options schema
+ * Gemini 3 specific options for thinking depth control
+ */
+declare const GoogleOptionsSchema: z.ZodObject<{
+    thinkingLevel: z.ZodOptional<z.ZodEnum<{
+        minimal: "minimal";
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Anthropic model options schema
+ * Currently empty - future options: budget_tokens for extended thinking
+ */
+declare const AnthropicOptionsSchema: z.ZodObject<{}, z.core.$strip>;
+/**
+ * Infer TypeScript types from schemas
+ */
+type GPT5Options = z.infer<typeof GPT5OptionsSchema>;
+type MockOptions = Record<string, never>;
+type OpenRouterOptions = z.infer<typeof OpenRouterOptionsSchema>;
+type GoogleOptions = z.infer<typeof GoogleOptionsSchema>;
+type AnthropicOptions = z.infer<typeof AnthropicOptionsSchema>;
+type ModelSpecificOptions = GPT5Options | MockOptions | OpenRouterOptions | GoogleOptions | AnthropicOptions;
+/**
+ * Model configuration for LLM execution
+ * Belongs in resource definition (AgentDefinition, WorkflowDefinition, etc.)
+ */
+interface ModelConfig {
+    model: LLMModel;
+    provider: 'openai' | 'anthropic' | 'openrouter' | 'google' | 'mock';
+    apiKey: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    /**
+     * Model-specific options (flat structure)
+     * Options are model-specific, not vendor-specific
+     * Available options defined in MODEL_INFO per model
+     * Validated at build time via validateModelOptions()
+     */
+    modelOptions?: ModelSpecificOptions;
+}
+
+/**
+ * Execution interface configuration
+ * Defines how a resource is executed via the UI (forms, scheduling, webhooks)
+ * Applies to both agents and workflows
+ */
+interface ExecutionInterface {
+    /** Form configuration for execution inputs */
+    form: ExecutionFormSchema;
+    /** Optional: Schedule configuration */
+    schedule?: ScheduleConfig;
+    /** Optional: Webhook trigger configuration */
+    webhook?: WebhookConfig;
+}
+/**
+ * Execution form schema
+ * Extends FormSchema with execution-specific fields
+ */
+interface ExecutionFormSchema extends FormSchema {
+    /**
+     * Field mappings to resource input schema
+     * Maps form field names to contract input paths
+     * If omitted, field names must match contract input keys exactly
+     */
+    fieldMappings?: Record<string, string>;
+    /**
+     * Submit button configuration
+     * Default: { label: 'Run', loadingLabel: 'Running...' }
+     */
+    submitButton?: {
+        label?: string;
+        loadingLabel?: string;
+        confirmMessage?: string;
+    };
+}
+/**
+ * Schedule configuration for automated execution
+ */
+interface ScheduleConfig {
+    /** Whether scheduling is enabled for this resource */
+    enabled: boolean;
+    /** Default schedule (cron expression) */
+    defaultSchedule?: string;
+    /** Allowed schedule patterns (if restricted) */
+    allowedPatterns?: string[];
+}
+/**
+ * Webhook configuration for external triggers
+ */
+interface WebhookConfig {
+    /** Whether webhook trigger is enabled */
+    enabled: boolean;
+    /** Expected payload schema (for documentation) */
+    payloadSchema?: unknown;
+}
+
+interface WorkflowConfig extends ResourceDefinition {
+    type: 'workflow';
+}
+interface WorkflowStepDefinition {
+    id: string;
+    name: string;
+    description: string;
+}
+type StepHandler = (input: unknown, context: ExecutionContext) => Promise<unknown>;
+declare enum StepType {
+    LINEAR = "linear",
+    CONDITIONAL = "conditional"
+}
+interface LinearNext {
+    type: StepType.LINEAR;
+    target: string;
+}
+interface ConditionalNext {
+    type: StepType.CONDITIONAL;
+    routes: Array<{
+        condition: (data: unknown) => boolean;
+        target: string;
+    }>;
+    default: string;
+}
+type NextConfig = LinearNext | ConditionalNext | null;
+interface WorkflowStep extends WorkflowStepDefinition {
+    handler: StepHandler;
+    inputSchema: z.ZodSchema;
+    outputSchema: z.ZodSchema;
+    next: NextConfig;
+}
+interface WorkflowDefinition {
+    config: WorkflowConfig;
+    contract: Contract;
+    steps: Record<string, WorkflowStep>;
+    entryPoint: string;
+    /**
+     * Metrics configuration for ROI calculations
+     * Optional: Only needed if tracking automation savings
+     */
+    metricsConfig?: ResourceMetricsConfig;
+    /**
+     * Execution interface configuration (optional)
+     * If provided, workflow appears in Execution Runner UI
+     */
+    interface?: ExecutionInterface;
+}
+
+/**
+ * Memory type definitions
+ * Types for agent memory management with semantic entry types
+ */
+/**
+ * Semantic memory entry types
+ * Use-case agnostic types that describe the purpose of each entry
+ * Memory types mirror action types for clarity and filtering
+ */
+type MemoryEntryType = 'context' | 'input' | 'reasoning' | 'tool-result' | 'delegation-result' | 'error';
+/**
+ * Memory entry - represents a single entry in agent memory
+ * Stored in agent memory, translated by adapters to vendor-specific formats
+ */
+interface MemoryEntry {
+    type: MemoryEntryType;
+    content: string;
+    timestamp: number;
+    turnNumber: number | null;
+    iterationNumber: number | null;
+}
+/**
+ * Agent memory - Self-orchestrated memory with session + working storage
+ * Agent has full control over what persists, framework handles auto-compaction
+ */
+interface AgentMemory {
+    /**
+     * Session memory - Persists for session/conversation duration
+     * Never auto-trimmed by framework
+     * Agent-managed key-value store for critical information
+     * Agent provides strings, framework wraps in MemoryEntry
+     */
+    sessionMemory: Record<string, MemoryEntry>;
+    /**
+     * Working memory - Execution history
+     * Automatically compacted by framework when needed
+     * Agent doesn't control compaction
+     */
+    history: MemoryEntry[];
+}
+/**
+ * Memory status for agent awareness
+ */
+interface MemoryStatus {
+    sessionMemoryKeys: number;
+    sessionMemoryLimit: number;
+    currentKeys: string[];
+    historyPercent: number;
+    historyTokens: number;
+    tokenBudget: number;
+}
+/**
+ * Memory constraints (optional limits)
+ */
+interface MemoryConstraints {
+    maxSessionMemoryKeys?: number;
+    maxMemoryTokens?: number;
+}
+
+/**
+ * Memory Manager
+ * Encapsulates all memory operations with ultra-simple agent API
+ * Agent provides strings, framework handles wrapping and auto-compaction
+ */
+
+/**
+ * Memory Manager - Agent memory orchestration
+ * Provides ultra-simple API for agents (strings only)
+ * Handles automatic compaction and token management
+ */
+declare class MemoryManager {
+    private memory;
+    private constraints;
+    private logger?;
+    private cachedSnapshot?;
+    constructor(memory: AgentMemory, constraints?: MemoryConstraints, logger?: AgentScopedLogger | undefined);
+    /**
+     * Set session memory entry (agent provides string, framework wraps it)
+     * @param key - Session memory key
+     * @param content - String content from agent
+     */
+    set(key: string, content: string): void;
+    /**
+     * Get session memory entry content
+     * @param key - Session memory key
+     * @returns String content if exists, undefined otherwise
+     */
+    get(key: string): string | undefined;
+    /**
+     * Delete session memory entry
+     * @param key - Key to delete
+     * @returns True if key existed and was deleted
+     */
+    delete(key: string): boolean;
+    /**
+     * Add entry to history (called by framework after tool results, reasoning, etc.)
+     * Automatically sets timestamp to current time
+     * @param entry - Memory entry to add (without timestamp - auto-generated)
+     */
+    addToHistory(entry: Omit<MemoryEntry, 'timestamp'>): void;
+    /**
+     * Auto-compact history if approaching token budget
+     * Uses preserve-anchors strategy: keep first + recent entries
+     */
+    autoCompact(): void;
+    /**
+     * Enforce hard limits (called before LLM request)
+     * Emergency fallback if agent exceeds limits
+     */
+    enforceHardLimits(): void;
+    /**
+     * Get history length (for logging and introspection)
+     * @returns Number of entries in history
+     */
+    getHistoryLength(): number;
+    /**
+     * Get memory status for agent awareness
+     * @returns Memory status with token usage and key counts
+     */
+    getStatus(): MemoryStatus;
+    /**
+     * Create memory snapshot for persistence
+     * Caches snapshot internally for later retrieval
+     * @returns Deep copy of current memory state
+     */
+    toSnapshot(): AgentMemory;
+    /**
+     * Get cached memory snapshot
+     * Returns snapshot created by toSnapshot()
+     * @returns Cached snapshot (undefined if toSnapshot() not called yet)
+     */
+    getSnapshot(): AgentMemory | undefined;
+    /**
+     * Build context string for LLM
+     * Serializes sessionmemory + history memory with clear sections
+     * Shows current iteration entries FIRST (reverse chronological) for LLM attention
+     * @param currentIteration - Current iteration number (0 = pre-iteration)
+     * @param currentTurn - Current turn number (optional, for session context filtering)
+     * @returns Formatted memory context for LLM prompt
+     */
+    toContext(currentIteration: number, currentTurn?: number): string;
+}
+
+/**
+ * Knowledge Map Types
+ *
+ * Enables agents to navigate organizational knowledge through a lightweight
+ * graph that lazy-loads capabilities on-demand.
+ *
+ * @module agent/knowledge-map
+ */
+
+/**
+ * Lightweight knowledge map (passed as agent property)
+ *
+ * Contains metadata about available knowledge nodes without loading
+ * the full content upfront. Total size: ~300-500 tokens.
+ *
+ * Multi-tenancy is enforced via:
+ * - File-scoped maps (organizations/{org-name}/knowledge/)
+ * - ExecutionContext.organizationId passed to node.load()
+ */
+interface KnowledgeMap {
+    /** Available knowledge nodes indexed by ID */
+    nodes: Record<string, KnowledgeNode>;
+}
+/**
+ * Single knowledge source
+ *
+ * Represents a domain knowledge area (CRM, brand guidelines, Excel tools)
+ * that can be lazy-loaded to provide instructions and tools to agents.
+ */
+interface KnowledgeNode {
+    /** Unique identifier for this node (e.g., "crm", "brand-guidelines") */
+    id: string;
+    /**
+     * Description of when to use this knowledge
+     * Used for semantic matching against user intent
+     */
+    description: string;
+    /**
+     * Load knowledge content on-demand
+     *
+     * @param context - Execution context with organizationId for multi-tenancy
+     * @returns Promise resolving to knowledge content (prompt + optional tools)
+     */
+    load(context: ExecutionContext): Promise<KnowledgeContent>;
+    /**
+     * Loaded state flag
+     * Set to true after load() is called
+     */
+    loaded?: boolean;
+    /**
+     * Cached prompt (for system prompt serialization)
+     * Only the prompt is cached - tools go to toolRegistry, children flattened to nodes
+     */
+    prompt?: string;
+}
+/**
+ * Content returned by knowledge node
+ *
+ * Separates instructions (prompt) from capabilities (tools).
+ * Tools are optional - some nodes only provide context.
+ *
+ * Supports recursive navigation - nodes can contain child nodes
+ * that are discovered when the parent node is loaded.
+ */
+interface KnowledgeContent {
+    /** Instructions and context (markdown format) */
+    prompt: string;
+    /** Tool implementations (optional) */
+    tools?: Tool[];
+    /**
+     * Child knowledge nodes (optional, recursive)
+     *
+     * Enables hierarchical navigation: base → specialized → deep expertise.
+     * Child nodes are flattened into the main knowledge map when parent loads,
+     * making them available for subsequent navigate-knowledge actions.
+     *
+     * Example: CRM base node returns crm-customers and crm-deals as children
+     */
+    nodes?: Record<string, KnowledgeNode>;
+}
+
+/**
+ * Agent-specific type definitions
+ * Types for autonomous agents with tools, memory, and constraints
+ */
+
+interface AgentConfig extends ResourceDefinition {
+    type: 'agent';
+    systemPrompt: string;
+    constraints?: AgentConstraints;
+    /**
+     * Session capability declaration (opt-in)
+     * If true, agent is designed for multi-turn session interactions
+     * Controls whether agent can use message action and appears in Sessions UI
+     *
+     * Use for:
+     * - Conversational agents with multi-turn interactions
+     * - Agents requiring persistent context across turns
+     * - Agents that need human-in-the-loop communication
+     */
+    sessionCapable?: boolean;
+    /**
+     * Security level for system prompt hardening (auto-derived if omitted)
+     *
+     * - 'standard': Lightweight defense (3 rules) - default for non-session agents
+     * - 'hardened': Comprehensive defense (6 rules) - default for session-capable agents
+     * - 'none': No security prompt - for pure internal agents with no external input
+     *
+     * If omitted, derived from sessionCapable:
+     *   sessionCapable: true  -> 'hardened'
+     *   sessionCapable: false -> 'standard'
+     */
+    securityLevel?: 'standard' | 'hardened' | 'none';
+    /**
+     * Memory management preferences (opt-in)
+     * If provided, agent can use memoryOps to manage session memory
+     * If omitted, agent has no memory management capabilities
+     *
+     * Agent-specific guidance on what to preserve, when to persist, and what to clean up.
+     * This guidance is injected into the system prompt when memory management is enabled.
+     *
+     * Use for:
+     * - Conversational agents needing cross-turn context
+     * - Agents managing complex user preferences
+     * - Agents tracking decisions over multiple iterations
+     */
+    memoryPreferences?: string;
+}
+interface AgentConstraints {
+    maxIterations?: number;
+    timeout?: number;
+    maxSessionMemoryKeys?: number;
+    maxMemoryTokens?: number;
+}
+interface AgentDefinition {
+    config: AgentConfig;
+    contract: Contract;
+    tools: Tool[];
+    /**
+     * Model configuration for LLM execution
+     * Specifies provider, API key, and model-specific options
+     */
+    modelConfig: ModelConfig;
+    /**
+     * Optional knowledge map for lazy-loading capabilities
+     * Enables agents to navigate organizational knowledge on-demand
+     */
+    knowledgeMap?: KnowledgeMap;
+    /**
+     * Preload memory before execution starts
+     * Handles BOTH context loading AND session restoration
+     *
+     * @param context - Execution context (includes sessionId if session turn)
+     * @returns Initial AgentMemory state (sessionMemory entries + optionally history)
+     */
+    preloadMemory?: (context: ExecutionContext) => Promise<AgentMemory> | AgentMemory;
+    /**
+     * Metrics configuration for ROI calculations
+     * Optional: Only needed if tracking automation savings
+     */
+    metricsConfig?: ResourceMetricsConfig;
+    /**
+     * Execution interface configuration (optional)
+     * If provided, agent appears in Execution Runner UI
+     */
+    interface?: ExecutionInterface;
+}
+/**
+ * Agent execution context
+ * Groups all state needed for agent execution phases
+ */
+interface IterationContext {
+    config: AgentConfig;
+    contract: Contract;
+    toolRegistry: Map<string, Tool>;
+    memoryManager: MemoryManager;
+    executionContext: ExecutionContext;
+    iteration: number;
+    logger: AgentScopedLogger;
+    modelConfig: ModelConfig;
+    knowledgeMap?: KnowledgeMap;
+}
+
+/**
+ * ResourceRegistry - Resource discovery and lookup
+ * Handles resource definitions from OrganizationRegistry
+ *
+ * Features:
+ * - Resource discovery by organization
+ * - Startup validation (duplicate IDs, model configs, relationships, interface-schema alignment)
+ * - Pre-serialization cache for instant API responses
+ * - Command View data generation
+ */
+
+/**
+ * Organization-specific resource collection
+ *
+ * Complete manifest of all automation resources for an organization.
+ * Used by ResourceRegistry for discovery and Command View for visualization.
+ */
+interface OrganizationResources {
+    /** Workflow definitions */
+    workflows?: WorkflowDefinition[];
+    /** Agent definitions */
+    agents?: AgentDefinition[];
+    /** Trigger definitions - entry points that initiate executions */
+    triggers?: TriggerDefinition[];
+    /** Integration definitions - external service connections */
+    integrations?: IntegrationDefinition[];
+    /** Explicit relationship declarations between resources */
+    relationships?: ResourceRelationships;
+    /** External automation resources (n8n, Make, Zapier, etc.) */
+    externalResources?: ExternalResourceDefinition[];
+    /** Human checkpoint definitions - human decision points in automation */
+    humanCheckpoints?: HumanCheckpointDefinition[];
+}
+
+/**
+ * MetricsCollector
+ * Tracks execution timing and ROI metrics
+ */
+declare class MetricsCollector {
+    private timings;
+    private durationMs?;
+    /**
+     * Start a timer with a label
+     */
+    startTimer(label: string): void;
+    /**
+     * End a timer and calculate duration
+     * If label is 'execution', stores duration for metrics summary
+     */
+    endTimer(label: string): number | null;
+    /**
+     * Build execution metrics summary with optional ROI calculation
+     */
+    buildExecutionMetrics(metricsConfig?: ResourceMetricsConfig): ExecutionMetricsSummary;
+}
+
+interface BaseAICall {
+    callSequence: number;
+    callType: 'agent-reasoning' | 'agent-completion' | 'workflow-step' | 'tool' | 'other';
+    model: LLMModel;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    latencyMs: number;
+    context?: AICallContext;
+}
+type AICallContext = AgentReasoningContext | AgentCompletionContext | WorkflowStepContext | ToolCallContext | OtherCallContext;
+interface AgentReasoningContext {
+    type: 'agent-reasoning';
+    iteration: number;
+    actionsPlanned?: string[];
+    sessionId?: string;
+    turnNumber?: number;
+}
+interface AgentCompletionContext {
+    type: 'agent-completion';
+    attempt: 1 | 2;
+    validationFailed?: boolean;
+    sessionId?: string;
+    turnNumber?: number;
+}
+interface WorkflowStepContext {
+    type: 'workflow-step';
+    stepId: string;
+    stepName?: string;
+    stepSequence?: number;
+}
+interface ToolCallContext {
+    type: 'tool';
+    toolName: string;
+    parentIteration?: number;
+    parentStepId?: string;
+}
+interface OtherCallContext {
+    type: 'other';
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+type AICallRecord = BaseAICall;
+/**
+ * Raw LLM usage data returned by adapters
+ * Used as input to AIUsageCollector.record()
+ */
+interface LLMUsageData {
+    model: LLMModel;
+    inputTokens: number;
+    outputTokens: number;
+    latencyMs: number;
+    /** Actual cost from provider in USD (when available, e.g., OpenRouter) */
+    cost?: number;
+}
+interface AIUsageSummary {
+    model: LLMModel;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalTokens: number;
+    totalCostUsd: number;
+    callCount: number;
+    calls: AICallRecord[];
+}
+interface ExecutionMetricsSummary {
+    durationMs?: number;
+    automationSavingsUsd?: number;
+}
+interface ResourceMetricsConfig {
+    estimatedManualMinutes: number;
+    hourlyLaborRateUsd: number;
+    confidenceLevel?: 'low' | 'medium' | 'high';
+    notes?: string;
+}
+
+/**
+ * AIUsageCollector
+ * Centralized token tracking that aggregates usage across all LLM calls in an execution
+ */
+declare class AIUsageCollector {
+    private model;
+    private calls;
+    private callSequence;
+    /**
+     * Record a single AI call with usage metrics
+     *
+     * @param usage - Token usage and latency data from LLM adapter
+     * @param callType - Type discriminator (agent-reasoning, tool, etc.)
+     * @param context - Optional typed context specific to callType
+     */
+    record(usage: LLMUsageData, callType?: BaseAICall['callType'], context?: AICallContext): void;
+    /**
+     * Get aggregated summary of all AI calls
+     */
+    getSummary(): AIUsageSummary;
+    /**
+     * Check if any usage has been recorded
+     */
+    hasUsage(): boolean;
+}
+
+/**
+ * Base Execution Engine type definitions
+ * Core types shared across all Execution Engine resources
+ */
+
+/**
+ * Immutable execution metadata
+ * Represents complete execution identity (who, what, when, where)
+ * Shared across ExecutionContext and ExecutionLoggerContext to eliminate field duplication
+ */
+interface ExecutionMetadata {
+    executionId: string;
+    organizationId: string;
+    organizationName: string;
+    resourceId: string;
+    userId?: string;
+    sessionId?: string;
+    sessionTurnNumber?: number;
+}
+/**
+ * Unified message event type - covers all message types in sessions
+ * Replaces separate SessionTurnMessages and AgentActivityEvent mechanisms
+ */
+type MessageEvent = {
+    type: 'user_message';
+    text: string;
+} | {
+    type: 'assistant_message';
+    text: string;
+} | {
+    type: 'agent:started';
+} | {
+    type: 'agent:completed';
+} | {
+    type: 'agent:error';
+    error: string;
+} | {
+    type: 'agent:reasoning';
+    iteration: number;
+    reasoning: string;
+} | {
+    type: 'agent:tool_call';
+    toolName: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'agent:tool_result';
+    toolName: string;
+    success: boolean;
+    result?: unknown;
+    error?: string;
+};
+/**
+ * Execution context for all resources
+ * Unified callback replaces SessionTurnMessages (removed)
+ */
+interface ExecutionContext extends ExecutionMetadata {
+    logger: IExecutionLogger;
+    signal?: AbortSignal;
+    onMessageEvent?: (event: MessageEvent) => Promise<void>;
+    aiUsageCollector?: AIUsageCollector;
+    metricsCollector?: MetricsCollector;
+    parentExecutionId?: string;
+    executionDepth: number;
+    credentialName?: string;
+    store: Map<string, unknown>;
+}
+interface Contract {
+    inputSchema: z.ZodSchema;
+    outputSchema?: z.ZodSchema;
+}
+
+/**
+ * Tool definitions
+ *
+ * Tool interface used by agents and workflows.
+ * Provides a universal interface for AI systems to interact with tools.
+ */
+
+/**
+ * Options for tool execution
+ * Provides named parameters for better API clarity and extensibility
+ */
+interface ToolExecutionOptions {
+    /** Tool input (validated against inputSchema before execution) */
+    input: unknown;
+    /** Execution context with multi-tenant isolation and observability (optional for simple tools, required for platform/integration tools) */
+    executionContext?: ExecutionContext;
+    /** Full iteration context for advanced tools (provides access to memoryManager, toolRegistry, logger, etc.) */
+    iterationContext?: IterationContext;
+    /** Abort signal for timeout/cancellation -- forward to fetch() calls for clean cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Tool interface for AI systems
+ *
+ * Used by:
+ * - Agents: For agentic tool use (reasoning loop selects and executes tools)
+ * - Workflows: For workflow step tool invocation (future)
+ * - Platform tools: createApprovalTool(), createSchedulerTool()
+ * - Integration tools: External API calls (Gmail, Slack, etc.)
+ */
+interface Tool {
+    name: string;
+    description: string;
+    inputSchema: z.ZodSchema;
+    outputSchema: z.ZodSchema;
+    execute: (options: ToolExecutionOptions) => Promise<unknown>;
+    timeout?: number;
+}
+/**
+ * Tooling error types
+ * Used across platform tools and integration tools
+ */
+type ToolingErrorType = 'service_unavailable' | 'permission_denied' | 'adapter_not_found' | 'method_not_found' | 'tool_not_found' | 'credentials_missing' | 'credentials_invalid' | 'rate_limit_exceeded' | 'server_unavailable' | 'auth_error' | 'api_error' | 'validation_error' | 'network_error' | 'timeout_error' | 'unknown_error';
+/**
+ * Tooling error class
+ * Provides structured error information for tool failures across all tool types
+ *
+ * Severity mapping:
+ * - critical: credentials_missing, credentials_invalid, permission_denied, auth_error,
+ *            adapter_not_found, method_not_found, tool_not_found
+ * - info: validation_error
+ * - warning: All other types (retryable transient errors)
+ *
+ * Category: tool (tool execution errors)
+ */
+declare class ToolingError extends ExecutionError {
+    readonly errorType: ToolingErrorType;
+    readonly details?: unknown | undefined;
+    readonly type: "tooling_error";
+    readonly category: "tool";
+    constructor(errorType: ToolingErrorType, message: string, details?: unknown | undefined);
+    /**
+     * Derive severity based on error type
+     */
+    get severity(): 'critical' | 'warning' | 'info';
+    /**
+     * Check if error is retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Convert to JSON for logging
+     */
+    toJSON(): {
+        name: string;
+        type: ToolingErrorType;
+        message: string;
+        severity: "critical" | "warning" | "info";
+        category: "tool";
+        details: unknown;
+    };
+}
+
+/**
+ * Supported integration types
+ *
+ * These represent the available integration adapters that can be used with tools.
+ * Each integration type corresponds to an adapter implementation.
+ *
+ * Note: Concrete adapter implementations are deferred until needed.
+ * This type provides compile-time safety and auto-completion for tool definitions.
+ */
+type IntegrationType = 'gmail' | 'google-sheets' | 'slack' | 'github' | 'linear' | 'notion' | 'attio' | 'airtable' | 'trello' | 'salesforce' | 'hubspot' | 'stripe' | 'twilio' | 'sendgrid' | 'mailgun' | 'zapier' | 'webhook' | 'apify' | 'instantly' | 'resend' | 'signature-api' | 'dropbox' | 'mailso';
+
+/**
+ * Resource Registry type definitions
+ */
+
+/**
+ * Environment/deployment status for resources
+ */
+type ResourceStatus = 'dev' | 'prod';
+/**
+ * All resource types in the platform
+ * Used as the discriminator field in ResourceDefinition
+ */
+type ResourceType = 'agent' | 'workflow' | 'pipeline' | 'trigger' | 'integration' | 'external' | 'human';
+/**
+ * Base interface for ALL platform resources
+ * Shared by both executable (agents, workflows) and non-executable (triggers, integrations, etc.) resources
+ */
+interface ResourceDefinition {
+    /** Unique resource identifier */
+    resourceId: string;
+    /** Display name */
+    name: string;
+    /** Purpose and functionality description */
+    description: string;
+    /** Version for change tracking and evolution */
+    version: string;
+    /** Resource type discriminator */
+    type: ResourceType;
+    /** Environment/deployment status */
+    status: ResourceStatus;
+    /** Domain tags for filtering and organization */
+    domains?: ResourceDomain[];
+    /** Whether the agent supports multi-turn sessions (agents only) */
+    sessionCapable?: boolean;
+}
+/**
+ * Domain definition for Command View filtering
+ *
+ * Domains are organizational metadata for UI filtering/grouping.
+ * No execution impact - purely for visualization.
+ *
+ * @example
+ * {
+ *   id: 'support',
+ *   name: 'Customer Support',
+ *   description: 'Ticket triage, knowledge base, escalations',
+ *   color: 'green',
+ *   icon: 'IconHeadset'
+ * }
+ */
+interface DomainDefinition {
+    /** Unique identifier (e.g., 'support') */
+    id: string;
+    /** Display name (e.g., 'Customer Support') */
+    name: string;
+    /** Purpose description */
+    description: string;
+    /** Optional Mantine color for UI (e.g., 'blue', 'green', 'orange') */
+    color?: string;
+    /** Optional Tabler icon name (e.g., 'IconHeadset') */
+    icon?: string;
+}
+/** Webhook provider identifiers */
+type WebhookProviderType = 'cal-com' | 'fillout' | 'stripe' | 'signature-api' | 'instantly' | 'test';
+/** Webhook trigger configuration */
+interface WebhookTriggerConfig {
+    /** Provider identifier */
+    provider: WebhookProviderType;
+    /** Event type for documentation (not used for matching - workflow handles routing) */
+    event?: string;
+    /** Optional filtering (e.g., specific form ID for Fillout) */
+    filter?: Record<string, string>;
+    /** References credential in credentials table for per-org webhook secrets */
+    credentialName?: string;
+}
+/** Schedule trigger configuration */
+interface ScheduleTriggerConfig {
+    /** Cron expression (e.g., '0 6 * * *') */
+    cron: string;
+    /** Optional timezone (default: UTC) */
+    timezone?: string;
+}
+/** Event trigger configuration */
+interface EventTriggerConfig {
+    /** Internal event type */
+    eventType: string;
+    /** Event source */
+    source?: string;
+}
+/** Union of all trigger configs */
+type TriggerConfig = WebhookTriggerConfig | ScheduleTriggerConfig | EventTriggerConfig;
+/**
+ * Trigger metadata - entry points that initiate resource execution
+ *
+ * Triggers represent how executions start: webhooks from external services,
+ * scheduled cron jobs, platform events, or manual user actions.
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Field renames: `id` -> `resourceId` (inherited), `type` -> `triggerType`
+ * - Relationship rename: `invokes` -> `triggers` (unified vocabulary)
+ * - New required fields: `version` (inherited), `type: 'trigger'` (inherited)
+ * - triggers object now includes `externalResources` option
+ *
+ * @example
+ * // TriggerDefinition - metadata only
+ * {
+ *   resourceId: 'trigger-new-order',
+ *   type: 'trigger',
+ *   triggerType: 'webhook',
+ *   name: 'New Order',
+ *   description: 'Webhook from Shopify on new orders',
+ *   version: '1.0.0',
+ *   status: 'prod',
+ *   webhookPath: '/webhooks/shopify/orders'
+ * }
+ *
+ * // Relationships declared in ResourceRelationships (not on TriggerDefinition):
+ * // relationships: {
+ * //   'trigger-new-order': { triggers: { workflows: ['order-fulfillment-workflow'] } }
+ * // }
+ */
+interface TriggerDefinition extends ResourceDefinition {
+    /** Resource type discriminator (narrowed from base union) */
+    type: 'trigger';
+    /** Trigger mechanism type (renamed from 'type' to avoid collision with base type discriminator) */
+    triggerType: 'webhook' | 'schedule' | 'manual' | 'event';
+    /** Type-specific configuration */
+    config?: TriggerConfig;
+    /** For webhook triggers: path like '/webhooks/shopify/orders' */
+    webhookPath?: string;
+    /** For schedule triggers: cron expression like '0 6 * * *' */
+    schedule?: string;
+    /** For event triggers: event type like 'low-stock-alert' */
+    eventType?: string;
+}
+/**
+ * Integration metadata - external service connections
+ *
+ * References credentials table for actual connection. No connection status
+ * stored here (queried at runtime from credentials table).
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Field renames: `id` -> `resourceId` (inherited)
+ * - New required field: `status` (inherited) - organizations must add status to all integrations
+ * - New required field: `version` (inherited) - organizations must add version to all integrations
+ * - New required field: `type: 'integration'` (inherited) - resource type discriminator
+ *
+ * @example
+ * {
+ *   resourceId: 'integration-shopify-prod',
+ *   type: 'integration',
+ *   provider: 'shopify',
+ *   credentialName: 'shopify-prod',
+ *   name: 'Shopify Production',
+ *   description: 'E-commerce platform',
+ *   version: '1.0.0',
+ *   status: 'prod'
+ * }
+ */
+interface IntegrationDefinition extends ResourceDefinition {
+    /** Resource type discriminator (narrowed from base union) */
+    type: 'integration';
+    /** Integration provider type */
+    provider: IntegrationType;
+    /** References credentials table (e.g., 'shopify-prod', 'zendesk-api') */
+    credentialName: string;
+}
+/**
+ * Explicit resource relationship declaration
+ *
+ * Single-direction only - Command View derives reverse relationships.
+ * Agents/workflows declare what they trigger and use.
+ *
+ * @example
+ * {
+ *   triggers: { workflows: ['order-fulfillment-workflow'] },
+ *   uses: { integrations: ['integration-shopify-prod', 'integration-postgres'] }
+ * }
+ */
+interface RelationshipDeclaration {
+    /** Resources this resource triggers */
+    triggers?: {
+        /** Agent resourceIds this resource triggers */
+        agents?: string[];
+        /** Workflow resourceIds this resource triggers */
+        workflows?: string[];
+    };
+    /** Integrations this resource uses */
+    uses?: {
+        /** Integration IDs this resource uses */
+        integrations?: string[];
+    };
+}
+/**
+ * Resource relationships map
+ * Maps resourceId to its relationship declarations
+ *
+ * @example
+ * {
+ *   'order-processor-agent': {
+ *     triggers: { workflows: ['order-fulfillment-workflow'] },
+ *     uses: { integrations: ['integration-shopify-prod'] }
+ *   }
+ * }
+ */
+type ResourceRelationships = Record<string, RelationshipDeclaration>;
+/**
+ * External platform type
+ * Supported third-party automation platforms
+ */
+type ExternalPlatform = 'n8n' | 'make' | 'zapier' | 'other';
+/**
+ * External automation resource metadata
+ *
+ * Represents workflows/automations running on third-party platforms
+ * (n8n, Make, Zapier, etc.) for visualization in Command View.
+ *
+ * NOTE: This is metadata ONLY for visualization. No execution logic,
+ * no API integration with external platforms, no status syncing.
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Field renames: `id` -> `resourceId` (inherited)
+ * - New required field: `version` (inherited) - organizations must add version to all external resources
+ * - New required field: `type: 'external'` (inherited) - resource type discriminator
+ * - REMOVED FIELD: `triggeredBy` - per relationship-consolidation design, all relationships are forward-only declarations
+ *
+ * @example
+ * {
+ *   resourceId: 'external-n8n-order-sync',
+ *   type: 'external',
+ *   version: '1.0.0',
+ *   platform: 'n8n',
+ *   name: 'Shopify Order Sync',
+ *   description: 'Legacy n8n workflow for syncing Shopify orders',
+ *   status: 'prod',
+ *   platformUrl: 'https://n8n.client.com/workflow/123',
+ *   triggers: { workflows: ['order-fulfillment-workflow'] },
+ *   uses: { integrations: ['integration-shopify-prod'] }
+ * }
+ */
+interface ExternalResourceDefinition extends ResourceDefinition {
+    /** Resource type discriminator (narrowed from base union) */
+    type: 'external';
+    /** Platform type */
+    platform: ExternalPlatform;
+    /** Link to external platform (e.g., n8n workflow editor URL) */
+    platformUrl?: string;
+    /** Platform's internal ID/reference */
+    externalId?: string;
+    /** What this external resource triggers (external -> internal) */
+    triggers?: {
+        /** Elevasis workflow resourceIds this external automation triggers */
+        workflows?: string[];
+        /** Elevasis agent resourceIds this external automation triggers */
+        agents?: string[];
+    };
+    /** Integrations this external resource uses (shared credentials) */
+    uses?: {
+        /** Integration IDs this external automation uses */
+        integrations?: string[];
+    };
+}
+/**
+ * Human Checkpoint definition - human decision points in automation
+ *
+ * Represents where human judgment is deployed in the automation landscape.
+ * Tasks with matching command_queue_group are routed to this checkpoint.
+ *
+ * BREAKING CHANGES (2025-11-30):
+ * - Now extends ResourceDefinition (inherits: resourceId, name, description, version, type, status, domains)
+ * - Field renames: `id` -> `resourceId` (inherited)
+ * - description is now REQUIRED (was optional) - organizations must add description to all human checkpoints
+ * - New required field: `version` (inherited) - organizations must add version to all human checkpoints
+ * - New required field: `type: 'human'` (inherited) - resource type discriminator
+ *
+ * @example
+ * {
+ *   resourceId: 'sales-approval',
+ *   type: 'human',
+ *   name: 'Sales Approval Queue',
+ *   description: 'High-value order approvals for sales team',
+ *   version: '1.0.0',
+ *   status: 'prod',
+ *   requestedBy: { agents: ['order-processor-agent'] },
+ *   routesTo: { agents: ['order-fulfillment-agent'] }
+ * }
+ */
+interface HumanCheckpointDefinition extends ResourceDefinition {
+    /** Resource type discriminator (narrowed from base union) */
+    type: 'human';
+    /** Resources that create tasks for this checkpoint */
+    requestedBy?: {
+        /** Agent resourceIds that request approval here */
+        agents?: string[];
+        /** Workflow resourceIds that request approval here */
+        workflows?: string[];
+    };
+    /** Resources that receive approved decisions */
+    routesTo?: {
+        /** Agent resourceIds that handle approved tasks */
+        agents?: string[];
+        /** Workflow resourceIds that handle approved tasks */
+        workflows?: string[];
+    };
+}
+
+/**
+ * Standard Domain Definitions
+ * Centralized domain constants and definitions for all organization resources.
+ */
+
+declare const DOMAINS: {
+    readonly ACQUISITION: "acquisition";
+    readonly SUPPORT: "support";
+    readonly DELIVERY: "delivery";
+    readonly OPERATIONS: "operations";
+    readonly FINANCE: "finance";
+    readonly EXECUTIVE: "executive";
+    readonly TESTING: "testing";
+    readonly INTERNAL: "internal";
+    readonly INTEGRATION: "integration";
+    readonly UTILITY: "utility";
+    readonly DIAGNOSTIC: "diagnostic";
+};
+/**
+ * ResourceDomain - Strongly typed domain identifier
+ * Use this type for all domain references to ensure compile-time validation.
+ */
+type ResourceDomain = (typeof DOMAINS)[keyof typeof DOMAINS];
+
+/**
+ * Project configuration for an external developer project.
+ * Defined in elevas.config.ts at the project root.
+ */
+interface ElevasConfig {
+    organization: string;
+    defaultStatus?: ResourceStatus;
+    dev?: {
+        port?: number;
+    };
+}
+
+export { ExecutionError, StepType, ToolingError };
+export type { AgentConfig, AgentConstraints, AgentDefinition, ConditionalNext, Contract, DomainDefinition, ElevasConfig, EventTriggerConfig, ExecutionContext, ExecutionInterface, ExecutionMetadata, FormField, FormFieldType, FormSchema, IntegrationDefinition, LLMModel, LinearNext, ModelConfig, NextConfig, OrganizationResources, ResourceDefinition, ResourceDomain, ResourceMetricsConfig, ResourceStatus, ResourceType, ScheduleTriggerConfig, StepHandler, Tool, ToolExecutionOptions, ToolingErrorType, TriggerConfig, TriggerDefinition, WebhookProviderType, WebhookTriggerConfig, WorkflowConfig, WorkflowDefinition, WorkflowStep };