/**
 * AgentRouter Type Definitions
 *
 * Core type definitions for the AgentRouter MCP server.
 * These types define the data structures for configuration, agents,
 * messages, providers, and MCP tools.
 */
/**
 * Root configuration object for AgentRouter.
 * Loaded from YAML config file with environment variable interpolation.
 */
export interface Config {
    /** Configuration schema version (e.g., "1.0") */
    version: string;
    /** Default values applied to all roles unless overridden */
    defaults: DefaultConfig;
    /** Role definitions mapping role names to their configurations */
    roles: Record<string, RoleConfig>;
    /** Provider configurations mapping provider names to their settings */
    providers: Record<string, ProviderConfig>;
}
/**
 * Default configuration values applied to all roles.
 * Individual roles can override these values.
 */
export interface DefaultConfig {
    /** Default temperature for LLM requests (0-2) */
    temperature: number;
    /** Default maximum tokens for LLM responses */
    max_tokens: number;
    /** Default timeout in milliseconds for LLM requests */
    timeout_ms: number;
    /** Global failover configuration */
    failover?: {
        /** Enable automatic failover (default: true) */
        enabled?: boolean;
        /** Maximum total retries across all providers (default: 6) */
        max_total_retries?: number;
        /** Health check interval in ms (default: 60000) */
        health_check_interval_ms?: number;
        /** Cooldown period in ms before retrying unhealthy provider (default: 300000) */
        cooldown_ms?: number;
        /** Use cheapest healthy provider when no preference specified */
        prefer_cost_efficient?: boolean;
    };
}
/**
 * Configuration for a specific agent role.
 * Defines the provider, model, and optional overrides for a role.
 */
export interface RoleConfig {
    /** Provider name (must match a key in config.providers) */
    provider: string;
    /** Model identifier to use with the provider */
    model: string;
    /** System prompt / persona for this role */
    system_prompt?: string;
    /** Temperature override for this role (0-2) */
    temperature?: number;
    /** Max tokens override for this role */
    max_tokens?: number;
    /** Timeout override in milliseconds for this role */
    timeout_ms?: number;
    /** Fallback configuration if primary provider fails */
    fallback?: FallbackConfig;
    /** Extended fallback chain configuration for multiple fallbacks */
    fallback_chain?: FallbackChainConfig;
    /** Whether this role needs an isolated git worktree for file modifications */
    needs_worktree?: boolean;
}
/**
 * Fallback provider configuration.
 * Used when the primary provider fails or is unavailable.
 */
export interface FallbackConfig {
    /** Fallback provider name */
    provider: string;
    /** Fallback model identifier */
    model: string;
}
/**
 * Extended fallback chain configuration.
 * Allows multiple fallback providers with retry and health check settings.
 */
export interface FallbackChainConfig {
    /** Ordered list of fallback providers to try on failure */
    providers: Array<{
        provider: string;
        model: string;
    }>;
    /** HTTP status codes that trigger failover (default: [429, 500, 502, 503, 504]) */
    on_errors?: number[];
    /** Retry configuration for transient failures */
    retry?: {
        /** Maximum retry attempts before trying next provider (default: 2) */
        max_attempts?: number;
        /** Initial delay in ms before first retry (default: 1000) */
        initial_delay_ms?: number;
        /** Maximum delay in ms between retries (default: 30000) */
        max_delay_ms?: number;
        /** Backoff strategy: 'immediate' | 'linear' | 'exponential' (default: 'exponential') */
        strategy?: 'immediate' | 'linear' | 'exponential';
    };
    /** How often to check if unhealthy providers have recovered, in ms (default: 60000) */
    health_check_interval_ms?: number;
    /** How long to wait before retrying an unhealthy provider, in ms (default: 300000) */
    cooldown_ms?: number;
}
/**
 * Access mode for Anthropic provider.
 * - 'api': Direct HTTP calls to Anthropic API
 * - 'session': Returns delegation response for current Claude session (recommended for Claude Code)
 * - 'auto': Auto-detect best method based on environment
 * - 'subscription': Legacy subprocess mode via Agent SDK (deprecated)
 */
