/**
 * Workflow Types for Relay Cloud Swarm Patterns
 *
 * Shared TypeScript types for relay.yaml configuration, workflow execution,
 * and database row representations.
 */
/** Top-level relay.yaml configuration file structure. */
export interface RelayYamlConfig {
    version: string;
    name: string;
    description?: string;
    /** Named paths to external directories used by this workflow.
     *  The primary working directory defaults to cwd and does not need to be declared.
     *  Use this to declare additional directories so the runner can validate them
     *  in preflight and agents can reference them via `workdir`. */
    paths?: PathDefinition[];
    swarm: SwarmConfig;
    agents: AgentDefinition[];
    workflows?: WorkflowDefinition[];
    coordination?: CoordinationConfig;
    state?: StateConfig;
    errorHandling?: ErrorHandlingConfig;
    trajectories?: TrajectoryConfig | false;
}
/** A named path to an external directory for cross-repo workflows.
 *  Only needed for directories outside the default working directory. */
export interface PathDefinition {
    /** Unique name used to reference this path (e.g. "relaycast"). */
    name: string;
    /** Directory path, resolved relative to the YAML file.
     *  Supports environment variables: "$HOME/.openclaw", "$RELAY_ROOT/packages/sdk". */
    path: string;
    /** Human-readable description of this path's role in the workflow. */
    description?: string;
    /** Whether this path is required. If true (default), preflight fails if it doesn't exist. */
    required?: boolean;
}
/** Configuration for workflow trajectory recording. */
export interface TrajectoryConfig {
    /** Enable trajectory recording (default: true). */
    enabled?: boolean;
    /** Auto-reflect when barriers resolve (default: true). */
    reflectOnBarriers?: boolean;
    /** Auto-reflect when parallel tracks converge (default: true). */
    reflectOnConverge?: boolean;
    /** Record retry/skip/fail decisions automatically (default: true). */
    autoDecisions?: boolean;
}
/** Configuration for idle agent detection and nudging. */
export interface IdleNudgeConfig {
    /** ms after idle detection before first nudge (default: 120_000 = 2 min). */
    nudgeAfterMs?: number;
    /** ms after nudge before force-release (default: 120_000 = 2 min). */
    escalateAfterMs?: number;
    /** Max nudges before escalation (default: 1). */
    maxNudges?: number;
}
/** Swarm-level settings controlling the overall pattern. */
export interface SwarmConfig {
    pattern: SwarmPattern;
    maxConcurrency?: number;
    timeoutMs?: number;
    channel?: string;
    /** Idle agent detection and nudging configuration for interactive agents. */
    idleNudge?: IdleNudgeConfig;
}
export type SwarmPattern = 'fan-out' | 'pipeline' | 'hub-spoke' | 'consensus' | 'mesh' | 'handoff' | 'cascade' | 'dag' | 'debate' | 'hierarchical' | 'map-reduce' | 'scatter-gather' | 'supervisor' | 'reflection' | 'red-team' | 'verifier' | 'auction' | 'escalation' | 'saga' | 'circuit-breaker' | 'blackboard' | 'swarm' | 'competitive' | 'review-loop';
export type AgentPreset = 'lead' | 'worker' | 'reviewer' | 'analyst';
/** Definition of an agent participating in a workflow. */
export interface AgentDefinition {
    name: string;
    cli: AgentCli;
    role?: string;
    task?: string;
    channels?: string[];
    constraints?: AgentConstraints;
    /** When false, the agent runs as a non-interactive subprocess (no PTY, no relay messaging).
     *  It receives its task as a CLI prompt argument and returns stdout as output.
     *  Default: true (interactive PTY mode). */
    interactive?: boolean;
    /** Working directory for this agent, resolved relative to the YAML file. */
    cwd?: string;
    /** Sets this agent's working directory to a named entry from the top-level `paths` array.
     *  Mutually exclusive with `cwd`. If omitted, the agent runs in the runner's
     *  working directory (the directory containing the workflow YAML file). */
    workdir?: string;
    /** Additional paths the agent needs read/write access to. */
    additionalPaths?: string[];
    /**
     * Role preset that automatically configures interactive mode and injects
     * appropriate task guardrails. Overrides are still accepted.
     *   lead     → interactive PTY, relay-aware, coordinates workers via channels
     *   worker   → interactive: false, produces structured output, no sub-agents
     *   reviewer → interactive: false, reads artifacts, produces verdict, no sub-agents
     *   analyst  → interactive: false, reads code/files, writes findings, no sub-agents
     */
    preset?: AgentPreset;
}
export type AgentCli = 'claude' | 'codex' | 'gemini' | 'aider' | 'goose' | 'opencode' | 'droid' | 'cursor' | 'cursor-agent' | 'agent';
/** Resource and behavioral constraints for an agent. */
export interface AgentConstraints {
    maxTokens?: number;
    timeoutMs?: number;
    retries?: number;
    model?: string;
    /** Silence duration in seconds before the agent is considered idle (0 = disabled, default: 30). */
    idleThresholdSecs?: number;
}
/** Preflight check that runs before any workflow steps. */
export interface PreflightCheck {
    /** Shell command to execute. */
    command: string;
    /** Fail if output matches this condition: "non-empty", "empty", or a regex pattern. */
    failIf?: 'non-empty' | 'empty' | string;
    /** Succeed only if output matches this condition. */
    successIf?: string;
    /** Human-readable description of what this check validates. */
    description?: string;
}
/** A named workflow composed of sequential or parallel steps. */
export interface WorkflowDefinition {
    name: string;
    description?: string;
    /** Preflight checks that run before any steps. All must pass. */
    preflight?: PreflightCheck[];
    steps: WorkflowStep[];
    onError?: 'fail' | 'skip' | 'retry';
}
/** Step type: agent (LLM-powered), deterministic (shell command), or worktree (git worktree setup). */
export type WorkflowStepType = 'agent' | 'deterministic' | 'worktree';
/** Parameter definition for a custom step. */
export interface CustomStepParam {
    /** Parameter name. */
    name: string;
    /** Whether this parameter is required. Default: false. */
    required?: boolean;
    /** Default value if not provided. */
    default?: string;
    /** Human-readable description of the parameter. */
    description?: string;
}
/** A reusable custom step definition stored in .relay/steps.yaml. */
export interface CustomStepDefinition {
    /** Parameters that can be passed when using this step. */
    params?: CustomStepParam[];
    /** Step type: "deterministic" or "worktree". */
    type?: 'deterministic' | 'worktree';
    /** Shell command to execute (for deterministic steps). Supports {{param}} interpolation. */
    command?: string;
    /** Branch name (for worktree steps). Supports {{param}} interpolation. */
    branch?: string;
    /** Base branch (for worktree steps). */
    baseBranch?: string;
    /** Worktree path (for worktree steps). */
    path?: string;
    /** Create branch if missing (for worktree steps). */
    createBranch?: boolean;
    /** Fail if command exit code is non-zero. Default: true. */
    failOnError?: boolean;
    /** Capture stdout as step output. Default: true. */
    captureOutput?: boolean;
    /** Timeout in milliseconds. */
    timeoutMs?: number;
    /** Human-readable description of this step. */
    description?: string;
}
/** Configuration file for custom step definitions (.relay/steps.yaml). */
export interface CustomStepsConfig {
    /** Map of step name to step definition. */
    steps: Record<string, CustomStepDefinition>;
}
/**
 * A single step within a workflow.
 *
 * Steps can be either:
 * - Agent steps (type: undefined or "agent"): Spawn an LLM agent to execute a task
 * - Deterministic steps (type: "deterministic"): Execute a shell command
 */
