Types

Complete TypeScript type definitions exported by @autowright/fixwright.

Import

import type {
  ResolvedAiFixConfig,
  AiConfig,
  GitConfig,
  GitHubConfig,
  ValidationConfig,
  FixingConfig,
  FixAttempt,
  FixAttemptStatus,
  FailureAnalysis,
  ProposedFix,
  ValidationResult,
  VerbosityLevel,
} from '@autowright/fixwright';

// FailureCase comes from shared package
import type { FailureCase } from '@autowright/shared';

Configuration Types

ResolvedAiFixConfig

Full configuration interface for FixingLoop.

interface ResolvedAiFixConfig {
  /** Claude Agent SDK configuration */
  ai: AiConfig;

  /** Git configuration */
  git: GitConfig;

  /** GitHub configuration for PR creation */
  github?: GitHubConfig;

  /** Validation configuration */
  validation: ValidationConfig;

  /** Fixing loop configuration */
  fixing: FixingConfig;

  /** Working directory */
  workDir: string;

  /** Verbosity level */
  verbosity?: VerbosityLevel;
}

AiConfig (Claude Agent SDK)

Configuration for the Claude Agent SDK.

interface AiConfig {
  // Required
  apiKey: string;                    // Anthropic API key

  // Model Selection
  model?: string;                    // Default: 'claude-sonnet-4-20250514'
  fallbackModel?: string;            // Fallback if primary fails

  // Token Limits
  maxTokens?: number;                // Max tokens for responses
  maxThinkingTokens?: number;        // Max tokens for thinking
  maxTurns?: number;                 // Max agent turns (default: 20)

  // Budget Control
  maxBudgetUsd?: number;             // Max budget in USD

  // Temperature
  temperature?: number;              // 0-1, controls randomness

  // Permissions
  permissionMode?: PermissionMode;   // Tool permission handling
  allowDangerouslySkipPermissions?: boolean;

  // Tools
  allowedTools?: string[];           // Allowed tool names
  disallowedTools?: string[];        // Blocked tool names
  tools?: string[] | { type: 'preset'; preset: 'claude_code' };

  // System Prompt
  systemPrompt?: string | {
    type: 'preset';
    preset: 'claude_code';
    append?: string;
  };

  // MCP Servers
  mcpServers?: Record<string, McpServerConfig>;

  // Advanced
  betas?: SdkBeta[];                 // Beta features
  settingSources?: SettingSource[];  // Config sources
  additionalDirectories?: string[];  // Extra accessible dirs
  env?: Record<string, string>;      // Environment variables
  executable?: JsRuntime;            // 'node' | 'bun' | 'deno'
  executableArgs?: string[];         // Runtime arguments

  // Streaming
  includePartialMessages?: boolean;  // Stream partial messages
  enableFileCheckpointing?: boolean; // Track file changes

  // Callbacks
  stderr?: (data: string) => void;   // stderr handler
  canUseTool?: ToolPermissionFn;     // Custom tool filtering
}

PermissionMode

Permission modes for tool execution.

type PermissionMode =
  | 'default'           // Ask for permission on sensitive ops
  | 'acceptEdits'       // Auto-accept file edits
  | 'bypassPermissions' // Skip all permission checks
  | 'plan';             // Planning mode only

McpServerConfig

MCP server configuration types.

type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig;

interface McpStdioServerConfig {
  type?: 'stdio';
  command: string;
  args?: string[];
  env?: Record<string, string>;
}

interface McpSSEServerConfig {
  type: 'sse';
  url: string;
  headers?: Record<string, string>;
}

interface McpHttpServerConfig {
  type: 'http';
  url: string;
  headers?: Record<string, string>;
}

GitConfig

Git configuration.

interface GitConfig {
  baseBranch: string;           // e.g., 'main'
  fixBranchPrefix: string;      // e.g., 'fix/stepwright-'
  commitAuthor?: {
    name: string;
    email: string;
  };
}

GitHubConfig

GitHub configuration for PR creation.

interface GitHubConfig {
  token: string;    // GitHub PAT
  owner: string;    // Repository owner
  repo: string;     // Repository name
}

ValidationConfig

Validation configuration.

interface ValidationConfig {
  stepwrightPath: string;  // Path to stepwright CLI (e.g., 'npx stepwright')
  timeout?: number;        // Validation timeout (ms)
  retries?: number;        // Max validation retries
}

FixingConfig

Fixing loop configuration.

interface FixingConfig {
  maxAttempts: number;          // Max fix attempts per failure
  maxRetriesPerAttempt: number; // Max retries within attempt
  cooldownMs?: number;          // Delay between attempts
}

VerbosityLevel

Output verbosity levels.

type VerbosityLevel = 'quiet' | 'normal' | 'verbose';

DEFAULT_CONFIG

Default configuration values.

const DEFAULT_CONFIG = {
  git: {
    baseBranch: 'main',
    fixBranchPrefix: 'fix/stepwright-',
  },
  validation: {
    stepwrightPath: 'npx stepwright',
    timeout: 120000,
    retries: 2,
  },
  fixing: {
    maxAttempts: 3,
    maxRetriesPerAttempt: 2,
    cooldownMs: 1000,
  },
  verbosity: 'normal',
};

Fix Attempt Types

FixAttempt

Represents a single fix attempt.

interface FixAttempt {
  /** Unique attempt ID */
  id: string;

  /** Parent failure case ID */
  failureCaseId: string;

  /** Attempt number (1-based) */
  attemptNumber: number;

  /** Current status */
  status: FixAttemptStatus;

  /** When the attempt started */
  startedAt: Date;

