Configuration Reference

interface SwarmConfig {
  serverUrl: string;
  agentCount: number;
  adapter: GameAdapter;
  tickIntervalMs?: number;
  connectStaggerMs?: number;
  durationMs?: number;
  detectors?: Detector[];
  reporters?: Reporter[];
  behaviorMix?: {
    regression: number;
    llmGenerated: number;
    handwritten: number;
  };
  llm?: {
    model?: string;
    regenerateIntervalMs?: number;
    apiKey?: string;
  };
  treeDir?: string;
  trimAfterRun?: boolean;
  handwrittenTrees?: TreeNode[];
}

type TreeNode =
  | { type: 'sequence'; children: TreeNode[] }
  | { type: 'selector'; children: TreeNode[] }
  | { type: 'repeat'; count: number | 'forever'; child: TreeNode }
  | { type: 'random_selector'; children: TreeNode[]; weights?: number[] }
  | { type: 'action'; name: string; params?: Record<string, unknown> }
  | { type: 'wait'; ticks: number }
  | { type: 'condition'; predicate: string; then: TreeNode; else?: TreeNode }
  | { type: 'probability'; chance: number; child: TreeNode };

interface SavedTree {
  id: string;                    // Unique ID (e.g., "tree-1771647225060-tgbfcs")
  game: string;                  // Game adapter name
  tree: TreeNode;                // The behavior tree definition
  source: 'llm' | 'handwritten' | 'recorded';
  createdAt: string;             // ISO 8601 timestamp
  findings: string[];            // IDs of findings this tree triggered
  actionSequenceHash: string;    // Hash for deduplication
  tags: string[];                // Categories from associated findings
}

interface GameAdapter<TClientMsg = unknown, TServerMsg = unknown, TAgentState = unknown> {
  readonly name: string;

  connect(url: string, agentId: string): Promise<AgentConnection>;
  createConnectMessage(agentId: string, config: AgentConfig): TClientMsg;
  createDisconnectMessage?(): TClientMsg | null;
  createPingMessage(timestamp: number): TClientMsg;

  parseServerMessage(raw: string): TServerMsg;
  serializeClientMessage(msg: TClientMsg): string;
  isConnectAccepted(msg: TServerMsg): boolean;
  isError(msg: TServerMsg): boolean;
  getErrorInfo(msg: TServerMsg): { code: string; message: string } | null;

  initAgentState(connectResponse: TServerMsg, agentId: string): TAgentState;
  updateAgentState(state: TAgentState, msg: TServerMsg): TAgentState;
  getAvailableActions(state: TAgentState): AvailableAction[];
  buildActionMessage(state: TAgentState, action: string, params?: Record<string, unknown>): TClientMsg | null;

  checkInvariants(state: TAgentState): InvariantViolation[];
  describeGameContext(): string;
  describeAvailableActions(): ActionDescription[];
}

interface AgentConnection {
  send(data: string): void;
  onMessage(handler: (data: string) => void): void;
  onClose(handler: (code: number, reason: string) => void): void;
  onError(handler: (error: Error) => void): void;
  close(): void;
  isConnected(): boolean;
}

interface AgentConfig {
  id: string;                              // e.g., "bot-000"
  name: string;                            // e.g., "S1a2b00"
  tickIntervalMs: number;
  connectTimeoutMs: number;                // Default: 5000
  gameConfig?: Record<string, unknown>;    // Game-specific config (e.g., starter selection)
}

interface AvailableAction {
  name: string;
  description: string;
  params?: Record<string, ParamSpec>;
  weight?: number;
}

interface ParamSpec {
  type: 'string' | 'number' | 'boolean' | 'enum';
  values?: (string | number)[];
  min?: number;
  max?: number;
}

type FindingSeverity = 'crash' | 'bug' | 'jank' | 'warning' | 'info';

interface Finding {
  id: string;
  severity: FindingSeverity;
  category: string;
  title: string;
  description: string;
  agentId: string;
  timestamp: number;
  context?: { timestamp: number; direction: string; data: string }[];
  metadata?: Record<string, unknown>;
}

interface Detector {
  readonly name: string;
  onSwarmStart?(): void;
  onAgentTick?(agent: AgentHandle): void;
  onMessage?(agent: AgentHandle, raw: string, direction: 'sent' | 'received', parsed?: unknown): void;
  onAgentConnect?(agent: AgentHandle): void;
  onAgentDisconnect?(agent: AgentHandle, code: number, reason: string): void;
  onAgentError?(agent: AgentHandle, error: Error): void;
  onCrossAgentCheck?(agents: AgentHandle[]): void;
  getFindings(): Finding[];
}

interface Reporter {
  onFinding(finding: Finding): void;
  onComplete(summary: SwarmSummary): void;
}

interface SwarmSummary {
  durationMs: number;
  agentCount: number;
  connectedCount: number;
  failedCount: number;
  totalMessagesSent: number;
  totalMessagesReceived: number;
  totalErrors: number;
  findings: Finding[];
  findingsBySeverity: Record<string, number>;
  agentSummaries: AgentSummary[];
}

interface AgentSummary {
  agentId: string;
  phase: string;
  connected: boolean;
  connectFailReason: string | null;
  messagesSent: number;
  messagesReceived: number;
  latencyMs: number;
  findings: number;
}