export type AccessMode = 'api' | 'session' | 'auto' | 'subscription';
/**
 * Provider-specific configuration.
 * Contains credentials and settings for connecting to an LLM provider.
 */
export interface ProviderConfig {
    /** Access mode: "api", "session", "auto", or "subscription" (deprecated) - see AccessMode type */
    access_mode?: AccessMode;
    /** API key for authentication (supports ${ENV_VAR} interpolation) */
    api_key?: string;
    /** Base URL for the provider API (for self-hosted or proxy setups) */
    base_url?: string;
    /** Default model for this provider */
    default_model?: string;
    /** Organization ID (OpenAI) */
    organization?: string;
    /** Project ID (Google Cloud / Vertex AI) */
    project?: string;
    /** Region/location (Google Cloud / Vertex AI) */
    location?: string;
    /** Additional headers to include in API requests */
    headers?: Record<string, string>;
    /** System prompt for session delegation mode (injected by role resolver) */
    system_prompt?: string;
    /** Role name for session delegation mode (injected by role resolver) */
    role_name?: string;
}
/**
 * Predefined agent roles.
 * These represent specialized AI agents with specific capabilities.
 */
export type AgentRole = 'coder' | 'critic' | 'designer' | 'researcher' | 'reviewer';
/**
 * Resolved agent configuration.
 * Created by merging role config with defaults.
 * All optional fields from RoleConfig become required here.
 */
export interface AgentConfig {
    /** Provider name */
    provider: string;
    /** Model identifier */
    model: string;
    /** System prompt / persona */
    system_prompt?: string;
    /** Temperature (always resolved, never undefined) */
    temperature: number;
    /** Max tokens (always resolved, never undefined) */
    max_tokens: number;
    /** Timeout in milliseconds (always resolved, never undefined) */
    timeout_ms: number;
    /** Fallback configuration if available */
    fallback?: FallbackConfig;
}
/**
 * Input parameters for invoking an agent.
 */
export interface InvokeAgentInput {
    /** Role name of the agent to invoke */
    role: string;
    /** Task description or question for the agent */
    task: string;
    /** Optional additional context from the conversation */
    context?: string;
    /** Optional tools to make available to the agent */
    tools?: Tool[];
}
/**
 * Response from an agent invocation.
 */
export interface AgentResponse {
    /** Role that was invoked */
    role: string;
    /** Provider that handled the request */
    provider: string;
    /** Model that generated the response */
    model: string;
    /** Response content blocks */
    content: ContentBlock[];
    /** Token usage information */
    usage?: UsageInfo;
    /** Request metadata */
    metadata: {
        /** Unique trace ID for this request */
        traceId: string;
        /** Total duration in milliseconds */
        durationMs: number;
    };
}
/**
 * Response returned when using session delegation mode.
 * Instead of making an API call or spawning a subprocess,
 * the MCP tool returns instructions for the current Claude
 * session to handle the request directly.
 */
export interface SessionDelegationResponse {
    /** Marker that this is a delegation, not a completion */
    delegation: true;
    /** The role being delegated (e.g., "orchestrator", "reviewer") */
    role: string;
    /** The system prompt for the role (from config) */
    system_prompt: string;
    /** The original task to execute */
    task: string;
    /** Optional context from the caller */
    context?: string;
    /** Human-readable instructions for the current session */
    instructions: string;
    /** The model that was requested (for reference) */
    model?: string;
}
/**
 * Type guard to check if a response is a session delegation
 */
export declare function isSessionDelegation(response: unknown): response is SessionDelegationResponse;
/**
 * Chat message in the conversation.
 * Used for building request messages to providers.
 */
export interface Message {
    /** Message role: user or assistant */
    role: 'user' | 'assistant';
    /** Message content (string or content blocks) */
    content: string | ContentBlock[];
}
/**
 * Content block within a message.
 * Supports text, tool use requests, and tool results.
 */