export interface WorkflowStep {
    /** Unique step name within the workflow. */
    name: string;
    /** Step type: "agent" (default) or "deterministic". */
    type?: WorkflowStepType;
    /** Reference to a custom step definition from .relay/steps.yaml. */
    use?: string;
    /** Step names that must complete before this step runs. */
    dependsOn?: string[];
    /** Timeout in milliseconds. */
    timeoutMs?: number;
    /** Name of the agent to execute this step (required for agent steps). */
    agent?: string;
    /** Task description for the agent (required for agent steps). */
    task?: string;
    /** Verification check to validate step output. */
    verification?: VerificationCheck;
    /** Number of retry attempts on failure. */
    retries?: number;
    /** Maximum iterations for steps that may need to retry (e.g., fix-failures). */
    maxIterations?: number;
    /** Shell command to execute (required for deterministic steps). */
    command?: string;
    /** Sets this step's working directory to a named entry from the top-level `paths` array.
     *  If omitted, the step inherits the agent's workdir, or falls back to the runner's
     *  working directory. */
    workdir?: string;
    /** Fail if command exit code is non-zero. Default: true. */
    failOnError?: boolean;
    /** Capture stdout as step output for downstream steps. Default: true. */
    captureOutput?: boolean;
    /** Branch name for the worktree (required for worktree steps). */
    branch?: string;
    /** Base branch to create the worktree from. Default: HEAD. */
    baseBranch?: string;
    /** Explicit path for the worktree. Default: .worktrees/<step-name>. */
    path?: string;
    /** Create the branch if it doesn't exist. Default: true. */
    createBranch?: boolean;
}
/** Type guard: Check if a step is a deterministic (shell command) step. */
export declare function isDeterministicStep(step: WorkflowStep): boolean;
/** Type guard: Check if a step is a worktree (git worktree setup) step. */
export declare function isWorktreeStep(step: WorkflowStep): boolean;
/** Type guard: Check if a step uses a custom step definition. */
export declare function isCustomStep(step: WorkflowStep): boolean;
/** Type guard: Check if a step is an agent (LLM-powered) step. */
export declare function isAgentStep(step: WorkflowStep): boolean;
export type AgentWorkflowStep = WorkflowStep;
export type DeterministicWorkflowStep = WorkflowStep;
/** Verification check to validate a step's output. */
export interface VerificationCheck {
    type: 'output_contains' | 'exit_code' | 'file_exists' | 'custom';
    value: string;
    description?: string;
}
/** Coordination settings for multi-agent synchronization. */
export interface CoordinationConfig {
    barriers?: Barrier[];
    votingThreshold?: number;
    consensusStrategy?: 'majority' | 'unanimous' | 'quorum';
}
/** A synchronization barrier that gates downstream work. */
export interface Barrier {
    name: string;
    waitFor: string[];
    timeoutMs?: number;
}
/** Shared state configuration for workflows. */
export interface StateConfig {
    backend: 'memory' | 'redis' | 'database';
    ttlMs?: number;
    namespace?: string;
}
/** Global error handling configuration. */
export interface ErrorHandlingConfig {
    strategy: 'fail-fast' | 'continue' | 'retry';
    maxRetries?: number;
    retryDelayMs?: number;
    notifyChannel?: string;
}
/** A single execution wave in a dry-run simulation. */
export interface DryRunWave {
    wave: number;
    /** Steps in this wave. Agent is undefined for deterministic steps. */
    steps: Array<{
        name: string;
        agent?: string;
        dependsOn: string[];
    }>;
}
/** Report produced by a dry-run validation of a workflow config. */
export interface DryRunReport {
    valid: boolean;
    errors: string[];
    warnings: string[];
    name: string;
    description?: string;
    pattern: string;
    agents: Array<{
        name: string;
        cli: string;
        role?: string;
        cwd?: string;
        stepCount: number;
    }>;
    waves: DryRunWave[];
    totalSteps: number;
    maxConcurrency?: number;
    estimatedWaves: number;
    /** Estimated peak concurrent agents. */
    estimatedPeakConcurrency?: number;
    /** Estimated total agent-steps (counting retries as additional steps). */
    estimatedTotalAgentSteps?: number;
}
export type WorkflowRunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
/** Database row representing a workflow run. */
export interface WorkflowRunRow {
    id: string;
    workspaceId: string;
    workflowName: string;
    pattern: SwarmPattern;
    status: WorkflowRunStatus;
    config: RelayYamlConfig;
    stateSnapshot?: Record<string, unknown>;
    startedAt: string;
    completedAt?: string;
    error?: string;
    createdAt: string;
    updatedAt: string;
}
export type WorkflowStepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
/** Database row representing a single workflow step execution. */
export interface WorkflowStepRow {
    id: string;
    runId: string;
    stepName: string;
    /** Agent name for agent steps, null for deterministic/worktree steps. */
    agentName: string | null;
    /** Step type: agent, deterministic, or worktree. */
    stepType: WorkflowStepType;
    status: WorkflowStepStatus;
    /** Task description for agent steps, command for deterministic steps, branch for worktree steps. */
    task: string;
    dependsOn: string[];
    output?: string;
    error?: string;
    startedAt?: string;
    completedAt?: string;
    retryCount: number;
    createdAt: string;
    updatedAt: string;
}
//# sourceMappingURL=types.d.ts.map