@probelabs/visor 0.1.106 → 0.1.107

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';
 /**
  * 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,32 @@ 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;
     /** 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;
 }
 /**
  * MCP Server configuration
@@ -190,6 +279,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 +319,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,6 +337,14 @@ 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>;
     /** Claude Code configuration (for claude-code type checks) */
@@ -258,6 +359,13 @@ interface CheckConfig {
     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 +380,57 @@ 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;
     /** 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 +445,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 +485,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 +499,17 @@ 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>;
 }
 /**
  * Backoff policy for retries
@@ -375,6 +545,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 +566,37 @@ 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[];
+}
+/**
+ * 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 +609,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
  */
@@ -571,6 +795,40 @@ 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>;
+}
 /**
  * Main Visor configuration
  */
@@ -579,6 +837,12 @@ 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[];
     /** Step configurations (recommended) */
     steps?: Record<string, CheckConfig>;
     /** Check configurations (legacy, use 'steps' instead) - always populated after normalization */
@@ -611,21 +875,15 @@ interface VisorConfig {
     tag_filter?: TagFilter;
     /** Optional routing defaults for retry/goto/run policies */
     routing?: RoutingDefaults;
-}
-
-/**
- * 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;
-    /** SDK hooks for human input */
-    hooks?: {
-        onHumanInput?: (request: HumanInputRequest) => Promise<string>;
-    };
+    /** 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;
+    }>;
 }
 
 /**
@@ -636,10 +894,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 +975,51 @@ interface DebugInfo {
     }>;
 }
 
+/**
+ * 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>;
+    /** 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;
+    };
+}
+
 interface VisorOptions {
     cwd?: string;
     debug?: boolean;