export interface ContentBlock {
    /** Type of content block */
    type: 'text' | 'tool_use' | 'tool_result';
    /** Text content (for type: "text") */
    text?: string;
    /** Tool use ID (for type: "tool_use") */
    id?: string;
    /** Tool name (for type: "tool_use") */
    name?: string;
    /** Tool input parameters (for type: "tool_use") */
    input?: Record<string, unknown>;
    /** Reference to tool_use ID (for type: "tool_result") */
    tool_use_id?: string;
    /** Tool result content (for type: "tool_result") */
    content?: string;
}
/**
 * Tool definition for agent tool use.
 * Follows the Anthropic tool schema format.
 */
export interface Tool {
    /** Tool name (must be unique within a request) */
    name: string;
    /** Human-readable description of what the tool does */
    description: string;
    /** JSON Schema for the tool's input parameters */
    input_schema: {
        type: 'object';
        properties: Record<string, unknown>;
        required?: string[];
    };
}
/**
 * Supported LLM provider types.
 */
export type ProviderType = 'anthropic' | 'openai' | 'google' | 'deepseek' | 'zai' | 'kimi' | 'kimi-code' | 'ollama' | 'openrouter' | 'perplexity' | 'groq' | 'together' | 'fireworks';
/**
 * Request to complete a conversation.
 * Sent to providers after translation.
 */
export interface CompletionRequest {
    /** Model identifier */
    model: string;
    /** Conversation messages */
    messages: Message[];
    /** Temperature for response generation (0-2) */
    temperature?: number;
    /** Maximum tokens to generate */
    max_tokens?: number;
    /** Timeout in milliseconds for this request */
    timeout_ms?: number;
    /** Tools available for the model to use */
    tools?: Tool[];
    /** Whether to stream the response */
    stream?: boolean;
}
/**
 * Response from a completion request.
 * Normalized format returned by all providers.
 */
export interface CompletionResponse {
    /** Unique response ID from the provider */
    id: string;
    /** Response content blocks */
    content: ContentBlock[];
    /** Model that generated the response */
    model: string;
    /** Reason the generation stopped (e.g., "end_turn", "tool_use") */
    stop_reason: string;
    /** Token usage information */
    usage?: UsageInfo;
}
/**
 * Token usage information for a request/response.
 */
export interface UsageInfo {
    /** Number of tokens in the input/prompt */
    input_tokens: number;
    /** Number of tokens in the output/completion */
    output_tokens: number;
    /** Tokens used to create prompt cache (Anthropic) */
    cache_creation_input_tokens?: number;
    /** Tokens read from prompt cache (Anthropic) */
    cache_read_input_tokens?: number;
}
/**
 * Provider interface that all provider adapters must implement.
 */
export interface Provider {
    /** Provider name identifier */
    name: string;
    /** Execute a completion request and return the full response (or session delegation) */
    complete(request: CompletionRequest): Promise<CompletionResponse | SessionDelegationResponse>;
    /** Execute a streaming completion request */
    completeStream(request: CompletionRequest): AsyncIterable<StreamChunk>;
    /** Check if the provider is available and configured correctly */
    healthCheck(): Promise<void>;
}
/**
 * Chunk of a streaming response.
 */
export interface StreamChunk {
    /** Type of streaming event */
    type: 'content_block_start' | 'content_block_delta' | 'message_stop';
    /** Index of the content block (for multi-block responses) */
    index?: number;
    /** Content block being started (for content_block_start) */
    content_block?: ContentBlock;
    /** Delta update to content (for content_block_delta) */
    delta?: {
        type: string;
        text?: string;
    };
}
/**
 * Input schema for the invoke_agent MCP tool.
 */
export interface InvokeAgentToolInput {
    /** The agent role to invoke */
    role: AgentRole | string;
    /** The task description or question for the agent */
    task: string;
    /** Optional additional context from the current conversation */
    context?: string;
}
/**
 * Input schema for the compare_agents MCP tool.
 */
export interface CompareAgentsToolInput {
    /** List of role names to compare */
    roles: string[];
    /** The task to send to all agents */
    task: string;
}
/**
 * Input schema for the critique_plan MCP tool.
 * Shorthand for invoking the critic role.
 */
export interface CritiquePlanToolInput {
    /** The plan or PRD to critique */
    plan: string;
}
/**
 * Input schema for the review_code MCP tool.
 * Shorthand for invoking the reviewer role.
 */
