@almadar/agent 1.3.1 → 1.3.3

package/dist/index.d.ts

@@ -7,10 +7,10 @@ import { DomainContext, OrbitalSchema, Orbital } from '@almadar/core/types';
 export { DomainDocument, DomainToSchemaResult, ParseError, SchemaToDomainResult, SectionMapping, applySectionUpdate, convertDomainToSchema, convertSchemaToDomain, deleteSection } from '@almadar/core/domain-language';
 import { LLMClient } from '@almadar/llm';
 export { createCompactSystemPrompt, createSystemPrompt } from './prompts/index.js';
-import { U as UserPreference, M as MemoryManager, G as GenerationSession } from './index-BN4d3ObG.js';
-export { C as CheckpointRecord, a as ContextCompactionConfig, D as DEFAULT_COMPACTION_CONFIG, E as EVENT_BUDGETS, I as InterruptRecord, b as MemoryManagerOptions, c as MemoryOrbitalSchema, P as PatternAffinity, d as ProjectContext, S as SessionManager, e as SessionManagerOptions, f as Skill, g as SkillAgentOptions, h as SkillAgentResult, i as SkillLoader, j as SkillMeta, k as SkillRefLoader, T as ToolApprovalPreference, l as UserFeedback, m as createSkillAgent, n as createSummaryPrompt, o as estimateTokens, p as getBudgetWarningMessage, q as getEventBudget, r as getInterruptConfig, s as needsCompaction, t as resumeSkillAgent } from './index-BN4d3ObG.js';
-import { S as SessionMetadata } from './firestore-checkpointer-CkNKXoun.js';
-export { F as FirestoreCheckpointer, a as FirestoreCheckpointerOptions, b as FirestoreDb, c as FirestoreTimestamp, P as PersistenceMode, d as Session, e as SessionRecord } from './firestore-checkpointer-CkNKXoun.js';
+import { U as UserPreference, M as MemoryManager, G as GenerationSession } from './interrupt-config-Bib_RCTB.js';
+export { C as CheckpointRecord, l as ContextCompactionConfig, D as DEFAULT_COMPACTION_CONFIG, E as EVENT_BUDGETS, I as InterruptRecord, m as MemoryManagerOptions, n as MemoryOrbitalSchema, P as PatternAffinity, o as ProjectContext, S as SessionManager, a as SessionManagerOptions, b as Skill, c as SkillAgentOptions, d as SkillAgentResult, e as SkillLoader, f as SkillMeta, g as SkillRefLoader, T as ToolApprovalPreference, p as UserFeedback, h as createSkillAgent, q as createSummaryPrompt, s as estimateTokens, i as getBudgetWarningMessage, j as getEventBudget, k as getInterruptConfig, t as needsCompaction, r as resumeSkillAgent } from './interrupt-config-Bib_RCTB.js';
+import { S as SessionMetadata } from './firestore-checkpointer-BkFR-sZM.js';
+export { b as FirestoreCheckpointer, c as FirestoreCheckpointerOptions, F as FirestoreDb, d as FirestoreTimestamp, P as PersistenceMode, e as Session, a as SessionRecord } from './firestore-checkpointer-BkFR-sZM.js';
 export { FirestoreSessionStore, FirestoreSessionStoreOptions, FirestoreStore, FirestoreStoreOptions, MemorySessionBackend } from './persistence/index.js';
 export { RawAgentEvent, extractFileOperation, extractInterruptData, hasInterrupt, isFileOperation, isTodoUpdate, transformAgentEvent, transformAgentEventMulti } from './event-transformer/index.js';
 import { EventEmitter } from 'events';
