@probelabs/visor 0.1.106 → 0.1.111

package/dist/sdk/sdk.d.ts

@@ -120,7 +120,7 @@ interface FailureConditionResult {
 /**
  * Valid check types in configuration
  */
-type ConfigCheckType = 'ai' | 'command' | 'http' | 'http_input' | 'http_client' | 'noop' | 'log' | 'memory' | 'github' | 'claude-code' | 'mcp' | 'human-input';
+type ConfigCheckType = 'ai' | 'command' | 'script' | 'http' | 'http_input' | 'http_client' | 'noop' | 'log' | 'memory' | 'github' | 'claude-code' | 'mcp' | 'human-input' | 'workflow' | 'git-checkout';
 /**
  * Valid event triggers for checks
  */
@@ -148,6 +148,71 @@ type GroupByOption = 'check' | 'file' | 'severity' | 'group';
 interface EnvConfig {
     [key: string]: string | number | boolean;
 }
+/**
+ * Retry configuration for AI provider calls
+ */
+interface AIRetryConfig {
+    /** Maximum retry attempts (0-50) */
+    maxRetries?: number;
+    /** Initial delay in milliseconds (0-60000) */
+    initialDelay?: number;
+    /** Maximum delay cap in milliseconds (0-300000) */
+    maxDelay?: number;
+    /** Exponential backoff multiplier (1-10) */
+    backoffFactor?: number;
+    /** Custom error patterns to retry on */
+    retryableErrors?: string[];
+}
+/**
+ * Fallback provider configuration
+ */
+interface AIFallbackProviderConfig {
+    /** AI provider to use */
+    provider: 'google' | 'anthropic' | 'openai' | 'bedrock';
+    /** Model name to use */
+    model: string;
+    /** API key for this provider */
+    apiKey?: string;
+    /** Per-provider retry override */
+    maxRetries?: number;
+    /** AWS region (for Bedrock) */
+    region?: string;
+    /** AWS access key ID (for Bedrock) */
+    accessKeyId?: string;
+    /** AWS secret access key (for Bedrock) */
+    secretAccessKey?: string;
+}
+/**
+ * Fallback configuration for AI providers
+ */
+interface AIFallbackConfig {
+    /** Fallback strategy: 'same-model', 'same-provider', 'any', or 'custom' */
+    strategy?: 'same-model' | 'same-provider' | 'any' | 'custom';
+    /** Array of fallback provider configurations */
+    providers?: AIFallbackProviderConfig[];
+    /** Maximum total attempts across all providers */
+    maxTotalAttempts?: number;
+    /** Enable automatic fallback using available environment variables */
+    auto?: boolean;
+}
+/**
+ * Bash command execution configuration for ProbeAgent
+ * Note: Use 'allowBash: true' in AIProviderConfig to enable bash execution
+ */
+interface BashConfig {
+    /** Array of permitted command patterns (e.g., ['ls', 'git status']) */
+    allow?: string[];
+    /** Array of blocked command patterns (e.g., ['rm -rf', 'sudo']) */
+    deny?: string[];
+    /** Disable default safe command list (use with caution) */
+    noDefaultAllow?: boolean;
+    /** Disable default dangerous command blocklist (use with extreme caution) */
+    noDefaultDeny?: boolean;
+    /** Execution timeout in milliseconds */
+    timeout?: number;
+    /** Default working directory for command execution */
+    workingDirectory?: string;
+}
 /**
  * AI provider configuration
  */
@@ -162,8 +227,43 @@ interface AIProviderConfig {
     timeout?: number;
     /** Enable debug mode */
     debug?: boolean;
+    /** Probe promptType to use (e.g., engineer, code-review, architect) */
+    prompt_type?: string;
+    /** System prompt (baseline preamble). Replaces legacy custom_prompt. */
+    system_prompt?: string;
+    /** Probe customPrompt (baseline/system prompt) — deprecated, use system_prompt */
+    custom_prompt?: string;
+    /** Skip adding code context (diffs, files, PR info) to the prompt */
+    skip_code_context?: boolean;
+    /** Skip adding Slack conversation context to the prompt (when running under Slack) */
+    skip_slack_context?: boolean;
+    /**
+     * Skip adding transport-specific context (e.g., GitHub PR/issue XML, Slack
+     * conversation XML) to the prompt. When true, this behaves like setting both
+     * skip_code_context and skip_slack_context to true, unless those are
+     * explicitly overridden.
+     */
+    skip_transport_context?: boolean;
     /** MCP servers configuration */
     mcpServers?: Record<string, McpServerConfig>;
+    /** Enable the delegate tool for task distribution to subagents */
+    enableDelegate?: boolean;
+    /** Retry configuration for this provider */
+    retry?: AIRetryConfig;
+    /** Fallback configuration for provider failures */
+    fallback?: AIFallbackConfig;
+    /** Enable Edit and Create tools for file modification (disabled by default for security) */
+    allowEdit?: boolean;
+    /** Filter allowed tools - supports whitelist, exclusion (!prefix), or raw AI mode (empty array) */
+    allowedTools?: string[];
+    /** Disable all tools for raw AI mode (alternative to allowedTools: []) */
+    disableTools?: boolean;
+    /** Enable bash command execution (shorthand for bashConfig.enabled) */
+    allowBash?: boolean;
+    /** Advanced bash command execution configuration */
+    bashConfig?: BashConfig;
+    /** Completion prompt for post-completion validation/review (runs after attempt_completion) */
+    completion_prompt?: string;
 }
 /**
  * MCP Server configuration
@@ -190,6 +290,8 @@ interface ClaudeCodeConfig {
     mcpServers?: Record<string, McpServerConfig>;
     /** Path to subagent script */
     subagent?: string;
+    /** Enable the delegate tool for task distribution to subagents */
+    enableDelegate?: boolean;
     /** Event hooks for lifecycle management */
     hooks?: {
         /** Called when check starts */
@@ -228,6 +330,8 @@ interface CheckConfig {
     transform?: string;
     /** Transform using JavaScript expressions (evaluated in secure sandbox) - optional */
     transform_js?: string;
+    /** Script content to execute for script checks */
+    content?: string;
     /** Cron schedule expression (e.g., "0 2 * * *") - optional for any check type */
     schedule?: string;
     /** Focus area for the check (security/performance/style/architecture/all) - optional */
@@ -244,20 +348,37 @@ interface CheckConfig {
     ai_model?: string;
     /** AI provider to use for this check - overrides global setting */
     ai_provider?: 'google' | 'anthropic' | 'openai' | 'bedrock' | 'mock' | string;
+    /** Optional persona hint, prepended to the prompt as 'Persona: <value>' */
+    ai_persona?: string;
+    /** Probe promptType for this check (underscore style) */
+    ai_prompt_type?: string;
+    /** System prompt for this check (underscore style) */
+    ai_system_prompt?: string;
+    /** Legacy customPrompt (underscore style) — deprecated, use ai_system_prompt */
+    ai_custom_prompt?: string;
     /** MCP servers for this AI check - overrides global setting */
     ai_mcp_servers?: Record<string, McpServerConfig>;
+    /** List of custom tool names to expose to this AI check via ephemeral SSE MCP server */
+    ai_custom_tools?: string[];
     /** Claude Code configuration (for claude-code type checks) */
     claude_code?: ClaudeCodeConfig;
     /** Environment variables for this check */
     env?: EnvConfig;
     /** Timeout in seconds for command execution (default: 60) */
     timeout?: number;
-    /** Check IDs that this check depends on (optional) */
-    depends_on?: string[];
+    /** Check IDs that this check depends on (optional). Accepts single string or array. */
+    depends_on?: string | string[];
     /** Group name for comment separation (e.g., "code-review", "pr-overview") - optional */
     group?: string;
     /** Schema type for template rendering (e.g., "code-review", "markdown") or inline JSON schema object - optional */
     schema?: string | Record<string, unknown>;
+    /**
+     * Optional JSON Schema to validate the produced output. If omitted and
+     * `schema` is an object, the engine will treat that object as the
+     * output_schema for validation purposes while still using string schemas
+     * (e.g., 'code-review') for template selection.
+     */
+    output_schema?: Record<string, unknown>;
     /** Custom template configuration - optional */
     template?: CustomTemplateConfig;
     /** Condition to determine if check should run - runs if expression evaluates to true */
@@ -272,12 +393,59 @@ interface CheckConfig {
     failure_conditions?: FailureConditions;
     /** Tags for categorizing and filtering checks (e.g., ["local", "fast", "security"]) */
     tags?: string[];
+    /**
+     * Operational criticality of this step. Drives default safety policies
+     * (contracts, retries, loop budgets) at load time. Behavior can still be
+     * overridden explicitly per step via on_*, fail_if, assume/guarantee, etc.
+     *
+     * - 'external': interacts with external systems (side effects). Highest safety.
+     * - 'internal': modifies CI/config/state but not prod. High safety.
+     * - 'policy': organizational checks (linting, style, doc). Moderate safety.
+     * - 'info': informational checks. Lowest safety.
+     */
+    criticality?: 'external' | 'internal' | 'policy' | 'info';
+    /**
+     * Allow dependents to run even if this step fails.
+     * Defaults to false (dependents are gated when this step fails).
+     * Similar to GitHub Actions' continue-on-error.
+     */
+    continue_on_failure?: boolean;
     /** Process output as array and run dependent checks for each item */
     forEach?: boolean;
+    /**
+     * Control scheduling behavior when this check is triggered via routing (run/goto)
+     * from a forEach scope.
+     * - 'map': schedule once per item (fan-out) using item scopes.
+     * - 'reduce': schedule a single run at the parent scope (aggregation).
+     * If unset, the current default is a single run (reduce) for backward compatibility.
+     */
+    fanout?: 'map' | 'reduce';
+    /** Alias for fanout: 'reduce' */
+    reduce?: boolean;
+    /** Init routing configuration for this check (runs before execution/preprocessing) */
+    on_init?: OnInitConfig;
     /** Failure routing configuration for this check (retry/goto/run) */
     on_fail?: OnFailConfig;
     /** Success routing configuration for this check (post-actions and optional goto) */
     on_success?: OnSuccessConfig;
+    /** Finish routing configuration for forEach checks (runs after ALL iterations complete) */
+    on_finish?: OnFinishConfig;
+    /**
+     * Preconditions that must hold before executing the check. If any expression
+     * evaluates to false, the check is skipped (skipReason='assume').
+     */
+    assume?: string | string[];
+    /**
+     * Postconditions that should hold after executing the check. Expressions are
+     * evaluated against the produced result/output; violations are recorded as
+     * error issues with ruleId "contract/guarantee_failed".
+     */
+    guarantee?: string | string[];
+    /**
+     * Hard cap on how many times this check may execute within a single engine run.
+     * Overrides global limits.max_runs_per_check. Set to 0 or negative to disable for this step.
+     */
+    max_runs?: number;
     /**
      * Log provider specific options (optional, only used when type === 'log').
      * Declared here to ensure JSON Schema allows these keys and Ajv does not warn.
@@ -292,19 +460,25 @@ interface CheckConfig {
     include_dependencies?: boolean;
     /** Include execution metadata in log output */
     include_metadata?: boolean;
+    /**
+     * Output parsing hint for command provider (optional)
+     * When set to 'json', command stdout is expected to be JSON. When 'text', treat as plain text.
+     * Note: command provider attempts JSON parsing heuristically; this flag mainly suppresses schema warnings
+     * and may be used by providers to alter parsing behavior in the future.
+     */
+    output_format?: 'json' | 'text';
     /**
      * Memory provider specific options (optional, only used when type === 'memory').
      */
     /** Memory operation to perform */
-    operation?: 'get' | 'set' | 'append' | 'increment' | 'delete' | 'clear' | 'list' | 'exec_js';
+    /** Memory operation to perform. Use `type: 'script'` for custom JavaScript. */
+    operation?: 'get' | 'set' | 'append' | 'increment' | 'delete' | 'clear' | 'list';
     /** Key for memory operation */
     key?: string;
     /** Value for set/append operations */
     value?: unknown;
     /** JavaScript expression to compute value dynamically */
     value_js?: string;
-    /** JavaScript code for exec_js operation with full memory access */
-    memory_js?: string;
     /** Override namespace for this check */
     namespace?: string;
     /**
@@ -326,7 +500,7 @@ interface CheckConfig {
     /** Session ID for HTTP transport (optional, server may generate one) */
     sessionId?: string;
     /** Command arguments (for stdio transport in MCP checks) */
-    args?: string[];
+    command_args?: string[];
     /** Working directory (for stdio transport in MCP checks) */
     workingDirectory?: string;
     /**
@@ -340,6 +514,54 @@ interface CheckConfig {
     multiline?: boolean;
     /** Default value if timeout occurs or empty input when allow_empty is true */
     default?: string;
+    /**
+     * Workflow provider specific options (optional, only used when type === 'workflow').
+     */
+    /** Workflow ID or path to workflow file */
+    workflow?: string;
+    /** Arguments/inputs for the workflow */
+    args?: Record<string, unknown>;
+    /** Override specific step configurations in the workflow */
+    overrides?: Record<string, Partial<CheckConfig>>;
+    /** Map workflow outputs to check outputs */
+    output_mapping?: Record<string, string>;
+    /** Alias for args - workflow inputs (backward compatibility) */
+    workflow_inputs?: Record<string, unknown>;
+    /** Config file path - alternative to workflow ID (loads a Visor config file as workflow) */
+    config?: string;
+    /** Alias for overrides - workflow step overrides (backward compatibility) */
+    workflow_overrides?: Record<string, Partial<CheckConfig>>;
+    /**
+     * Git-checkout provider specific options (optional, only used when type === 'git-checkout').
+     */
+    /** Git reference to checkout (branch, tag, commit SHA) - supports templates */
+    ref?: string;
+    /** Repository URL or owner/repo format (defaults to current repository) */
+    repository?: string;
+    /** GitHub token for private repositories (defaults to GITHUB_TOKEN env) */
+    token?: string;
+    /** Number of commits to fetch (0 for full history, default: 1) */
+    fetch_depth?: number;
+    /** Whether to fetch tags (default: false) */
+    fetch_tags?: boolean;
+    /** Checkout submodules: false, true, or 'recursive' */
+    submodules?: boolean | 'recursive';
+    /** Working directory for the checkout (defaults to temp directory) */
+    working_directory?: string;
+    /** Use git worktree for efficient parallel checkouts (default: true) */
+    use_worktree?: boolean;
+    /** Clean the working directory before checkout (default: true) */
+    clean?: boolean;
+    /** Sparse checkout paths - only checkout specific directories/files */
+    sparse_checkout?: string[];
+    /** Enable Git LFS (Large File Storage) */
+    lfs?: boolean;
+    /** Timeout in ms for cloning the bare repository (default: 300000 = 5 min) */
+    clone_timeout_ms?: number;
+    /** Clean up worktree on failure (default: true) */
+    cleanup_on_failure?: boolean;
+    /** Keep worktree after workflow completion (default: false) */
+    persist_worktree?: boolean;
 }
 /**
  * Backoff policy for retries
@@ -375,6 +597,12 @@ interface OnFailConfig {
     goto_js?: string;
     /** Dynamic remediation list: JS expression returning string[] */
     run_js?: string;
+    /**
+     * Declarative transitions. Evaluated in order; first matching rule wins.
+     * If a rule's `to` is null, no goto occurs. When omitted or none match,
+     * the engine falls back to goto_js/goto for backward compatibility.
+     */
+    transitions?: TransitionRule[];
 }
 /**
  * Success routing configuration per check
@@ -390,6 +618,90 @@ interface OnSuccessConfig {
     goto_js?: string;
     /** Dynamic post-success steps: JS expression returning string[] */
     run_js?: string;
+    /** Declarative transitions (see OnFailConfig.transitions). */
+    transitions?: TransitionRule[];
+}
+/**
+ * Finish routing configuration for forEach checks
+ * Runs once after ALL iterations of forEach and ALL dependent checks complete
+ */
+interface OnFinishConfig {
+    /** Post-finish steps to run */
+    run?: string[];
+    /** Optional jump back to ancestor step (by id) */
+    goto?: string;
+    /** Simulate a different event when performing goto (e.g., 'pr_updated') */
+    goto_event?: EventTrigger;
+    /** Dynamic goto: JS expression returning step id or null */
+    goto_js?: string;
+    /** Dynamic post-finish steps: JS expression returning string[] */
+    run_js?: string;
+    /** Declarative transitions (see OnFailConfig.transitions). */
+    transitions?: TransitionRule[];
+}
+/**
+ * Init routing configuration per check
+ * Runs BEFORE the check executes (preprocessing/setup)
+ */
+interface OnInitConfig {
+    /** Items to run before this check executes */
+    run?: OnInitRunItem[];
+    /** Dynamic init items: JS expression returning OnInitRunItem[] */
+    run_js?: string;
+    /** Declarative transitions (optional, for advanced use cases) */
+    transitions?: TransitionRule[];
+}
+/**
+ * Unified on_init run item - can be tool, step, workflow, or plain string
+ */
+type OnInitRunItem = OnInitToolInvocation | OnInitStepInvocation | OnInitWorkflowInvocation | string;
+/**
+ * Invoke a custom tool (from tools: section)
+ */
+interface OnInitToolInvocation {
+    /** Tool name (must exist in tools: section) */
+    tool: string;
+    /** Arguments to pass to the tool (Liquid templates supported) */
+    with?: Record<string, unknown>;
+    /** Custom output name (defaults to tool name) */
+    as?: string;
+}
+/**
+ * Invoke a helper step (regular check)
+ */
+interface OnInitStepInvocation {
+    /** Step name (must exist in steps: section) */
+    step: string;
+    /** Arguments to pass to the step (Liquid templates supported) */
+    with?: Record<string, unknown>;
+    /** Custom output name (defaults to step name) */
+    as?: string;
+}
+/**
+ * Invoke a reusable workflow
+ */
+interface OnInitWorkflowInvocation {
+    /** Workflow ID or path */
+    workflow: string;
+    /** Workflow inputs (Liquid templates supported) */
+    with?: Record<string, unknown>;
+    /** Custom output name (defaults to workflow name) */
+    as?: string;
+    /** Step overrides */
+    overrides?: Record<string, Partial<CheckConfig>>;
+    /** Output mapping */
+    output_mapping?: Record<string, string>;
+}
+/**
+ * Declarative transition rule for on_* blocks.
+ */
+interface TransitionRule {
+    /** JavaScript expression evaluated in the same sandbox as goto_js; truthy enables the rule. */
+    when: string;
+    /** Target step ID, or null to explicitly prevent goto. */
+    to?: string | null;
+    /** Optional event override when performing goto. */
+    goto_event?: EventTrigger;
 }
 /**
  * Global routing defaults
@@ -402,6 +714,23 @@ interface RoutingDefaults {
         on_fail?: OnFailConfig;
     };
 }
+/**
+ * Global engine limits
+ */
+interface LimitsConfig {
+    /**
+     * Maximum number of executions per check within a single engine run.
+     * Applies to each distinct scope independently for forEach item executions.
+     * Set to 0 or negative to disable. Default: 50.
+     */
+    max_runs_per_check?: number;
+    /**
+     * Maximum nesting depth for workflows executed by the state machine engine.
+     * Nested workflows are invoked by the workflow provider; this limit prevents
+     * accidental infinite recursion. Default: 3.
+     */
+    max_workflow_depth?: number;
+}
 /**
  * Custom template configuration
  */
@@ -430,6 +759,8 @@ interface DebugConfig {
  * PR comment output configuration
  */
 interface PrCommentOutput {
+    /** Whether PR comments are enabled */
+    enabled?: boolean;
     /** Format of the output */
     format: ConfigOutputFormat;
     /** How to group the results */
@@ -571,6 +902,68 @@ interface VisorHooks {
     /** Called when human input is required */
     onHumanInput?: (request: HumanInputRequest) => Promise<string>;
 }
+/**
+ * Custom tool definition for use in MCP blocks
+ */
+interface CustomToolDefinition {
+    /** Tool name - used to reference the tool in MCP blocks */
+    name: string;
+    /** Description of what the tool does */
+    description?: string;
+    /** Input schema for the tool (JSON Schema format) */
+    inputSchema?: {
+        type: 'object';
+        properties?: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+    /** Command to execute - supports Liquid template */
+    exec: string;
+    /** Optional stdin input - supports Liquid template */
+    stdin?: string;
+    /** Transform the raw output - supports Liquid template */
+    transform?: string;
+    /** Transform the output using JavaScript - alternative to transform */
+    transform_js?: string;
+    /** Working directory for command execution */
+    cwd?: string;
+    /** Environment variables for the command */
+    env?: Record<string, string>;
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Whether to parse output as JSON automatically */
+    parseJson?: boolean;
+    /** Expected output schema for validation */
+    outputSchema?: Record<string, unknown>;
+}
+/**
+ * Workflow input definition for standalone reusable workflows
+ */
+interface WorkflowInput {
+    /** Input parameter name */
+    name: string;
+    /** JSON Schema for the input */
+    schema?: Record<string, unknown>;
+    /** Whether this input is required */
+    required?: boolean;
+    /** Default value if not provided */
+    default?: unknown;
+    /** Human-readable description */
+    description?: string;
+}
+/**
+ * Workflow output definition for standalone reusable workflows
+ */
+interface WorkflowOutput {
+    /** Output name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Value using Liquid template syntax (references step outputs) */
+    value?: string;
+    /** Value using JavaScript expression (alternative to value) */
+    value_js?: string;
+}
 /**
  * Main Visor configuration
  */
@@ -579,12 +972,22 @@ interface VisorConfig {
     version: string;
     /** Extends from other configurations - can be file path, HTTP(S) URL, or "default" */
     extends?: string | string[];
+    /** Alias for extends - include from other configurations (backward compatibility) */
+    include?: string | string[];
+    /** Custom tool definitions that can be used in MCP blocks */
+    tools?: Record<string, CustomToolDefinition>;
+    /** Import workflow definitions from external files or URLs */
+    imports?: string[];
+    /** Workflow inputs (for standalone reusable workflows) */
+    inputs?: WorkflowInput[];
+    /** Workflow outputs (for standalone reusable workflows) */
+    outputs?: WorkflowOutput[];
     /** Step configurations (recommended) */
     steps?: Record<string, CheckConfig>;
     /** Check configurations (legacy, use 'steps' instead) - always populated after normalization */
     checks?: Record<string, CheckConfig>;
-    /** Output configuration */
-    output: OutputConfig;
+    /** Output configuration (optional - defaults provided) */
+    output?: OutputConfig;
     /** HTTP server configuration for receiving webhooks */
     http_server?: HttpServerConfig;
     /** Memory storage configuration */
@@ -611,21 +1014,51 @@ interface VisorConfig {
     tag_filter?: TagFilter;
     /** Optional routing defaults for retry/goto/run policies */
     routing?: RoutingDefaults;
+    /** Global execution limits */
+    limits?: LimitsConfig;
+    /** Optional integrations: event-driven frontends (e.g., ndjson-sink, github) */
+    frontends?: Array<{
+        /** Frontend name, e.g., 'ndjson-sink', 'github' */
+        name: string;
+        /** Frontend-specific configuration */
+        config?: unknown;
+    }>;
+    /** Workspace isolation configuration for sandboxed execution */
+    workspace?: WorkspaceConfig;
+    /** Slack configuration */
+    slack?: SlackConfig;
 }
-
 /**
- * Execution context passed to check providers
+ * Workspace isolation configuration
  */
-interface ExecutionContext {
-    /** Session information for AI session reuse */
-    parentSessionId?: string;
-    reuseSession?: boolean;
-    /** CLI message value (from --message argument) */
-    cliMessage?: string;
-    /** SDK hooks for human input */
-    hooks?: {
-        onHumanInput?: (request: HumanInputRequest) => Promise<string>;
-    };
+interface WorkspaceConfig {
+    /** Enable workspace isolation (default: true when config present) */
+    enabled?: boolean;
+    /** Base path for workspaces (default: /tmp/visor-workspaces) */
+    base_path?: string;
+    /** Clean up workspace on exit (default: true) */
+    cleanup_on_exit?: boolean;
+}
+/**
+ * Slack configuration
+ */
+interface SlackConfig {
+    /** Slack API version */
+    version?: string;
+    /** Mention handling: 'all', 'direct', etc. */
+    mentions?: string;
+    /** Thread handling: 'required', 'optional', etc. */
+    threads?: string;
+    /** Show raw output in Slack responses */
+    show_raw_output?: boolean;
+    /**
+     * Append telemetry identifiers to Slack replies.
+     */
+    telemetry?: SlackTelemetryConfig;
+}
+interface SlackTelemetryConfig {
+    /** Enable telemetry ID suffix in Slack messages */
+    enabled?: boolean;
 }
 
 /**
@@ -636,10 +1069,12 @@ interface CheckExecutionStats {
     totalRuns: number;
     successfulRuns: number;
     failedRuns: number;
+    skippedRuns: number;
     skipped: boolean;
-    skipReason?: 'if_condition' | 'fail_fast' | 'dependency_failed';
+    skipReason?: 'if_condition' | 'fail_fast' | 'dependency_failed' | 'forEach_empty' | 'assume';
     skipCondition?: string;
     totalDuration: number;
+    providerDurationMs?: number;
     perIterationDuration?: number[];
     issuesFound: number;
     issuesBySeverity: {
@@ -715,6 +1150,90 @@ interface DebugInfo {
     }>;
 }
 
+interface EventEnvelope<T = any> {
+    id: string;
+    version: 1;
+    timestamp: string;
+    runId: string;
+    workflowId?: string;
+    caseId?: string;
+    wave?: number;
+    attempt?: number;
+    checkId?: string;
+    traceId?: string;
+    spanId?: string;
+    causationId?: string;
+    correlationId?: string;
+    payload: T;
+}
+type AnyEvent = any;
+
+type EventHandler<T = AnyEvent> = (event: T | EventEnvelope<T>) => void | Promise<void>;
+interface Subscription {
+    unsubscribe(): void;
+}
+declare class EventBus {
+    private handlers;
+    private anyHandlers;
+    on<T = AnyEvent>(eventType: string, handler: EventHandler<T>): Subscription;
+    onAny(handler: EventHandler): Subscription;
+    emit(event: AnyEvent | EventEnvelope): Promise<void>;
+}
+
+/**
+ * Execution context passed to check providers
+ */
+interface ExecutionContext {
+    /** Session information for AI session reuse */
+    parentSessionId?: string;
+    reuseSession?: boolean;
+    /** CLI message value (from --message argument) */
+    cliMessage?: string;
+    /**
+     * Stage-local baseline of output history lengths per check name.
+     * When present, providers should expose an `outputs_history_stage` object in
+     * Liquid/JS contexts that slices the global history from this baseline.
+     * This enables stage-scoped assertions in the YAML test runner without
+     * relying on global execution history.
+     */
+    stageHistoryBase?: Record<string, number>;
+    /** Workflow inputs - available when executing within a workflow */
+    workflowInputs?: Record<string, unknown>;
+    /** Custom arguments passed from on_init 'with' directive */
+    args?: Record<string, unknown>;
+    /** SDK hooks for human input */
+    hooks?: {
+        onHumanInput?: (request: HumanInputRequest) => Promise<string>;
+        onPromptCaptured?: (info: {
+            step: string;
+            provider: string;
+            prompt: string;
+        }) => void;
+        mockForStep?: (step: string) => unknown | undefined;
+    };
+    /**
+     * Optional execution mode hints. The core engine does not read environment
+     * variables directly; callers (CLI, test runner) can set these flags to
+     * request certain behaviors without polluting core logic with test-specific
+     * branches.
+     */
+    mode?: {
+        /** true when running under the YAML test runner */
+        test?: boolean;
+        /** post review comments from grouped execution paths (used by tests) */
+        postGroupedComments?: boolean;
+        /** reset per-run guard state before grouped execution */
+        resetPerRunState?: boolean;
+    };
+    /** Optional event bus for emitting integration events (e.g., HumanInputRequested) */
+    eventBus?: EventBus;
+    /** Optional webhook context (e.g., Slack Events API payload) */
+    webhookContext?: {
+        webhookData?: Map<string, unknown>;
+        eventType?: string;
+    };
+}
+
 interface VisorOptions {
     cwd?: string;
     debug?: boolean;