export interface ReviewCodeToolInput {
    /** The code to review */
    code: string;
    /** Optional context about the code (language, purpose, etc.) */
    context?: string;
}
/**
 * Input schema for the design_feedback MCP tool.
 * Shorthand for invoking the designer role.
 */
export interface DesignFeedbackToolInput {
    /** The design to review (description, wireframe, mockup) */
    design: string;
}
/**
 * Output schema for the list_agents MCP tool.
 */
export interface ListAgentsToolOutput {
    /** List of available agent roles */
    roles: {
        /** Role name */
        name: string;
        /** Provider configured for this role */
        provider: string;
        /** Model configured for this role */
        model: string;
        /** Whether a fallback is configured */
        hasFallback: boolean;
    }[];
}
/**
 * Base error class for AgentRouter errors.
 */
export declare class AgentRouterError extends Error {
    readonly code: string;
    constructor(message: string, code: string, cause?: Error);
}
/**
 * Error thrown when configuration is invalid.
 */
export declare class ConfigurationError extends AgentRouterError {
    constructor(message: string, cause?: Error);
}
/**
 * Error thrown when a provider API call fails.
 */
export declare class ProviderError extends AgentRouterError {
    readonly provider: string;
    readonly statusCode?: number | undefined;
    constructor(message: string, provider: string, statusCode?: number | undefined, cause?: Error);
}
/**
 * Error thrown when hitting rate limits.
 */
export declare class RateLimitError extends ProviderError {
    readonly retryAfterMs?: number | undefined;
    constructor(provider: string, retryAfterMs?: number | undefined, cause?: Error);
}
/**
 * Error thrown when authentication fails.
 */
export declare class AuthenticationError extends ProviderError {
    constructor(provider: string, cause?: Error);
}
/**
 * Error thrown when a request times out.
 */
export declare class TimeoutError extends ProviderError {
    constructor(provider: string, timeoutMs: number, cause?: Error);
}
/**
 * Error thrown when all providers in a failover chain fail.
 */
export declare class FailoverExhaustedError extends ProviderError {
    readonly attemptedProviders: string[];
    readonly errors: Map<string, Error>;
    constructor(role: string, attemptedProviders: string[], errors: Map<string, Error>, cause?: Error);
}
/**
 * Error thrown when message/tool translation fails.
 */
export declare class TranslationError extends AgentRouterError {
    readonly sourceFormat: string;
    readonly targetFormat: string;
    constructor(message: string, sourceFormat: string, targetFormat: string, cause?: Error);
}
/**
 * Execution state for a task being processed by AgentRouter.
 */
export interface TaskExecution {
    /** Claude Code task ID */
    taskId: string;
    /** Agent role used for execution */
    role: string;
    /** Unique trace ID for this execution */
    traceId: string;
    /** Execution start timestamp */
    startTime: number;
    /** Execution end timestamp (set on completion/failure) */
    endTime?: number;
    /** Current execution status */
    status: 'running' | 'completed' | 'failed';
    /** Agent response on success */
    result?: AgentResponse;
    /** Error details on failure */
    error?: Error;
}
/**
 * Instructions for Claude to execute task lifecycle operations.
 * MCP tools cannot directly call Claude Code tools, so they return
 * instruction strings that Claude must execute.
 */
export interface ClaimInstructions {
    /** Instruction to claim the task before execution */
    preExecution: string;
    /** Instruction to mark task complete on success */
    onSuccess: string;
    /** Instruction to release task on failure */
    onFailure: string;
}
/**
 * Result of completing a task execution.
 */
export interface CompletionResult {
    /** The execution record */
    execution: TaskExecution;
    /** Instruction for Claude to mark task complete */
    instructions: string;
    /** Agent response */
    result: AgentResponse;
}
/**
 * Result of a failed task execution.
 */
export interface FailureResult {
    /** The execution record */
    execution: TaskExecution;
    /** Instruction for Claude to release the task */
    instructions: string;
    /** Error that caused the failure */
    error: Error;
}
/**
 * A step in a multi-provider pipeline.
 */