  /** When the attempt completed */
  completedAt?: Date;

  /** Analysis of the failure */
  analysis?: FailureAnalysis;

  /** Proposed fix */
  proposedFix?: ProposedFix;

  /** Validation result */
  validationResult?: ValidationResult;

  /** Error message if failed */
  error?: string;
}

FixAttemptStatus

Possible attempt statuses.

type FixAttemptStatus =
  | 'pending'
  | 'analyzing'
  | 'fixing'
  | 'validating'
  | 'success'
  | 'failed'
  | 'regression'
  | 'new_error';

FailureAnalysis

Analysis result from Claude.

interface FailureAnalysis {
  /** Identified cause type */
  causeType:
    | 'selector_changed'
    | 'timing_issue'
    | 'page_flow_change'
    | 'element_state'
    | 'api_change'
    | 'unknown';

  /** Explanation of the cause */
  explanation: string;

  /** Suggested approach to fix */
  suggestedApproach: string;

  /** Confidence score (0-1) */
  confidence: number;
}

ProposedFix

Proposed code fix.

interface ProposedFix {
  /** File path */
  filePath: string;

  /** Original code */
  originalCode: string;

  /** Fixed code */
  fixedCode: string;

  /** Line range affected */
  lineRange: {
    start: number;
    end: number;
  };

  /** Explanation of the fix */
  explanation: string;
}

ValidationResult

Result of validating a fix.

interface ValidationResult {
  /** Whether validation passed */
  success: boolean;

  /** Duration in milliseconds */
  duration: number;

  /** Error if failed */
  error?: string;

  /** Output from validation run */
  output?: string;
}

Agent Types

AgentFixerConfig

Configuration for AgentFixer.

interface AgentFixerConfig {
  model?: string;
  maxTurns?: number;
  timeout?: number;
  verbosity?: VerbosityLevel;
}

AgentFixResult

Result from an agent fix attempt.

interface AgentFixResult {
  success: boolean;
  analysis?: FailureAnalysis;
  proposedFix?: ProposedFix;
  sessionId?: string;
  error?: string;
  totalCostUsd?: number;
  duration?: number;
  edits?: EditInfo[];
}

EditInfo

Information about an edit operation.

interface EditInfo {
  filePath: string;
  oldString: string;
  newString: string;
  timestamp: Date;
}

ReadInfo

Information about a read operation.

interface ReadInfo {
  filePath: string;
  linesRead?: number;
  timestamp: Date;
}

BashInfo

Information about a bash command.

interface BashInfo {
  command: string;
  description?: string;
  timestamp: Date;
}

GrepInfo

Information about a grep search.

interface GrepInfo {
  pattern: string;
  path?: string;
  glob?: string;
  timestamp: Date;
}

GlobInfo

Information about a glob search.

interface GlobInfo {
  pattern: string;
  path?: string;
  timestamp: Date;
}

Event Types

FixingLoopEvents

Events emitted by FixingLoop.

interface FixingLoopEvents {
  // Attempt Lifecycle
  'attempt:start': (attempt: FixAttempt) => void;
  'attempt:analyzing': (attempt: FixAttempt) => void;
  'attempt:fixing': (attempt: FixAttempt) => void;
  'attempt:validating': (attempt: FixAttempt) => void;
  'attempt:success': (attempt: FixAttempt) => void;
  'attempt:failed': (attempt: FixAttempt) => void;
  'attempt:regression': (attempt: FixAttempt) => void;
  'attempt:new_error': (attempt: FixAttempt, newError: string) => void;
  'failure:completed': (summary: FixCompletionSummary) => void;

  // Agent Events
  'agent:message': (message: SDKMessage) => void;
  'agent:error': (error: Error) => void;
  'agent:thinking': (text: string) => void;
  'agent:text': (text: string) => void;
  'agent:tool_use': (toolName: string, input: unknown) => void;
  'agent:read': (info: ReadInfo) => void;
  'agent:edit': (info: EditInfo) => void;
  'agent:bash': (info: BashInfo) => void;
  'agent:grep': (info: GrepInfo) => void;
  'agent:glob': (info: GlobInfo) => void;
  'agent:start': () => void;
  'agent:complete': (result: AgentFixResult) => void;

  // Result Events
  'pr:created': (prUrl: string) => void;
  error: (error: Error) => void;
}

FixCompletionSummary

Summary when a failure case is completed.

interface FixCompletionSummary {
  failureCaseId: string;
  status: 'fixed' | 'unfixable';
  attempts: number;
  totalDuration: number;
  successfulAttempt?: FixAttempt;
  prNumber?: number;
  prUrl?: string;
  reason?: string;
}

Shared Types

FailureCase

From @autowright/shared - the contract between Stepwright and Fixwright.

import type { FailureCase, FailureCaseStatus } from '@autowright/shared';

interface FailureCase {
  id: string;
  status: FailureCaseStatus;
  timestamp: string;
  script: {
    name: string;
    path: string;
    repository?: {
      url: string;
      branch: string;
    };
  };
  failure: {
    step: string;
    checkpoint?: string;
    error: {
      message: string;
      stack?: string;
    };
    artifacts: {
      screenshot?: string;
      dom?: string;
      console?: string;
      trace?: string;  // Playwright trace file
      video?: string;  // Video recording
    };
    url?: string;
    title?: string;
  };
  sourceCode?: {
    content: string;
    lineNumber: number;
    context: string[];
  };
}

type FailureCaseStatus = 'pending' | 'processing' | 'fixed' | 'unfixable';

See Also

• FixingLoop Class - Main class
• AgentFixer - Agent API
• FailureSource - Source API