@@ -1092,4 +1092,766 @@ declare function withSync<T extends (...args: unknown[]) => unknown>(fn: T, sync
  */
 declare function debounceSync(syncManager: StateSyncManager, delay?: number): (type: StateChangeType, threadId: string, payload: Record<string, unknown>) => void;
 
-export { type AccessCheckResult, AgenticSearchEngine, type AgenticSearchParams, type AgenticSearchResponse, type ConflictResolution, type DeepAgentCompleteEvent, type DeepAgentErrorEvent, type DeepAgentEvent, type DeepAgentExecutionEvent, type DeepAgentSchemaEvent, type DeepAgentStartEvent, type GenerationMetrics, GenerationSession, type HealthCheckResult, type InferredPreference, MemoryManager, MetricsCollector, type MetricsSummary, MultiUserManager, ObservabilityCollector, type ObservableEvent, type ObservableEventType, type CombinerOptions as OrbitalCombinerOptions, type CombinerResult as OrbitalCombinerResult, type OrbitalSchemaValidationResult, type PerformanceSnapshot, type PreferenceAnalysis, PreferenceLearner, type PreferenceLearnerOptions, type ScopedSessionMetadata, type SearchResult, type SearchStrategy, SessionMetadata, type SessionTelemetry, type StateChangeEvent, type StateChangeType, type StateSyncConfig, StateSyncManager, type StateSyncSnapshot, SubAgent, type UserContext, UserPreference, type UserSessionStats, type VersionVector, analyzeFailures, combineOrbitals, combineOrbitalsToSchema, createAgenticSearchEngine, createErrorFixerSubagent, createPreferenceLearner, createSchemaGeneratorSubagent, createSubagentConfigs, createSubagents, createTestAnalyzerSubagent, createUserContext, debounceSync, endObservabilitySession, estimateCacheSavings, estimateCombineComplexity, formatSummary, generateFullOrbital, getMultiUserManager, getObservabilityCollector, getPerformanceSnapshot, getStateSyncManager, isAdmin, isCompleteEvent, isErrorEvent, isExecutionEvent, isSchemaEvent, isStartEvent, parseDeepAgentEvent, recordEvent, requireOwnership, resetMultiUserManager, resetObservabilityCollector, resetStateSyncManager, startObservabilitySession, withSync };
+/**
+ * Model Router Types
+ *
+ * @packageDocumentation
+ */
+type LLMProvider = 'anthropic' | 'openrouter' | 'openai' | 'deepseek' | 'kimi';
+interface RoutingDecision {
+    /** Selected model identifier */
+    model: string;
+    /** Provider to use */
+    provider: LLMProvider;
+    /** Human-readable reasoning */
+    reasoning: string;
+    /** Estimated cost in USD */
+    estimatedCost: number;
+    /** Estimated latency in milliseconds */
+    estimatedLatency: number;
+    /** Fallback model if primary fails */
+    fallback?: {
+        model: string;
+        provider: LLMProvider;
+    };
+}
+interface ProviderConfig {
+    /** Provider identifier */
+    name: LLMProvider;
+    /** Model identifier */
+    model: string;
+    /** Cost per 1K input tokens */
+    costPer1KInput: number;
+    /** Cost per 1K output tokens */
+    costPer1KOutput: number;
+    /** Typical latency for simple request (ms) */
+    baseLatency: number;
+    /** Maximum orbitals this provider can handle reliably */
+    maxOrbitals: number;
+    /** Whether this provider supports fallback */
+    supportsFallback: boolean;
+}
+type RoutingStrategy = 'cost-optimized' | 'latency-optimized' | 'quality-optimized';
+interface ModelRouterConfig {
+    /** Primary provider configurations */
+    providers: ProviderConfig[];
+    /** Default routing strategy */
+    defaultStrategy: RoutingStrategy;
+    /** Enable automatic fallback on failure */
+    enableFallback: boolean;
+    /** Timeout threshold for fallback (ms) */
+    fallbackTimeout: number;
+    /** Enable A/B testing for routing decisions */
+    enableABTesting: boolean;
+}
+interface OrbitalEstimation {
+    /** Estimated number of orbitals */
+    count: number;
+    /** Confidence in estimation (0-1) */
+    confidence: number;
+    /** Detected domains/domains */
+    domains: string[];
+    /** Reasoning for estimation */
+    reasoning: string;
+    /** Optional metadata for debugging */
+    _metadata?: {
+        method?: 'llm' | 'heuristic';
+        entities?: string[];
+        complexityFactors?: string[];
+        latencyMs?: number;
+        tokensUsed?: number;
+        model?: string;
+        originalEstimate?: number;
+        validationMethod?: string;
+    };
+}
+/**
+ * Safety configuration for conservative routing
+ */
+interface SafetyConfig {
+    /** Always round up estimates by this amount */
+    conservativeBias: number;
+    /** Route to Anthropic if confidence below this */
+    minConfidenceThreshold: number;
+    /** Validate estimations above this threshold */
+    validationThreshold: number;
+    /** Maximum orbitals allowed for Qwen */
+    qwenMaxOrbitals: number;
+    /** Keywords that force Anthropic routing */
+    forceComplexKeywords: string[];
+}
+
+/**
+ * Model Router with Safety Layer
+ *
+ * Routes generation requests to optimal LLM provider based on orbital count.
+ * Implements Phase 1.1 of the enhancement plan.
+ *
+ * SAFETY FEATURES:
+ * - Conservative bias: Always rounds up estimates
+ * - Complex indicators: Definite keywords force Anthropic
+ * - Confidence threshold: Low confidence → Anthropic
+ * - Circuit breaker: Auto-fallback on repeated failures
+ *
+ * Test Results:
+ * - 1 orbital: Qwen 100% quality, 68s (75% cheaper)
+ * - 3-4 orbitals: Qwen 56/100, 169s (24% faster, same quality)
+ * - 6+ orbitals: Qwen times out, Anthropic required
+ *
+ * @packageDocumentation
+ */
+
+declare class ModelRouter {
+    private config;
+    private circuitBreaker;
+    constructor(config?: Partial<ModelRouterConfig>);
+    /**
+     * Route request with FULL safety checks
+     * This is the primary production routing method
+     */
+    routeSafely(request: string, expectedOrbitals?: number, safetyConfig?: Partial<SafetyConfig>): Promise<RoutingDecision>;
+    /**
+     * Legacy method - kept for compatibility, but uses safety layer internally
+     * @deprecated Use routeSafely() for production
+     */
+    routeByOrbitalCount(request: string, expectedOrbitals?: number): Promise<RoutingDecision>;
+    /**
+     * Route with pre-decomposition estimation
+     */
+    routeWithDecomposition(request: string): Promise<RoutingDecision>;
+    /**
+     * Generate with automatic fallback AND circuit breaker tracking
+     */
+    generateWithFallback<T>(request: string, generateFn: (provider: LLMProvider, model: string) => Promise<T>, expectedOrbitals?: number): Promise<{
+        result: T;
+        routing: RoutingDecision;
+        usedFallback: boolean;
+    }>;
+    /**
+     * Get cost comparison for debugging/optimization
+     */
+    getCostComparison(request: string, expectedOrbitals?: number): Promise<{
+        orbitalCount: number;
+        recommended: RoutingDecision;
+        alternatives: RoutingDecision[];
+        savings: number;
+        safetyChecks: string[];
+    }>;
+    /**
+     * Get circuit breaker status for monitoring
+     */
+    getCircuitBreakerStatus(): {
+        failures: number;
+        successes: number;
+        isOpen: boolean;
+        failureRate: number;
+    };
+    private estimateWithSafety;
+    private createQwenDecision;
+    private createAnthropicDecision;
+    private executeWithTimeout;
+}
+/**
+ * Factory function for creating router
+ */
+declare function createModelRouter(config?: Partial<ModelRouterConfig>): ModelRouter;
+declare function getModelRouter(): ModelRouter;
+
+/**
+ * Orbital Count Estimator - LLM-Based
+ *
+ * Uses a fast, cheap LLM (GPT-4o-mini or GPT-5-mini) to estimate orbital complexity
+ * from natural language requests. Much more accurate and scalable than keyword matching.
+ *
+ * Cost: ~$0.0001 per estimate (~500 tokens total)
+ * Latency: ~100-200ms
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Estimate orbital count using LLM (recommended for production)
+ */
+declare function estimateOrbitalCountLLM(request: string, options?: {
+    model?: string;
+    timeoutMs?: number;
+}): Promise<OrbitalEstimation>;
+/**
+ * Heuristic estimation (no LLM required) - used as fallback
+ * Less accurate but works offline and without API keys
+ */
+declare function estimateOrbitalCountHeuristic(request: string): OrbitalEstimation;
+/**
+ * Primary estimation function - uses LLM by default, falls back to heuristic
+ *
+ * NOTE: LLM estimation is strongly recommended for production use.
+ * Heuristic estimation significantly underestimates complex apps (see eval results).
+ */
+declare function estimateOrbitalCount(request: string, options?: {
+    useLLM?: boolean;
+    model?: string;
+    timeoutMs?: number;
+}): Promise<OrbitalEstimation>;
+/**
+ * Quick synchronous estimate (always uses heuristic)
+ */
+declare function quickEstimate(request: string): number;
+/**
+ * Batch estimation for multiple requests (uses LLM with batching)
+ */
+declare function estimateOrbitalCountBatch(requests: string[], options?: {
+    model?: string;
+}): Promise<OrbitalEstimation[]>;
+
+/**
+ * Model Router Safety Layer
+ *
+ * Prevents catastrophic underestimation that leads to Qwen timeouts.
+ * Uses multiple safety mechanisms:
+ * 1. Conservative bias (round up, not down)
+ * 2. Complexity indicators (definite "complex" signals)
+ * 3. Confidence threshold (low confidence → Anthropic)
+ * 4. Validation layer (second opinion for borderline cases)
+ * 5. Circuit breaker (auto-fallback on any failure)
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Check if request contains definite complex indicators
+ */
+declare function hasDefiniteComplexIndicators(request: string): boolean;
+/**
+ * Apply conservative bias to estimation
+ */
+declare function applyConservativeBias(estimation: OrbitalEstimation, bias?: number): OrbitalEstimation;
+/**
+ * Make final routing decision with all safety checks
+ */
+declare function makeSafeRoutingDecision(estimation: OrbitalEstimation, request: string, config?: Partial<SafetyConfig>): {
+    finalCount: number;
+    useAnthropic: boolean;
+    reason: string;
+    safetyChecks: string[];
+};
+/**
+ * Complete safe estimation pipeline
+ */
+declare function safeEstimate(request: string, options: {
+    estimateFn: (request: string) => Promise<OrbitalEstimation>;
+    validateFn?: (est: OrbitalEstimation) => Promise<OrbitalEstimation>;
+    config?: Partial<SafetyConfig>;
+}): Promise<{
+    estimation: OrbitalEstimation;
+    routing: {
+        useAnthropic: boolean;
+        reason: string;
+        safetyChecks: string[];
+    };
+}>;
+/**
+ * Circuit breaker for Qwen calls
+ * Monitors failure rate and forces Anthropic if too many failures
+ */
+declare class QwenCircuitBreaker {
+    private failureThreshold;
+    private resetTimeoutMs;
+    private failures;
+    private successes;
+    private lastFailure;
+    constructor(failureThreshold?: number, resetTimeoutMs?: number);
+    recordSuccess(): void;
+    recordFailure(): void;
+    isOpen(): boolean;
+    getStatus(): {
+        failures: number;
+        successes: number;
+        isOpen: boolean;
+        failureRate: number;
+    };
+}
+declare function getCircuitBreaker(): QwenCircuitBreaker;
+
+/**
+ * MCP (Model Context Protocol) Types
+ *
+ * Standard types for the Model Context Protocol.
+ *
+ * @packageDocumentation
+ */
+interface ToolDefinition {
+    /** Tool name (must be unique) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** JSON Schema for tool input */
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+interface ToolCallRequest {
+    type: 'tool_call';
+    name: string;
+    input: unknown;
+}
+interface ToolCallResponse {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+interface ResourceDefinition {
+    /** Resource URI (e.g., "schema://patterns") */
+    uri: string;
+    /** Human-readable name */
+    name: string;
+    /** MIME type of resource content */
+    mimeType: string;
+    /** Description of the resource */
+    description: string;
+}
+interface ResourceRequest {
+    type: 'resource_request';
+    uri: string;
+}
+interface ResourceResponse {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+interface MCPClientConfig {
+    /** Server URL */
+    serverUrl: string;
+    /** Auth token if required */
+    authToken?: string;
+    /** Request timeout in ms */
+    timeoutMs?: number;
+}
+interface MCPDiscoveryRequest {
+    type: 'discovery';
+}
+
+/**
+ * MCP (Model Context Protocol) Server - Phase 3.1
+ *
+ * Exposes Almadar tools via the Model Context Protocol standard.
+ * Allows external agents (Claude Desktop, etc.) to use our tools.
+ *
+ * @packageDocumentation
+ */
+
+interface MCPServerConfig {
+    name: string;
+    version: string;
+    port?: number;
+    enableCors?: boolean;
+    authToken?: string;
+}
+interface MCPDiscoveryResponse {
+    name: string;
+    version: string;
+    tools: ToolDefinition[];
+    resources: ResourceDefinition[];
+}
+declare class MCPToolRegistry {
+    private tools;
+    private handlers;
+    registerTool<TInput = unknown, TOutput = unknown>(definition: ToolDefinition, handler: (input: TInput) => Promise<TOutput>): void;
+    callTool(name: string, input: unknown): Promise<ToolCallResponse>;
+    listTools(): ToolDefinition[];
+    hasTool(name: string): boolean;
+}
+declare class MCPResourceRegistry {
+    private resources;
+    private handlers;
+    registerResource(definition: ResourceDefinition, handler: () => Promise<unknown>): void;
+    getResource(uri: string): Promise<ResourceResponse>;
+    listResources(): ResourceDefinition[];
+}
+declare class MCPServer {
+    private config;
+    private toolRegistry;
+    private resourceRegistry;
+    constructor(config: MCPServerConfig);
+    /**
+     * Register an orbital generation tool
+     */
+    registerOrbitalTools(): void;
+    /**
+     * Register MCP resources
+     */
+    registerResources(): void;
+    /**
+     * Handle discovery request (list all tools and resources)
+     */
+    handleDiscovery(): MCPDiscoveryResponse;
+    /**
+     * Handle tool call
+     */
+    handleToolCall(request: ToolCallRequest): Promise<ToolCallResponse>;
+    /**
+     * Handle resource request
+     */
+    handleResourceRequest(request: ResourceRequest): Promise<ResourceResponse>;
+    /**
+     * Get tool registry for external access
+     */
+    getToolRegistry(): MCPToolRegistry;
+    /**
+     * Get resource registry for external access
+     */
+    getResourceRegistry(): MCPResourceRegistry;
+    /**
+     * Create HTTP request handler for Express/Fastify
+     */
+    createRequestHandler(): (request: {
+        method: string;
+        body: unknown;
+    }) => Promise<unknown>;
+}
+declare function createMCPServer(config: MCPServerConfig): MCPServer;
+/**
+ * Create and configure a standard Almadar MCP server
+ */
+declare function createAlmadarMCPServer(options?: Partial<MCPServerConfig>): MCPServer;
+
+/**
+ * MCP (Model Context Protocol) Client - Phase 3.1
+ *
+ * Client for calling external MCP servers.
+ * Allows our agent to use tools from other MCP-compliant servers.
+ *
+ * @packageDocumentation
+ */
+
+declare class MCPClient {
+    private config;
+    private cachedTools;
+    private cachedResources;
+    private cacheExpiry;
+    constructor(config: MCPClientConfig);
+    /**
+     * Discover available tools and resources from server
+     */
+    discover(): Promise<{
+        tools: ToolDefinition[];
+        resources: ResourceDefinition[];
+        name: string;
+        version: string;
+    }>;
+    /**
+     * Call a tool on the MCP server
+     */
+    callTool(name: string, input: unknown): Promise<ToolCallResponse>;
+    /**
+     * Get a resource from the MCP server
+     */
+    getResource(uri: string): Promise<ResourceResponse>;
+    /**
+     * List available tools (from cache or discovery)
+     */
+    listTools(): Promise<ToolDefinition[]>;
+    /**
+     * List available resources (from cache or discovery)
+     */
+    listResources(): Promise<ResourceDefinition[]>;
+    /**
+     * Check if a tool is available
+     */
+    hasTool(name: string): Promise<boolean>;
+    /**
+     * Get tool definition
+     */
+    getTool(name: string): Promise<ToolDefinition | null>;
+    /**
+     * Clear cache and force re-discovery
+     */
+    clearCache(): void;
+    private sendRequest;
+}
+interface RegisteredMCPServer {
+    name: string;
+    client: MCPClient;
+    description?: string;
+}
+declare class MCPClientManager {
+    private servers;
+    /**
+     * Register an MCP server
+     */
+    registerServer(name: string, config: MCPClientConfig, description?: string): void;
+    /**
+     * Get client for a specific server
+     */
+    getClient(name: string): MCPClient | null;
+    /**
+     * Call a tool on a specific server
+     */
+    callTool(serverName: string, toolName: string, input: unknown): Promise<ToolCallResponse>;
+    /**
+     * Discover all registered servers
+     */
+    discoverAll(): Promise<Record<string, {
+        tools: ToolDefinition[];
+        resources: ResourceDefinition[];
+    }>>;
+    /**
+     * List all registered servers
+     */
+    listServers(): Array<{
+        name: string;
+        description?: string;
+    }>;
+    /**
+     * Unregister a server
+     */
+    unregisterServer(name: string): void;
+    /**
+     * Clear all caches
+     */
+    clearAllCaches(): void;
+}
+declare function createMCPClient(config: MCPClientConfig): MCPClient;
+declare function createMCPClientManager(): MCPClientManager;
+/**
+ * Create a pre-configured client manager with common MCP servers
+ */
+declare function createDefaultMCPClientManager(): MCPClientManager;
+
+/**
+ * Online Evaluations - Phase 3.2a: Simple Sampling
+ *
+ * 10% traffic sampling with async validation and basic alerting.
+ * Non-blocking - runs in background without affecting user response.
+ *
+ * @packageDocumentation
+ */
+
+interface SamplingConfig {
+    /** Sampling rate (0.0 - 1.0) */
+    sampleRate: number;
+    /** Async queue size */
+    maxQueueSize: number;
+    /** Validation timeout */
+    validationTimeoutMs: number;
+    /** Alert threshold for error rate */
+    errorRateThreshold: number;
+    /** Alert window in ms */
+    alertWindowMs: number;
+}
+interface EvalSample {
+    sampleId: string;
+    timestamp: number;
+    request: {
+        prompt: string;
+        provider: string;
+        model: string;
+    };
+    result: {
+        success: boolean;
+        schema?: unknown;
+        error?: string;
+        latencyMs: number;
+    };
+    validation?: {
+        automatedScore: number;
+        syntaxErrors: number;
+        structureWarnings: number;
+        timestamp: number;
+    };
+}
+interface ErrorAlert {
+    alertId: string;
+    timestamp: number;
+    errorRate: number;
+    threshold: number;
+    windowStart: number;
+    sampleCount: number;
+    errorCount: number;
+}
+interface SamplingStats {
+    totalSampled: number;
+    totalValidated: number;
+    averageScore: number;
+    currentErrorRate: number;
+    queueSize: number;
+    isHealthy: boolean;
+}
+declare class OnlineEvalSampler extends EventEmitter {
+    private config;
+    private queue;
+    private samples;
+    private errorWindow;
+    private isProcessing;
+    constructor(config?: Partial<SamplingConfig>);
+    /**
+     * Check if a request should be sampled
+     * Uses hash-based sampling for consistency
+     */
+    shouldSample(requestId: string): boolean;
+    /**
+     * Add a sample to the queue for async validation
+     */
+    sample(requestId: string, request: {
+        prompt: string;
+        provider: string;
+        model: string;
+    }, result: {
+        success: boolean;
+        schema?: unknown;
+        error?: string;
+        latencyMs: number;
+    }): Promise<void>;
+    /**
+     * Pull samples for manual review
+     */
+    pullSamples(options?: {
+        date?: Date;
+        limit?: number;
+        minScore?: number;
+    }): Promise<EvalSample[]>;
+    /**
+     * Get current stats
+     */
+    getStats(): SamplingStats;
+    /**
+     * Stop the processor
+     */
+    stop(): void;
+    private startProcessor;
+    private validateSample;
+    private runAutomatedValidation;
+    private trackError;
+    private calculateErrorRate;
+}
+interface ReviewOptions {
+    date?: string;
+    limit?: number;
+    minScore?: number;
+    format?: 'json' | 'table';
+}
+declare function reviewSamples(sampler: OnlineEvalSampler, options?: ReviewOptions): Promise<void>;
+declare function createOnlineEvalSampler(config?: Partial<SamplingConfig>): OnlineEvalSampler;
+
+/**
+ * Tool Composition & Chaining - Phase 3.3
+ *
+ * Composable tool workflows with parallel execution, error handling,
+ * and conditional branching.
+ *
+ * @packageDocumentation
+ */
+type ToolStepStatus = 'pending' | 'running' | 'success' | 'error' | 'skipped';
+interface ToolStep {
+    id: string;
+    name: string;
+    tool: string;
+    input: Record<string, unknown> | ((context: WorkflowContext) => Record<string, unknown>);
+    condition?: (context: WorkflowContext) => boolean;
+    dependsOn?: string[];
+    status: ToolStepStatus;
+    output?: unknown;
+    error?: string;
+    startTime?: number;
+    endTime?: number;
+}
+interface WorkflowContext {
+    workflowId: string;
+    inputs: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+    stepResults: Map<string, {
+        success: boolean;
+        output?: unknown;
+        error?: string;
+    }>;
+    metadata: {
+        startTime: number;
+        stepsCompleted: number;
+        stepsFailed: number;
+    };
+}
+interface WorkflowDefinition {
+    name: string;
+    description: string;
+    inputs: Record<string, {
+        type: string;
+        required: boolean;
+        default?: unknown;
+    }>;
+    steps: ToolStep[];
+    onError?: 'stop' | 'continue' | 'retry';
+    maxRetries?: number;
+}
+interface WorkflowExecutionResult {
+    success: boolean;
+    workflowId: string;
+    context: WorkflowContext;
+    steps: ToolStep[];
+    durationMs: number;
+    error?: string;
+}
+interface ParallelExecutionResult {
+    stepId: string;
+    success: boolean;
+    output?: unknown;
+    error?: string;
+    durationMs: number;
+}
+interface ToolExecutor {
+    execute(tool: string, input: Record<string, unknown>): Promise<unknown>;
+}
+declare class WorkflowEngine {
+    private executor;
+    private workflows;
+    constructor(executor: ToolExecutor);
+    /**
+     * Register a workflow definition
+     */
+    registerWorkflow(definition: WorkflowDefinition): void;
+    /**
+     * Execute a workflow by name
+     */
+    executeWorkflow(workflowName: string, inputs: Record<string, unknown>): Promise<WorkflowExecutionResult>;
+    /**
+     * Execute a workflow definition directly
+     */
+    runWorkflow(definition: WorkflowDefinition, inputs: Record<string, unknown>): Promise<WorkflowExecutionResult>;
+    /**
+     * Execute independent steps in parallel
+     */
+    executeParallel(steps: Array<{
+        id: string;
+        tool: string;
+        input: Record<string, unknown>;
+    }>, context: WorkflowContext): Promise<ParallelExecutionResult[]>;
+    /**
+     * Create a workflow builder for fluent API
+     */
+    createWorkflow(name: string, description: string): WorkflowBuilder;
+    private executeStep;
+    private resolveDependencies;
+}
+declare class WorkflowBuilder {
+    private engine;
+    private definition;
+    constructor(engine: WorkflowEngine, name: string, description: string);
+    input(name: string, type: string, required?: boolean, defaultValue?: unknown): this;
+    step(id: string, tool: string, input: Record<string, unknown> | ((context: WorkflowContext) => Record<string, unknown>), options?: {
+        dependsOn?: string[];
+        condition?: (context: WorkflowContext) => boolean;
+    }): this;
+    parallel(steps: Array<{
+        id: string;
+        tool: string;
+        input: Record<string, unknown>;
+    }>): this;
+    onError(policy: 'stop' | 'continue' | 'retry'): this;
+    retry(maxRetries: number): this;
+    build(): WorkflowDefinition;
+    execute(inputs: Record<string, unknown>): Promise<WorkflowExecutionResult>;
+}
+declare function createSchemaGenerationWorkflow(engine: WorkflowEngine): WorkflowDefinition;
+declare function createWorkflowEngine(executor: ToolExecutor): WorkflowEngine;
+
+export { type AccessCheckResult, AgenticSearchEngine, type AgenticSearchParams, type AgenticSearchResponse, type ConflictResolution, type DeepAgentCompleteEvent, type DeepAgentErrorEvent, type DeepAgentEvent, type DeepAgentExecutionEvent, type DeepAgentSchemaEvent, type DeepAgentStartEvent, type ErrorAlert, type EvalSample, type GenerationMetrics, GenerationSession, type HealthCheckResult, type InferredPreference, type LLMProvider, MCPClient, type MCPClientConfig, MCPClientManager, type MCPDiscoveryRequest, type MCPDiscoveryResponse, MCPResourceRegistry, MCPServer, type MCPServerConfig, MCPToolRegistry, MemoryManager, MetricsCollector, type MetricsSummary, ModelRouter, type ModelRouterConfig, MultiUserManager, ObservabilityCollector, type ObservableEvent, type ObservableEventType, OnlineEvalSampler, type CombinerOptions as OrbitalCombinerOptions, type CombinerResult as OrbitalCombinerResult, type OrbitalEstimation, type OrbitalSchemaValidationResult, type ParallelExecutionResult, type PerformanceSnapshot, type PreferenceAnalysis, PreferenceLearner, type PreferenceLearnerOptions, type ProviderConfig, QwenCircuitBreaker, type RegisteredMCPServer, type ResourceDefinition, type ResourceRequest, type ResourceResponse, type ReviewOptions, type RoutingDecision, type RoutingStrategy, type SamplingConfig, type SamplingStats, type ScopedSessionMetadata, type SearchResult, type SearchStrategy, SessionMetadata, type SessionTelemetry, type StateChangeEvent, type StateChangeType, type StateSyncConfig, StateSyncManager, type StateSyncSnapshot, SubAgent, type ToolCallRequest, type ToolCallResponse, type ToolDefinition, type ToolExecutor, type ToolStep, type ToolStepStatus, type UserContext, UserPreference, type UserSessionStats, type VersionVector, WorkflowBuilder, type WorkflowContext, type WorkflowDefinition, WorkflowEngine, type WorkflowExecutionResult, analyzeFailures, applyConservativeBias, combineOrbitals, combineOrbitalsToSchema, createAgenticSearchEngine, createAlmadarMCPServer, createDefaultMCPClientManager, createErrorFixerSubagent, createMCPClient, createMCPClientManager, createMCPServer, createModelRouter, createOnlineEvalSampler, createPreferenceLearner, createSchemaGenerationWorkflow, createSchemaGeneratorSubagent, createSubagentConfigs, createSubagents, createTestAnalyzerSubagent, createUserContext, createWorkflowEngine, debounceSync, endObservabilitySession, estimateCacheSavings, estimateCombineComplexity, estimateOrbitalCount, estimateOrbitalCountBatch, estimateOrbitalCountHeuristic, estimateOrbitalCountLLM, formatSummary, generateFullOrbital, getCircuitBreaker, getModelRouter, getMultiUserManager, getObservabilityCollector, getPerformanceSnapshot, getStateSyncManager, hasDefiniteComplexIndicators, isAdmin, isCompleteEvent, isErrorEvent, isExecutionEvent, isSchemaEvent, isStartEvent, makeSafeRoutingDecision, parseDeepAgentEvent, quickEstimate, recordEvent, requireOwnership, resetMultiUserManager, resetObservabilityCollector, resetStateSyncManager, reviewSamples, safeEstimate, startObservabilitySession, withSync };