export interface PipelineStep {
    /** Unique step identifier within the pipeline */
    name: string;
    /** Task subject line (imperative form) */
    subject: string;
    /** Detailed task description */
    description?: string;
    /** AgentRouter role for execution */
    role: AgentRole | string;
    /** Names of steps this step depends on */
    dependsOn?: string[];
    /** Additional context for this step's agent */
    context?: string;
}
/**
 * Definition of a multi-step task pipeline.
 */
export interface PipelineDefinition {
    /** Pipeline name for identification */
    name: string;
    /** Pipeline steps in declaration order */
    steps: PipelineStep[];
    /** Context passed to all steps */
    globalContext?: string;
}
/**
 * Execution state for a pipeline.
 */
export interface PipelineExecution {
    /** Unique pipeline execution ID */
    pipelineId: string;
    /** Pipeline definition */
    definition: PipelineDefinition;
    /** Mapping from step name to Claude Code task ID */
    taskIdMap: Map<string, string>;
    /** Overall pipeline status */
    status: 'pending' | 'running' | 'completed' | 'failed';
    /** Pipeline start timestamp */
    startTime: number;
    /** Set of completed step names */
    completedSteps: Set<string>;
    /** Results from completed steps */
    results: Map<string, AgentResponse>;
}
/**
 * Configuration for a background worker.
 */
export interface WorkerConfig {
    /** Worker name for identification and ownership */
    name: string;
    /** Only claim tasks for these roles (empty = any) */
    allowedRoles?: AgentRole[];
    /** Maximum concurrent task executions (default: 1) */
    maxConcurrent?: number;
    /** Heartbeat interval in ms (default: 30000) */
    heartbeatMs?: number;
    /** Shutdown after idle for this duration in ms (default: 300000) */
    idleTimeoutMs?: number;
}
/**
 * Current state of a background worker.
 */
export interface WorkerState {
    /** Worker name */
    name: string;
    /** Current worker status */
    status: 'idle' | 'working' | 'shutdown';
    /** Currently executing task ID (if working) */
    currentTask?: string;
    /** Count of successfully completed tasks */
    completedCount: number;
    /** Count of failed task attempts */
    failedCount: number;
    /** Last heartbeat timestamp */
    lastHeartbeat: number;
    /** Task IDs to exclude from claiming (failed attempts) */
    excludeTaskIds?: string[];
}
/**
 * Configuration for the tasks integration feature.
 */
