@holoscript/engine 6.0.3 → 6.0.4

package/dist/choreography/index.d.cts

@@ -0,0 +1,687 @@
+import { AgentManifest, CapabilityQuery, AgentRegistry } from '@holoscript/framework/agents';
+import { EventEmitter } from 'events';
+
+/**
+ * @holoscript/core - Choreography Type Definitions
+ *
+ * Types for multi-agent choreography and orchestration.
+ * Part of HoloScript v3.1 Agentic Choreography.
+ */
+
+/**
+ * Status of a choreography step
+ */
+type StepStatus = 'pending' | 'waiting' | 'ready' | 'running' | 'paused' | 'completed' | 'failed' | 'skipped' | 'cancelled';
+/**
+ * Status of a choreography plan
+ */
+type ChoreographyStatus = 'draft' | 'ready' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Step retry strategy
+ */
+type RetryStrategy = 'none' | 'immediate' | 'exponential' | 'fixed';
+/**
+ * Execution constraint types
+ */
+type ConstraintType = 'timeout' | 'order' | 'concurrency' | 'resource' | 'spatial' | 'trust' | 'custom';
+/**
+ * Retry configuration for a step
+ */
+interface RetryConfig {
+    /** Retry strategy */
+    strategy: RetryStrategy;
+    /** Maximum number of retries */
+    maxRetries: number;
+    /** Delay between retries (ms) */
+    delay: number;
+    /** Backoff multiplier for exponential strategy */
+    backoffMultiplier?: number;
+    /** Maximum delay cap */
+    maxDelay?: number;
+    /** Retry condition (if false, don't retry) */
+    condition?: (error: Error, attempt: number) => boolean;
+}
+/**
+ * Default retry configuration
+ */
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Step input/output definition
+ */
+interface StepIO {
+    /** Key name */
+    key: string;
+    /** Value type */
+    type?: string;
+    /** Actual value */
+    value?: unknown;
+    /** Whether required */
+    required?: boolean;
+    /** Default value */
+    default?: unknown;
+    /** Source reference (e.g., 'step#generate.outputs.scene') */
+    source?: string;
+}
+/**
+ * Single step in a choreography
+ */
+interface ChoreographyStep {
+    /** Unique step ID */
+    id: string;
+    /** Human-readable name */
+    name?: string;
+    /** Description of what this step does */
+    description?: string;
+    /** Agent ID to execute this step */
+    agentId: string;
+    /** Action to invoke on the agent */
+    action: string;
+    /** Input parameters */
+    inputs: Record<string, unknown>;
+    /** Output definitions */
+    outputs: Record<string, StepIO>;
+    /** Step IDs this step depends on */
+    dependencies: string[];
+    /** Current status */
+    status: StepStatus;
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: Partial<RetryConfig>;
+    /** Condition for execution (if false, skip) */
+    condition?: string | ((context: StepContext) => boolean);
+    /** Whether this is a HITL gate step */
+    hitlGate?: boolean;
+    /** Started timestamp */
+    startedAt?: number;
+    /** Completed timestamp */
+    completedAt?: number;
+    /** Execution duration (ms) */
+    duration?: number;
+    /** Error if failed */
+    error?: string;
+    /** Current retry attempt */
+    retryAttempt?: number;
+    /** ID of step to execute if this step fails */
+    fallbackStepId?: string;
+    /** Parallel execution group */
+    parallelGroup?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Context available during step execution
+ */
+interface StepContext {
+    /** The choreography plan */
+    plan: ChoreographyPlan;
+    /** Current step */
+    currentStep: ChoreographyStep;
+    /** Available agents */
+    agents: Map<string, AgentManifest>;
+    /** Outputs from completed steps */
+    stepOutputs: Map<string, Record<string, unknown>>;
+    /** Global variables */
+    variables: Record<string, unknown>;
+    /** Start time */
+    startTime: number;
+    /** Elapsed time (ms) */
+    elapsedTime: number;
+}
+/**
+ * Execution constraint
+ */
+interface ExecutionConstraint {
+    /** Constraint type */
+    type: ConstraintType;
+    /** Constraint value */
+    value: unknown;
+    /** Human-readable description */
+    description?: string;
+    /** Whether this is a hard constraint (failure on violation) */
+    hard?: boolean;
+}
+/**
+ * Common constraint factories
+ */
+declare const Constraints: {
+    timeout(ms: number, hard?: boolean): ExecutionConstraint;
+    concurrency(max: number): ExecutionConstraint;
+    trust(minLevel: string): ExecutionConstraint;
+};
+/**
+ * Complete choreography plan
+ */
+interface ChoreographyPlan {
+    /** Unique plan ID */
+    id: string;
+    /** Human-readable name */
+    name?: string;
+    /** Goal description */
+    goal: string;
+    /** Choreography steps */
+    steps: ChoreographyStep[];
+    /** Participating agents */
+    participants: AgentManifest[];
+    /** Execution constraints */
+    constraints: ExecutionConstraint[];
+    /** Fallback plan on failure */
+    fallback?: ChoreographyPlan;
+    /** Current status */
+    status: ChoreographyStatus;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Started timestamp */
+    startedAt?: number;
+    /** Completed timestamp */
+    completedAt?: number;
+    /** Total duration (ms) */
+    duration?: number;
+    /** Initiating agent or user */
+    initiator?: string;
+    /** Priority (higher = more important) */
+    priority?: number;
+    /** Tags for categorization */
+    tags?: string[];
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of step execution
+ */
+interface StepResult {
+    /** Step ID */
+    stepId: string;
+    /** Success status */
+    success: boolean;
+    /** Outputs produced */
+    outputs: Record<string, unknown>;
+    /** Duration (ms) */
+    duration: number;
+    /** Error message if failed */
+    error?: string;
+    /** Number of retries attempted */
+    retries?: number;
+    /** Whether a fallback step was used */
+    usedFallback?: boolean;
+    /** Metrics */
+    metrics?: {
+        tokenUsage?: number;
+        computeTime?: number;
+        networkLatency?: number;
+    };
+}
+/**
+ * Result of complete choreography execution
+ */
+interface ChoreographyResult {
+    /** Plan ID */
+    planId: string;
+    /** Overall success */
+    success: boolean;
+    /** Final status */
+    status: ChoreographyStatus;
+    /** Individual step results */
+    stepResults: StepResult[];
+    /** Total duration (ms) */
+    duration: number;
+    /** Steps completed count */
+    stepsCompleted: number;
+    /** Steps failed count */
+    stepsFailed: number;
+    /** Steps skipped count */
+    stepsSkipped: number;
+    /** Array of completed steps */
+    completedSteps?: ChoreographyStep[];
+    /** Array of failed steps */
+    failedSteps?: ChoreographyStep[];
+    /** Error message if failed */
+    error?: string;
+    /** Final outputs (from terminal steps) */
+    finalOutputs: Record<string, unknown>;
+    /** Whether fallback was used */
+    usedFallback?: boolean;
+    /** Aggregate metrics */
+    metrics?: {
+        totalTokens?: number;
+        totalComputeTime?: number;
+        peakConcurrency?: number;
+    };
+}
+/**
+ * Events emitted by ChoreographyEngine
+ */
+interface ChoreographyEvents {
+    'plan:created': (plan: ChoreographyPlan) => void;
+    'plan:started': (plan: ChoreographyPlan) => void;
+    'plan:completed': (result: ChoreographyResult) => void;
+    'plan:failed': (plan: ChoreographyPlan, error: Error) => void;
+    'plan:paused': (plan: ChoreographyPlan) => void;
+    'plan:resumed': (plan: ChoreographyPlan) => void;
+    'plan:cancelled': (plan: ChoreographyPlan) => void;
+    'step:started': (step: ChoreographyStep, plan: ChoreographyPlan) => void;
+    'step:completed': (result: StepResult, plan: ChoreographyPlan) => void;
+    'step:failed': (step: ChoreographyStep, error: Error, plan: ChoreographyPlan) => void;
+    'step:retrying': (step: ChoreographyStep, attempt: number, plan: ChoreographyPlan) => void;
+    'step:skipped': (step: ChoreographyStep, reason: string, plan: ChoreographyPlan) => void;
+    'hitl:required': (step: ChoreographyStep, plan: ChoreographyPlan) => void;
+    'hitl:approved': (step: ChoreographyStep, plan: ChoreographyPlan) => void;
+    'hitl:rejected': (step: ChoreographyStep, reason: string, plan: ChoreographyPlan) => void;
+}
+
+/**
+ * @holoscript/core - Step Executor
+ *
+ * Executes individual choreography steps with retry logic.
+ * Part of HoloScript v3.1 Agentic Choreography.
+ */
+
+/**
+ * Agent action handler signature
+ */
+type ActionHandler = (agent: AgentManifest, action: string, inputs: Record<string, unknown>, context: StepContext) => Promise<Record<string, unknown>>;
+/**
+ * Step executor configuration
+ */
+interface StepExecutorConfig {
+    /** Default timeout (ms) */
+    defaultTimeout: number;
+    /** Default retry configuration */
+    defaultRetry: RetryConfig;
+    /** Whether to emit verbose events */
+    verbose: boolean;
+}
+/**
+ * Default executor configuration
+ */
+declare const DEFAULT_EXECUTOR_CONFIG: StepExecutorConfig;
+/**
+ * Step executor events
+ */
+interface StepExecutorEvents {
+    'step:starting': (step: ChoreographyStep) => void;
+    'step:inputs:resolved': (step: ChoreographyStep, inputs: Record<string, unknown>) => void;
+    'step:executing': (step: ChoreographyStep, agent: AgentManifest) => void;
+    'step:completed': (step: ChoreographyStep, result: StepResult) => void;
+    'step:failed': (step: ChoreographyStep, error: Error) => void;
+    'step:retrying': (step: ChoreographyStep, attempt: number, delay: number) => void;
+    'step:timeout': (step: ChoreographyStep, timeout: number) => void;
+    'step:skipped': (step: ChoreographyStep, reason: string) => void;
+}
+/**
+ * Executes individual choreography steps
+ */
+declare class StepExecutor extends EventEmitter {
+    private config;
+    private actionHandler;
+    private runningSteps;
+    constructor(config?: Partial<StepExecutorConfig>);
+    /**
+     * Register the action handler for executing agent actions
+     */
+    setActionHandler(handler: ActionHandler): void;
+    /**
+     * Execute a single step
+     */
+    execute(step: ChoreographyStep, context: StepContext): Promise<StepResult>;
+    /**
+     * Cancel a running step
+     */
+    cancel(stepId: string): boolean;
+    /**
+     * Check if any steps are running
+     */
+    isRunning(stepId?: string): boolean;
+    /**
+     * Check if step should be skipped
+     */
+    private shouldSkip;
+    /**
+     * Evaluate a string condition
+     */
+    private evaluateCondition;
+    /**
+     * Parse a string value
+     */
+    private parseValue;
+    /**
+     * Resolve input references
+     */
+    private resolveInputs;
+    /**
+     * Execute with timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Calculate retry delay
+     */
+    private calculateDelay;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+}
+/**
+ * Get default executor
+ */
+declare function getDefaultExecutor(): StepExecutor;
+/**
+ * Reset default executor (for testing)
+ */
+declare function resetDefaultExecutor(): void;
+
+/**
+ * @holoscript/core - Choreography Planner
+ *
+ * Creates and validates choreography execution plans.
+ * Part of HoloScript v3.1 Agentic Choreography.
+ */
+
+/**
+ * Step definition for plan builder
+ */
+interface StepDefinition {
+    /** Step ID (auto-generated if not provided) */
+    id?: string;
+    /** Step name */
+    name?: string;
+    /** Description */
+    description?: string;
+    /** Agent ID or capability query */
+    agent: string | CapabilityQuery;
+    /** Action to execute */
+    action: string;
+    /** Input parameters */
+    inputs?: Record<string, unknown>;
+    /** Output definitions */
+    outputs?: Record<string, StepIO | string>;
+    /** Dependencies (step IDs) */
+    dependencies?: string[];
+    /** Alias for dependencies (step names or IDs) */
+    dependsOn?: string[];
+    /** Parallel execution group */
+    parallelGroup?: string;
+    /** Timeout (ms) */
+    timeout?: number;
+    /** Max retries */
+    retries?: number;
+    /** Condition expression */
+    condition?: string;
+    /** Whether this is a HITL gate */
+    hitlGate?: boolean;
+    /** ID of step to execute if this step fails */
+    fallbackStepId?: string;
+}
+/**
+ * Plan definition for planner
+ */
+interface PlanDefinition {
+    /** Plan name */
+    name?: string;
+    /** Goal description */
+    goal: string;
+    /** Available agents */
+    agents: AgentManifest[];
+    /** Step definitions */
+    steps: StepDefinition[];
+    /** Constraints */
+    constraints?: ExecutionConstraint[];
+    /** Fallback plan */
+    fallback?: PlanDefinition;
+    /** Priority */
+    priority?: number;
+    /** Tags */
+    tags?: string[];
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Validation result
+ */
+interface PlanValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Execution order result
+ */
+interface ExecutionOrder {
+    /** Groups of steps that can run in parallel */
+    parallelGroups: string[][];
+    /** Flat ordered list (topological sort) */
+    flatOrder: string[];
+    /** Dependency graph */
+    graph: Map<string, string[]>;
+}
+/**
+ * Creates and validates choreography plans
+ */
+declare class ChoreographyPlanner {
+    private matcher;
+    /**
+     * Create a choreography plan from definition
+     */
+    createPlan(definition: PlanDefinition): ChoreographyPlan;
+    /**
+     * Validate a choreography plan
+     */
+    validate(plan: ChoreographyPlan): PlanValidationResult;
+    /**
+     * Calculate execution order
+     */
+    calculateExecutionOrder(plan: ChoreographyPlan): ExecutionOrder;
+    /**
+     * Clone and reset a plan for re-execution
+     */
+    resetPlan(plan: ChoreographyPlan): ChoreographyPlan;
+    /**
+     * Resolve agent from ID or capability query
+     */
+    private resolveAgent;
+    /**
+     * Detect circular dependencies
+     */
+    private detectCycles;
+}
+/**
+ * Fluent builder for choreography plans
+ */
+declare class PlanBuilder {
+    private definition;
+    private planner;
+    constructor(goal: string);
+    /**
+     * Set plan name
+     */
+    name(name: string): this;
+    /**
+     * Add an agent to the plan
+     */
+    agent(manifest: AgentManifest): this;
+    /**
+     * Add multiple agents
+     */
+    agents(manifests: AgentManifest[]): this;
+    /**
+     * Add a step to the plan
+     */
+    step(definition: StepDefinition): this;
+    /**
+     * Add a constraint
+     */
+    constraint(constraint: ExecutionConstraint): this;
+    /**
+     * Set timeout constraint
+     */
+    timeout(ms: number): this;
+    /**
+     * Set concurrency constraint
+     */
+    concurrency(max: number): this;
+    /**
+     * Set fallback plan
+     */
+    fallback(fallbackPlan: PlanDefinition): this;
+    /**
+     * Set priority
+     */
+    priority(priority: number): this;
+    /**
+     * Add tags
+     */
+    tags(...tags: string[]): this;
+    /**
+     * Set metadata
+     */
+    metadata(meta: Record<string, unknown>): this;
+    /**
+     * Build and validate the plan
+     */
+    build(): ChoreographyPlan;
+    /**
+     * Build without validation (for testing)
+     */
+    buildUnsafe(): ChoreographyPlan;
+}
+/**
+ * Create a new plan builder
+ */
+declare function plan(goal: string): PlanBuilder;
+/**
+ * Get default planner
+ */
+declare function getDefaultPlanner(): ChoreographyPlanner;
+
+/**
+ * @holoscript/core - Choreography Engine
+ *
+ * Orchestrates multi-agent choreography execution.
+ * Part of HoloScript v3.1 Agentic Choreography.
+ */
+
+/**
+ * Engine configuration
+ */
+interface ChoreographyEngineConfig {
+    /** Maximum concurrent step execution */
+    maxConcurrency: number;
+    /** Default step timeout (ms) */
+    defaultTimeout: number;
+    /** Whether to execute fallback on failure */
+    executeFallback: boolean;
+    /** Whether to pause on HITL gates automatically */
+    autoHitlPause: boolean;
+    /** Verbose logging */
+    verbose: boolean;
+}
+/**
+ * Default engine configuration
+ */
+declare const DEFAULT_ENGINE_CONFIG: ChoreographyEngineConfig;
+/**
+ * Main engine for executing choreography plans
+ */
+declare class ChoreographyEngine extends EventEmitter {
+    private config;
+    private planner;
+    private executor;
+    private registry;
+    private activePlans;
+    private actionHandler;
+    constructor(config?: Partial<ChoreographyEngineConfig>);
+    /**
+     * Set the agent registry
+     */
+    setRegistry(registry: AgentRegistry): void;
+    /**
+     * Set the action handler for executing agent actions
+     */
+    setActionHandler(handler: ActionHandler): void;
+    /**
+     * Create a new choreography plan
+     */
+    createPlan(goal: string, agents: AgentManifest[], steps: ChoreographyStep[]): ChoreographyPlan;
+    /**
+     * Execute a choreography plan
+     */
+    execute(plan: ChoreographyPlan, variables?: Record<string, unknown>): Promise<ChoreographyResult>;
+    /**
+     * Pause a running plan
+     */
+    pause(planId: string): Promise<void>;
+    /**
+     * Resume a paused plan
+     */
+    resume(planId: string): Promise<void>;
+    /**
+     * Cancel a running plan
+     */
+    cancel(planId: string): Promise<void>;
+    /**
+     * Approve a HITL gate
+     */
+    approveHitl(planId: string, stepId: string): void;
+    /**
+     * Reject a HITL gate
+     */
+    rejectHitl(planId: string, stepId: string, reason: string): void;
+    /**
+     * Get active plan IDs
+     */
+    getActivePlans(): string[];
+    /**
+     * Get plan status
+     */
+    getPlanStatus(planId: string): ChoreographyStatus | null;
+    /**
+     * Execute the plan
+     */
+    private executePlan;
+    /**
+     * Execute a group of steps (potentially in parallel)
+     */
+    private executeGroup;
+    /**
+     * Execute a single step
+     */
+    private executeStep;
+    /**
+     * Build step context
+     */
+    private buildStepContext;
+    /**
+     * Build final result
+     */
+    private buildResult;
+    /**
+     * Get concurrency limit from constraints
+     */
+    private getConcurrencyLimit;
+    /**
+     * Find plan containing a step
+     */
+    private findPlanWithStep;
+    /**
+     * Generate unique ID
+     */
+    private generateId;
+    /**
+     * Chunk array into batches
+     */
+    private chunk;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+}
+/**
+ * Get default choreography engine
+ */
+declare function getDefaultEngine(): ChoreographyEngine;
+/**
+ * Reset default engine (for testing)
+ */
+declare function resetDefaultEngine(): void;
+
+export { type ActionHandler, ChoreographyEngine, type ChoreographyEngineConfig, type ChoreographyEvents, type ChoreographyPlan, ChoreographyPlanner, type ChoreographyResult, type ChoreographyStatus, type ChoreographyStep, type ConstraintType, Constraints, DEFAULT_ENGINE_CONFIG, DEFAULT_EXECUTOR_CONFIG, DEFAULT_RETRY_CONFIG, type ExecutionConstraint, type ExecutionOrder, PlanBuilder, type PlanDefinition, type PlanValidationResult, type RetryConfig, type RetryStrategy, type StepContext, type StepDefinition, StepExecutor, type StepExecutorConfig, type StepExecutorEvents, type StepIO, type StepResult, type StepStatus, getDefaultEngine, getDefaultExecutor, getDefaultPlanner, plan, resetDefaultEngine, resetDefaultExecutor };