export interface TasksConfig {
    /** Enable task-aware tools */
    enabled: boolean;
    /** Default behavior settings */
    defaults: {
        /** Automatically mark tasks complete on success */
        autoComplete: boolean;
        /** Automatically release tasks on failure */
        autoRelease: boolean;
        /** Maximum execution time per task in ms */
        timeoutMs: number;
    };
    /** Worker mode settings */
    worker: {
        /** Heartbeat interval in ms */
        heartbeatMs: number;
        /** Shutdown after idle for this duration in ms */
        idleTimeoutMs: number;
        /** Maximum retry attempts for failed tasks */
        maxRetries: number;
    };
    /** Pipeline settings */
    pipeline: {
        /** Maximum concurrent pipeline steps */
        maxParallel: number;
        /** Execute independent steps in parallel by default */
        defaultParallel: boolean;
        /** Maximum context length before truncation */
        maxContextLength: number;
    };
}
export type WorktreeStatus = 'available' | 'assigned' | 'active' | 'completing' | 'conflict' | 'stale';
export interface Worktree {
    id: string;
    path: string;
    branch: string;
    baseBranch: string;
    status: WorktreeStatus;
    taskId?: string;
    agentId?: string;
    createdAt: number;
    lastActivityAt: number;
}
export interface WorktreeInstructions {
    workingDirectory: string;
    branch: string;
    baseBranch: string;
    commitPrefix: string;
    instructions: string;
}
export interface WorktreeConfig {
    enabled: boolean;
    baseDir: string;
    limits: {
        maxWorktrees: number;
        maxDiskBytes: number;
    };
    pool: {
        enabled: boolean;
        size: number;
    };
    git: {
        defaultBaseBranch: string;
        branchPattern: string;
        autoMerge: boolean;
        conflictStrategy: 'merge' | 'rebase' | 'ours' | 'theirs' | 'manual';
    };
    cleanup: {
        staleThresholdMs: number;
        autoCleanup: boolean;
    };
}
export interface TaskExecutionWithWorktree {
    taskId: string;
    role: string;
    status: 'pending' | 'running' | 'completed' | 'failed';
    worktree?: Worktree;
    requiresWorktree: boolean;
    worktreeInstructions?: WorktreeInstructions;
    startedAt?: number;
    completedAt?: number;
    result?: string;
    error?: string;
}
export interface PipelineStepWithWorktree {
    id: string;
    name: string;
    role: string;
    needsWorktree?: boolean;
    autoMerge?: boolean;
    dependsOn?: string[];
}
export interface WorktreeAllocationResult {
    success: boolean;
    worktree?: Worktree;
    instructions?: WorktreeInstructions;
    error?: string;
}
export interface MergeResult {
    success: boolean;
    conflicted: boolean;
    conflictedFiles?: string[];
    mergeCommit?: string;
    error?: string;
}
export interface StepWorktreeAllocation {
    stepId: string;
    worktreeId: string;
    worktreePath: string;
    branch: string;
    status: 'pending' | 'allocated' | 'active' | 'completed' | 'merged' | 'conflict';
    allocatedAt?: number;
    mergedAt?: number;
}
export interface PipelineWorktreeState {
    pipelineId: string;
    stepWorktrees: Map<string, StepWorktreeAllocation>;
    mergeOrder: string[][];
    mergeProgress: {
        phase: 'executing' | 'merging' | 'completed' | 'conflict' | 'failed';
        currentBatch: number;
        mergedSteps: string[];
        conflictedSteps: string[];
    };
}
export interface PipelineMergeResult {
    pipelineId: string;
    success: boolean;
    mergedSteps: Array<{
        stepId: string;
        branch: string;
        mergeCommit?: string;
    }>;
    conflicts: Array<{
        stepId: string;
        branch: string;
        conflictedFiles: string[];
        error?: string;
    }>;
    completedAt: number;
}
export interface PipelineWorktreeConfig {
    enabled: boolean;
    autoMerge: boolean;
    mergeStrategy: 'sequential' | 'parallel-safe';
    conflictResolution: 'halt' | 'skip' | 'manual';
    cleanupOnSuccess: boolean;
    preserveOnConflict: boolean;
}
export type ConflictResolutionStrategy = 'ours' | 'theirs' | 'auto' | 'manual';
export interface ConflictMarker {
    file: string;
    startLine: number;
    endLine: number;
    oursContent: string;
    theirsContent: string;
    oursLabel: string;
    theirsLabel: string;
}
export interface FileConflict {
    file: string;
    conflicts: ConflictMarker[];
    totalConflicts: number;
}
export interface ConflictState {
    taskId: string;
    worktreeId: string;
    detectedAt: number;
    files: FileConflict[];
    totalConflicts: number;
    resolved: boolean;
    resolutionStrategy?: ConflictResolutionStrategy;
    resolvedAt?: number;
}
export interface ConflictResolutionResult {
    success: boolean;
    strategy: ConflictResolutionStrategy;
    resolvedFiles: string[];
    remainingConflicts: FileConflict[];
    error?: string;
}
export interface ManualResolution {
    file: string;
    resolvedContent: string;
}
export interface ResourceLimits {
    maxWorktrees: number;
    maxDiskMB: number;
    cleanupThresholdMB: number;
    maxIdleTimeMs: number;
}
export interface ResourceUsage {
    currentWorktrees: number;
    availableSlots: number;
    diskUsageMB: number;
    oldestWorktreeAge: number;
}
export interface WorktreeMetrics {
    id: string;
    path: string;
    branch: string;
    status: WorktreeStatus;
    taskId?: string;
    createdAt: number;
    lastActivityAt: number;
    diskUsageMB?: number;
}
export interface ResourceReport {
    usage: ResourceUsage;
    limits: ResourceLimits;
    worktrees: WorktreeMetrics[];
    staleCount: number;
    shouldCleanup: boolean;
}
//# sourceMappingURL=types.d.ts.map