substrate-ai 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1389 @@
+import pino from "pino";
+import { z } from "zod";
+
+//#region src/core/types.d.ts
+/**
+* Core types for Substrate
+* Shared type definitions used across all modules
+*/
+/** Unique identifier for a task in the DAG */
+/**
+ * Core types for Substrate
+ * Shared type definitions used across all modules
+ */
+/** Unique identifier for a task in the DAG */
+type TaskId = string;
+/** Unique identifier for a worker/agent instance */
+type WorkerId = string;
+/** Unique identifier for a registered agent type */
+type AgentId = string;
+/** Status of an individual task */
+type TaskStatus = 'pending' | 'ready' | 'queued' | 'running' | 'completed' | 'failed' | 'cancelled' | 'blocked';
+/** Status of an orchestration session */
+type SessionStatus = 'initializing' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+/** Billing mode for a worker/agent */
+type BillingMode = 'subscription' | 'api' | 'free';
+/** Severity level for errors and log messages */
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/** Task priority level */
+type TaskPriority = 'low' | 'normal' | 'high' | 'critical';
+/** Agent capability descriptor */
+interface AgentCapability {
+  name: string;
+  version: string;
+  supportedTaskTypes: string[];
+  billingMode: BillingMode;
+  maxConcurrency: number;
+}
+/** Task graph node definition */
+interface TaskNode {
+  id: TaskId;
+  title: string;
+  description: string;
+  agentId?: AgentId;
+  status: TaskStatus;
+  priority: TaskPriority;
+  dependencies: TaskId[];
+  metadata: Record<string, unknown>;
+  createdAt: Date;
+  startedAt?: Date;
+  completedAt?: Date;
+}
+/** Session configuration */
+interface SessionConfig {
+  id: string;
+  name: string;
+  projectRoot: string;
+  taskGraphPath: string;
+  maxConcurrency: number;
+  budgetCap?: number;
+  billingMode: BillingMode;
+}
+/** Cost tracking record */
+interface CostRecord {
+  taskId: TaskId;
+  agentId: AgentId;
+  sessionId: string;
+  tokens: number;
+  estimatedCost: number;
+  billingMode: BillingMode;
+  timestamp: Date;
+} //#endregion
+//#region src/core/errors.d.ts
+
+//# sourceMappingURL=types.d.ts.map
+/**
+ * Error definitions for Substrate
+ * Provides structured error hierarchy for all toolkit operations
+ */
+/** Base error class for all Substrate errors */
+declare class AdtError extends Error {
+  readonly code: string;
+  readonly context: Record<string, unknown>;
+  constructor(message: string, code: string, context?: Record<string, unknown>);
+  toJSON(): Record<string, unknown>;
+}
+/** Error thrown when task configuration is invalid */
+declare class TaskConfigError extends AdtError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+/** Error thrown when a worker/agent operation fails */
+declare class WorkerError extends AdtError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+/** Error thrown when a worker/agent cannot be found */
+declare class WorkerNotFoundError extends AdtError {
+  constructor(agentId: string);
+}
+/** Error thrown when a task graph is invalid */
+declare class TaskGraphError extends AdtError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+/** Error thrown when a task graph has cycles (deadlock) */
+declare class TaskGraphCycleError extends TaskGraphError {
+  constructor(cycle: string[]);
+}
+/** Error thrown when a budget limit is exceeded */
+declare class BudgetExceededError extends AdtError {
+  constructor(limit: number, current: number, context?: Record<string, unknown>);
+}
+/** Error thrown when git operations fail */
+declare class GitError extends AdtError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+/** Error thrown when configuration is invalid or missing */
+declare class ConfigError extends AdtError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+/** Error thrown when state recovery fails */
+declare class RecoveryError extends AdtError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+/** Error thrown when a config file uses an incompatible format version */
+declare class ConfigIncompatibleFormatError extends AdtError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+/** Error thrown when a task graph file uses an incompatible format version */
+declare class TaskGraphIncompatibleFormatError extends AdtError {
+  constructor(message: string, context?: Record<string, unknown>);
+}
+
+//#endregion
+//#region src/utils/logger.d.ts
+//# sourceMappingURL=errors.d.ts.map
+/** Logger configuration options */
+interface LoggerOptions {
+  level?: string;
+  name?: string;
+  pretty?: boolean;
+}
+/**
+ * Create a named logger instance
+ * @param name - Logger name (module identifier)
+ * @param options - Optional logger configuration overrides
+ */
+declare function createLogger(name: string, options?: LoggerOptions): pino.Logger;
+/** Root application logger */
+declare const logger: pino.Logger<never, boolean>;
+/** Create a child logger with additional context */
+declare function childLogger(parent: pino.Logger, bindings: Record<string, unknown>): pino.Logger;
+
+//#endregion
+//#region src/utils/helpers.d.ts
+//# sourceMappingURL=logger.d.ts.map
+/**
+ * General utility helpers for Substrate
+ */
+/**
+ * Sleep for a given number of milliseconds
+ * @param ms - Milliseconds to sleep
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Assert that a value is defined (not null or undefined)
+ * @param value - Value to check
+ * @param message - Error message if undefined
+ */
+declare function assertDefined<T>(value: T | null | undefined, message: string): asserts value is T;
+/**
+ * Format a duration in milliseconds to a human-readable string
+ * @param ms - Duration in milliseconds
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Generate a unique identifier using crypto.randomUUID()
+ * @param prefix - Optional prefix for the ID
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * Deep clone an object using structuredClone.
+ * Supports most built-in types (Date, Map, Set, ArrayBuffer, etc.)
+ * but does NOT support functions, DOM nodes, or symbols as keys.
+ * @param obj - Object to clone
+ */
+declare function deepClone<T>(obj: T): T;
+/**
+ * Check if a value is a plain object (not an array, Date, or other special object)
+ * @param value - Value to check
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Retry an async operation with exponential backoff
+ * @param fn - Async function to retry
+ * @param maxRetries - Maximum number of retries
+ * @param baseDelayMs - Base delay in milliseconds (doubles each retry)
+ */
+declare function withRetry<T>(fn: () => Promise<T>, maxRetries?: number, baseDelayMs?: number): Promise<T>;
+
+//#endregion
+//#region src/modules/config/config-schema.d.ts
+//# sourceMappingURL=helpers.d.ts.map
+
+declare const SubstrateConfigSchema: z.ZodObject<{
+  config_format_version: z.ZodEnum<{
+    1: "1";
+  }>;
+  task_graph_version: z.ZodOptional<z.ZodEnum<{
+    1: "1";
+  }>>;
+  global: z.ZodObject<{
+    log_level: z.ZodEnum<{
+      fatal: "fatal";
+      error: "error";
+      warn: "warn";
+      info: "info";
+      debug: "debug";
+      trace: "trace";
+    }>;
+    max_concurrent_tasks: z.ZodNumber;
+    budget_cap_tokens: z.ZodNumber;
+    budget_cap_usd: z.ZodNumber;
+    workspace_dir: z.ZodOptional<z.ZodString>;
+    update_check: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>;
+  providers: z.ZodObject<{
+    claude: z.ZodOptional<z.ZodObject<{
+      enabled: z.ZodBoolean;
+      cli_path: z.ZodOptional<z.ZodString>;
+      subscription_routing: z.ZodEnum<{
+        auto: "auto";
+        subscription: "subscription";
+        api: "api";
+        disabled: "disabled";
+      }>;
+      max_concurrent: z.ZodNumber;
+      rate_limit: z.ZodOptional<z.ZodObject<{
+        tokens: z.ZodNumber;
+        window_seconds: z.ZodNumber;
+      }, z.core.$strict>>;
+      api_key_env: z.ZodOptional<z.ZodString>;
+      api_billing: z.ZodBoolean;
+    }, z.core.$strict>>;
+    codex: z.ZodOptional<z.ZodObject<{
+      enabled: z.ZodBoolean;
+      cli_path: z.ZodOptional<z.ZodString>;
+      subscription_routing: z.ZodEnum<{
+        auto: "auto";
+        subscription: "subscription";
+        api: "api";
+        disabled: "disabled";
+      }>;
+      max_concurrent: z.ZodNumber;
+      rate_limit: z.ZodOptional<z.ZodObject<{
+        tokens: z.ZodNumber;
+        window_seconds: z.ZodNumber;
+      }, z.core.$strict>>;
+      api_key_env: z.ZodOptional<z.ZodString>;
+      api_billing: z.ZodBoolean;
+    }, z.core.$strict>>;
+    gemini: z.ZodOptional<z.ZodObject<{
+      enabled: z.ZodBoolean;
+      cli_path: z.ZodOptional<z.ZodString>;
+      subscription_routing: z.ZodEnum<{
+        auto: "auto";
+        subscription: "subscription";
+        api: "api";
+        disabled: "disabled";
+      }>;
+      max_concurrent: z.ZodNumber;
+      rate_limit: z.ZodOptional<z.ZodObject<{
+        tokens: z.ZodNumber;
+        window_seconds: z.ZodNumber;
+      }, z.core.$strict>>;
+      api_key_env: z.ZodOptional<z.ZodString>;
+      api_billing: z.ZodBoolean;
+    }, z.core.$strict>>;
+  }, z.core.$strict>;
+  cost_tracker: z.ZodOptional<z.ZodObject<{
+    enabled: z.ZodBoolean;
+    token_rates_provider: z.ZodEnum<{
+      builtin: "builtin";
+      custom: "custom";
+    }>;
+    track_planning_costs: z.ZodBoolean;
+    savings_reporting: z.ZodBoolean;
+  }, z.core.$strict>>;
+  budget: z.ZodOptional<z.ZodObject<{
+    default_task_budget_usd: z.ZodNumber;
+    default_session_budget_usd: z.ZodNumber;
+    planning_costs_count_against_budget: z.ZodBoolean;
+    warning_threshold_percent: z.ZodNumber;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+type SubstrateConfig = z.infer<typeof SubstrateConfigSchema>;
+
+//#endregion
+//#region src/core/event-bus.types.d.ts
+/**
+ * Routing decision payload used in task:routed event.
+ * Mirrors RoutingDecision from src/modules/routing/routing-decision.ts
+ * but kept here as a plain interface to avoid circular module dependencies.
+ */
+interface RoutingDecision {
+  taskId: string;
+  agent: string;
+  billingMode: 'subscription' | 'api' | 'unavailable';
+  model?: string;
+  rationale: string;
+  fallbackChain?: string[];
+  estimatedCostUsd?: number;
+  rateLimit?: {
+    tokensUsedInWindow: number;
+    limit: number;
+  };
+}
+/** Result of a completed task */
+interface TaskResult$1 {
+  output?: string;
+  exitCode?: number;
+  tokensUsed?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  durationMs?: number;
+  costUsd?: number;
+  agent?: string;
+}
+/** Error payload for a failed task */
+interface TaskError {
+  message: string;
+  code?: string;
+  stack?: string;
+}
+/**
+ * Complete typed map of all events emitted on the orchestrator event bus.
+ * Use `keyof OrchestratorEvents` to constrain event keys.
+ */
+interface OrchestratorEvents {
+  /** Task has all dependencies satisfied and is ready to be assigned */
+  'task:ready': {
+    taskId: TaskId;
+    taskType?: string;
+  };
+  /** A worker has begun execution of a task */
+  'task:started': {
+    taskId: TaskId;
+    workerId: WorkerId;
+    agent: string;
+  };
+  /** Incremental progress report from a running task */
+  'task:progress': {
+    taskId: TaskId;
+    message: string;
+    tokensUsed?: number;
+  };
+  /** Task has completed successfully */
+  'task:complete': {
+    taskId: TaskId;
+    result: TaskResult$1;
+    taskType?: string;
+  };
+  /** Task has failed with an error */
+  'task:failed': {
+    taskId: TaskId;
+    error: TaskError;
+  };
+  /** Task was cancelled */
+  'task:cancelled': {
+    taskId: TaskId;
+    reason: string;
+  };
+  /** Task is being retried after a failure */
+  'task:retrying': {
+    taskId: TaskId;
+    attempt: number;
+    maxAttempts: number;
+  };
+  /** A worker subprocess was spawned */
+  'worker:spawned': {
+    workerId: WorkerId;
+    taskId: TaskId;
+    agent: string;
+  };
+  /** A worker subprocess was terminated */
+  'worker:terminated': {
+    workerId: WorkerId;
+    reason: string;
+  };
+  /** Spending is approaching the configured budget limit */
+  'budget:warning': {
+    taskId: TaskId;
+    currentSpend: number;
+    limit: number;
+  };
+  /** Spending has exceeded the configured budget limit */
+  'budget:exceeded': {
+    taskId: TaskId;
+    spend: number;
+    limit: number;
+  };
+  /** Task is approaching its budget cap (80% threshold) */
+  'budget:warning:task': {
+    taskId: TaskId;
+    currentCostUsd: number;
+    budgetUsd: number;
+    percentageUsed: number;
+  };
+  /** Task has exceeded its budget cap — force-terminate worker */
+  'budget:exceeded:task': {
+    taskId: TaskId;
+    currentCostUsd: number;
+    budgetUsd: number;
+  };
+  /** Session-wide budget is approaching the cap (80% threshold) */
+  'budget:warning:session': {
+    sessionId: string;
+    currentCostUsd: number;
+    budgetUsd: number;
+    percentageUsed: number;
+  };
+  /** Session-wide budget has been exceeded — terminate all workers */
+  'session:budget:exceeded': {
+    sessionId: string;
+    currentCostUsd: number;
+    budgetUsd: number;
+  };
+  /** Budget cap has been set for a task */
+  'task:budget-set': {
+    taskId: TaskId;
+    budgetUsd: number;
+  };
+  /** Budget cap has been set for a session */
+  'session:budget-set': {
+    sessionId: string;
+    budgetUsd: number;
+  };
+  /** A task graph has been loaded and validated */
+  'graph:loaded': {
+    sessionId: string;
+    taskCount: number;
+    readyCount: number;
+  };
+  /** All tasks in the graph have completed or failed */
+  'graph:complete': {
+    totalTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+    totalCostUsd: number;
+  };
+  /** Graph execution was cancelled */
+  'graph:cancelled': {
+    cancelledTasks: number;
+  };
+  /** Graph execution was paused */
+  'graph:paused': Record<string, never>;
+  /** Graph execution was resumed */
+  'graph:resumed': Record<string, never>;
+  /** A git worktree was created for a task */
+  'worktree:created': {
+    taskId: TaskId;
+    branchName: string;
+    worktreePath: string;
+    createdAt?: Date;
+  };
+  /** A task's worktree branch was merged */
+  'worktree:merged': {
+    taskId: TaskId;
+    branch: string;
+    mergedFiles: string[];
+  };
+  /** A merge conflict was detected in a task's worktree */
+  'worktree:conflict': {
+    taskId: TaskId;
+    branch: string;
+    conflictingFiles: string[];
+  };
+  /** A task's worktree was removed */
+  'worktree:removed': {
+    taskId: TaskId;
+    branchName: string;
+  };
+  /** Plan generation has started */
+  'plan:generating': {
+    agent: string;
+    description: string;
+  };
+  /** Plan generation has completed */
+  'plan:generated': {
+    taskCount: number;
+    estimatedCost: number;
+  };
+  /** Plan was approved by the user */
+  'plan:approved': {
+    taskCount: number;
+  };
+  /** Plan was rejected by the user */
+  'plan:rejected': {
+    reason: string;
+  };
+  /** Plan is being refined based on feedback */
+  'plan:refining': {
+    planId: string;
+    feedback: string;
+    currentVersion: number;
+  };
+  /** Plan refinement completed successfully */
+  'plan:refined': {
+    planId: string;
+    newVersion: number;
+    taskCount: number;
+  };
+  /** Plan was rolled back to a previous version */
+  'plan:rolled-back': {
+    planId: string;
+    fromVersion: number;
+    toVersion: number;
+    newVersion: number;
+  };
+  /** Plan refinement failed */
+  'plan:refinement-failed': {
+    planId: string;
+    currentVersion: number;
+    error: string;
+  };
+  /** A task's cost has been recorded by the cost tracker */
+  'cost:recorded': {
+    taskId: string;
+    sessionId: string;
+    costUsd: number;
+    savingsUsd: number;
+    billingMode: 'subscription' | 'api';
+  };
+  /** A task's metrics have been recorded by the monitor */
+  'monitor:metrics_recorded': {
+    taskId: string;
+    agent: string;
+    taskType: string;
+  };
+  /** A routing recommendation has been generated by the monitor */
+  'monitor:recommendation_generated': {
+    taskType: string;
+    recommendedAgent: string;
+    confidence: number;
+  };
+  /** Configuration has been reloaded */
+  'config:reloaded': {
+    path: string;
+    previousConfig: SubstrateConfig;
+    newConfig: SubstrateConfig;
+    changedKeys: string[];
+  };
+  /** A task has been routed to an agent with billing mode decision */
+  'task:routed': {
+    taskId: TaskId;
+    decision: RoutingDecision;
+  };
+  /** A provider has become unavailable */
+  'provider:unavailable': {
+    provider: string;
+    reason: 'rate_limit' | 'disabled';
+    resetAtMs?: number;
+  };
+  /** A provider has become available */
+  'provider:available': {
+    provider: string;
+  };
+  /** A newer version of the toolkit is available */
+  'version:update_available': {
+    currentVersion: string;
+    latestVersion: string;
+    breaking: boolean;
+  };
+  /** A sub-agent subprocess was spawned by the dispatch engine */
+  'agent:spawned': {
+    dispatchId: string;
+    agent: string;
+    taskType: string;
+  };
+  /** Incremental stdout data received from a running sub-agent */
+  'agent:output': {
+    dispatchId: string;
+    data: string;
+  };
+  /** A sub-agent completed successfully */
+  'agent:completed': {
+    dispatchId: string;
+    exitCode: number;
+    output: string;
+  };
+  /** A sub-agent exited with a non-zero code or encountered an error */
+  'agent:failed': {
+    dispatchId: string;
+    error: string;
+    exitCode: number;
+  };
+  /** A sub-agent was killed because it exceeded its timeout */
+  'agent:timeout': {
+    dispatchId: string;
+    timeoutMs: number;
+  };
+  /** Orchestrator has been fully initialized and is ready to process tasks */
+  'orchestrator:ready': Record<string, never>;
+  /** Orchestrator shutdown has been initiated */
+  'orchestrator:shutdown': {
+    reason: string;
+  };
+  /** Implementation orchestrator has started processing story keys */
+  'orchestrator:started': {
+    storyKeys: string[];
+    pipelineRunId?: string;
+  };
+  /** A story phase has completed within the implementation orchestrator */
+  'orchestrator:story-phase-complete': {
+    storyKey: string;
+    phase: string;
+    result: unknown;
+  };
+  /** A story has completed the full pipeline with SHIP_IT verdict */
+  'orchestrator:story-complete': {
+    storyKey: string;
+    reviewCycles: number;
+  };
+  /** A story has been escalated after exceeding max review cycles */
+  'orchestrator:story-escalated': {
+    storyKey: string;
+    lastVerdict: string;
+    reviewCycles: number;
+    issues: unknown[];
+  };
+  /** Implementation orchestrator has finished all stories */
+  'orchestrator:complete': {
+    totalStories: number;
+    completed: number;
+    escalated: number;
+    failed: number;
+  };
+  /** Implementation orchestrator has been paused */
+  'orchestrator:paused': Record<string, never>;
+  /** Implementation orchestrator has been resumed */
+  'orchestrator:resumed': Record<string, never>;
+} //#endregion
+//#region src/core/event-bus.d.ts
+//# sourceMappingURL=event-bus.types.d.ts.map
+/**
+ * A typed publish-subscribe bus.
+ *
+ * All event names and payload types are enforced by the `OrchestratorEvents` map.
+ */
+interface TypedEventBus {
+  /**
+   * Emit an event with a strongly-typed payload.
+   * Dispatch is synchronous — all registered handlers run before emit() returns.
+   */
+  emit<K extends keyof OrchestratorEvents>(event: K, payload: OrchestratorEvents[K]): void;
+  /**
+   * Subscribe to an event. The handler is called synchronously on each emit.
+   */
+  on<K extends keyof OrchestratorEvents>(event: K, handler: (payload: OrchestratorEvents[K]) => void): void;
+  /**
+   * Unsubscribe a previously registered handler.
+   * If the handler was not registered, this is a no-op.
+   */
+  off<K extends keyof OrchestratorEvents>(event: K, handler: (payload: OrchestratorEvents[K]) => void): void;
+}
+/**
+ * Concrete implementation of TypedEventBus backed by Node.js EventEmitter.
+ *
+ * @example
+ * const bus = new TypedEventBusImpl()
+ * bus.on('task:complete', ({ taskId, result }) => {
+ *   console.log(`Task ${taskId} finished`)
+ * })
+ * bus.emit('task:complete', { taskId: 'abc', result: { exitCode: 0 } })
+ */
+
+/**
+ * Create a new TypedEventBus instance.
+ *
+ * @example
+ * const bus = createEventBus()
+ */
+declare function createEventBus(): TypedEventBus;
+
+//#endregion
+//#region src/core/orchestrator.d.ts
+//# sourceMappingURL=event-bus.d.ts.map
+/**
+ * Configuration required to initialize the orchestrator.
+ */
+interface OrchestratorConfig {
+  /** Path to the SQLite database file (e.g., ".substrate/state.db") */
+  databasePath: string;
+  /** Working directory for the orchestrated project */
+  projectRoot: string;
+  /**
+   * Maximum number of concurrent worker tasks.
+   * @default 4
+   */
+  maxConcurrency?: number;
+  /**
+   * Budget cap in USD (0 = unlimited).
+   * @default 0
+   */
+  budgetCapUsd?: number;
+  /**
+   * Budget cap in tokens (0 = unlimited).
+   * @default 0
+   */
+  budgetCapTokens?: number;
+  /** Optional logger level override */
+  logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  /**
+   * Path to the substrate config file for hot-reload watching.
+   * If omitted, defaults to <projectRoot>/substrate.config.yaml
+   */
+  configPath?: string;
+  /**
+   * Enable config hot-reload via file watcher.
+   * When true (default), a file watcher is registered on the config file.
+   * Set to false to disable (e.g. in dry-run or --no-watch-config mode).
+   * @default true
+   */
+  enableConfigHotReload?: boolean;
+  /**
+   * Monitor agent configuration.
+   * If omitted, monitor agent is initialized with defaults.
+   */
+  monitor?: {
+    /**
+     * Path to the monitor SQLite database file.
+     * @default ':memory:' (in-memory, non-persistent) when not specified
+     */
+    databasePath?: string;
+    /**
+     * Number of days to retain task metrics.
+     * @default 90
+     */
+    retentionDays?: number;
+    /**
+     * Custom task type taxonomy for classification overrides.
+     */
+    customTaxonomy?: Record<string, string[]>;
+    /**
+     * Enable advisory routing recommendations based on performance data (AC6, FR68).
+     * When true, MonitorAgent.getRecommendation() returns recommendations for routing decisions.
+     * @default false
+     */
+    use_recommendations?: boolean;
+    /**
+     * Minimum success rate improvement (percentage points) required to generate a recommendation.
+     * @default 5.0
+     */
+    recommendation_threshold_percentage?: number;
+    /**
+     * Minimum number of tasks per (agent, task_type) pair before a recommendation is generated.
+     * @default 10
+     */
+    min_sample_size?: number;
+    /**
+     * Number of days of historical data to analyze for recommendations.
+     * @default 90
+     */
+    recommendation_history_days?: number;
+  };
+}
+/**
+ * Central orchestration engine — coordinates all modules via the event bus
+ * and dependency injection.
+ *
+ * Lifecycle:
+ *  1. Create via `createOrchestrator(config)`
+ *  2. Factory emits `orchestrator:ready` when initialization completes
+ *  3. Consumers interact with modules via the event bus or injected interfaces
+ *  4. On SIGTERM/SIGINT, graceful shutdown is triggered automatically
+ *  5. Call `shutdown()` explicitly for programmatic shutdown
+ */
+interface Orchestrator {
+  /**
+   * The typed event bus for this orchestrator instance.
+   * Modules and consumers use this to subscribe to and emit events.
+   */
+  readonly eventBus: TypedEventBus;
+  /**
+   * Whether the orchestrator has been fully initialized.
+   */
+  readonly isReady: boolean;
+  /**
+   * Perform a graceful shutdown of all modules.
+   * Calls shutdown() on all services in reverse initialization order.
+   * Safe to call multiple times — subsequent calls are no-ops.
+   */
+  shutdown(): Promise<void>;
+}
+
+//#endregion
+//#region src/core/orchestrator-impl.d.ts
+//# sourceMappingURL=orchestrator.d.ts.map
+/**
+ * Initialize the orchestrator with all modules wired via dependency injection.
+ *
+ * Steps performed:
+ *  1. Create the TypedEventBus
+ *  2. Create the SQLite database service
+ *  3. Instantiate all modules (TaskGraphEngine, RoutingEngine, WorkerManager,
+ *     BudgetTracker, GitManager) with constructor injection
+ *  4. Register all modules in the ServiceRegistry
+ *  5. Call initialize() on all services in registration order
+ *  6. Register SIGTERM/SIGINT graceful shutdown handlers
+ *  7. Emit orchestrator:ready
+ *
+ * @param config - Orchestrator configuration
+ * @returns Initialized Orchestrator instance
+ */
+declare function createOrchestrator(config: OrchestratorConfig): Promise<Orchestrator>;
+
+//#endregion
+//#region src/core/di.d.ts
+//# sourceMappingURL=orchestrator-impl.d.ts.map
+/**
+ * Dependency injection container and service registry.
+ *
+ * Provides:
+ *  - BaseService interface with initialize/shutdown lifecycle
+ *  - ServiceRegistry for registering and resolving services
+ *
+ * Design constraints (Architecture Section 19):
+ *  - No direct module-to-module imports; all wiring happens here.
+ *  - Modules communicate only via the Event Bus or injected interface dependencies.
+ *  - Services must support initialize() and shutdown() lifecycle methods.
+ */
+/**
+ * Lifecycle interface for all orchestrator services/modules.
+ * Every module must implement this to participate in graceful startup/shutdown.
+ */
+interface BaseService {
+  /**
+   * Initialize the service — set up connections, subscribe to events, etc.
+   * Called after all services are constructed but before the orchestrator
+   * emits orchestrator:ready.
+   */
+  initialize(): Promise<void>;
+  /**
+   * Tear down the service gracefully.
+   * Called during orchestrator shutdown in reverse dependency order.
+   */
+  shutdown(): Promise<void>;
+}
+/**
+ * Simple service registry — stores named service instances for DI resolution.
+ *
+ * Services are registered by name and can be retrieved by name or iterated
+ * in registration order for lifecycle management.
+ *
+ * @example
+ * const registry = new ServiceRegistry()
+ * registry.register('taskGraph', taskGraphEngine)
+ * registry.register('workerManager', workerManager)
+ *
+ * // Initialize all services
+ * await registry.initializeAll()
+ *
+ * // Shutdown all services in reverse order
+ * await registry.shutdownAll()
+ */
+declare class ServiceRegistry {
+  private readonly _services;
+  private readonly _order;
+  /**
+   * Register a named service. Registration order is preserved for lifecycle calls.
+   * @throws {Error} if a service with the same name is already registered.
+   */
+  register(name: string, service: BaseService): void;
+  /**
+   * Retrieve a registered service by name.
+   * @throws {Error} if no service with the given name is registered.
+   */
+  get(name: string): BaseService;
+  /**
+   * Returns true if a service with the given name is registered.
+   */
+  has(name: string): boolean;
+  /**
+   * Initialize all registered services in registration order.
+   * Fails fast on the first error — later services may depend on
+   * already-initialized ones, so continuing after a failure is unsafe.
+   * @throws the first initialization error encountered.
+   */
+  initializeAll(): Promise<void>;
+  /**
+   * Shut down all registered services in reverse registration order.
+   * Errors are collected and re-thrown as an AggregateError after all services
+   * have had a chance to shut down.
+   */
+  shutdownAll(): Promise<void>;
+  /** Return names of all registered services in registration order */
+  get serviceNames(): string[];
+}
+
+//#endregion
+//#region src/adapters/types.d.ts
+//# sourceMappingURL=di.d.ts.map
+/**
+ * A spawn command descriptor that the orchestrator uses to invoke a CLI agent.
+ * Contains all information needed to execute an agent process.
+ */
+interface SpawnCommand {
+  /** The binary to execute (e.g., "claude", "codex", "gemini") */
+  binary: string;
+  /** Arguments to pass to the binary */
+  args: string[];
+  /** Optional environment variable overrides */
+  env?: Record<string, string>;
+  /** Optional list of environment variable keys to unset in the child process */
+  unsetEnvKeys?: string[];
+  /** Working directory for the process */
+  cwd: string;
+  /** Optional data to pipe to stdin */
+  stdin?: string;
+  /** Optional timeout in milliseconds */
+  timeoutMs?: number;
+}
+/**
+ * Options passed to adapter methods for each invocation.
+ * Controls execution context for a specific task run.
+ */
+interface AdapterOptions {
+  /** Path to the git worktree for this task */
+  worktreePath: string;
+  /** Billing mode to use for this execution */
+  billingMode: BillingMode;
+  /** Optional model identifier override */
+  model?: string;
+  /** Optional additional CLI flags to append */
+  additionalFlags?: string[];
+  /** Optional API key override (used when billingMode is 'api') */
+  apiKey?: string;
+  /** Optional maximum agentic turns (passed as --max-turns to Claude CLI) */
+  maxTurns?: number;
+}
+/**
+ * Capabilities reported by an adapter for this CLI agent.
+ * Used for routing and planning decisions.
+ */
+interface AdapterCapabilities {
+  /** Whether the agent outputs structured JSON */
+  supportsJsonOutput: boolean;
+  /** Whether the agent supports streaming output */
+  supportsStreaming: boolean;
+  /** Whether the agent supports subscription-based billing */
+  supportsSubscriptionBilling: boolean;
+  /** Whether the agent supports API-key-based billing */
+  supportsApiBilling: boolean;
+  /** Whether the agent can generate task planning graphs */
+  supportsPlanGeneration: boolean;
+  /** Maximum context tokens the agent supports */
+  maxContextTokens: number;
+  /** Task types this agent can handle */
+  supportedTaskTypes: string[];
+  /** Programming languages the agent supports */
+  supportedLanguages: string[];
+}
+/**
+ * Result returned from an adapter health check.
+ * Indicates whether the CLI binary is present and functional.
+ */
+interface AdapterHealthResult {
+  /** Whether the adapter is considered healthy and usable */
+  healthy: boolean;
+  /** Detected version string of the CLI binary */
+  version?: string;
+  /** Full path to the CLI binary, if resolved */
+  cliPath?: string;
+  /** Error message when healthy is false */
+  error?: string;
+  /** Detected billing mode(s) available for this adapter */
+  detectedBillingModes?: BillingMode[];
+  /** Whether the CLI supports headless/non-interactive mode */
+  supportsHeadless: boolean;
+}
+/**
+ * Parsed result from a task execution.
+ * Normalized representation from CLI agent JSON output.
+ */
+interface TaskResult {
+  /** Task identifier this result belongs to */
+  taskId?: TaskId;
+  /** Whether the task completed successfully */
+  success: boolean;
+  /** Primary output content from the agent */
+  output: string;
+  /** Error message if the task failed */
+  error?: string;
+  /** Raw exit code from the CLI process */
+  exitCode: number;
+  /** Execution metadata */
+  metadata?: {
+    executionTime?: number;
+    tokensUsed?: TokenEstimate;
+  };
+}
+/**
+ * Token usage estimate for budget tracking.
+ */
+interface TokenEstimate {
+  /** Estimated input tokens */
+  input: number;
+  /** Estimated output tokens */
+  output: number;
+  /** Total token estimate */
+  total: number;
+}
+/**
+ * Request input for plan generation.
+ */
+interface PlanRequest {
+  /** High-level goal or description of work to plan */
+  goal: string;
+  /** Additional context for the planning agent */
+  context?: string;
+  /** Maximum number of tasks to generate */
+  maxTasks?: number;
+}
+/**
+ * Parsed result from a plan generation invocation.
+ */
+interface PlanParseResult {
+  /** Whether plan generation succeeded */
+  success: boolean;
+  /** Parsed list of planned task descriptions */
+  tasks: PlannedTask[];
+  /** Error message if plan generation failed */
+  error?: string;
+  /** Raw output for debugging */
+  rawOutput?: string;
+}
+/**
+ * A single task entry in a generated plan.
+ */
+interface PlannedTask {
+  /** Task title */
+  title: string;
+  /** Detailed description */
+  description: string;
+  /** Estimated complexity (1-10) */
+  complexity?: number;
+  /** Other task titles this task depends on */
+  dependencies?: string[];
+}
+
+//#endregion
+//#region src/adapters/worker-adapter.d.ts
+//# sourceMappingURL=types.d.ts.map
+/**
+ * WorkerAdapter — the interface every CLI agent adapter must implement.
+ *
+ * Adapters are responsible for:
+ * 1. Verifying their CLI binary is installed and responsive (healthCheck)
+ * 2. Constructing the spawn command to execute a task (buildCommand)
+ * 3. Constructing the spawn command for plan generation (buildPlanningCommand)
+ * 4. Parsing task result output from the CLI (parseOutput)
+ * 5. Parsing plan result output from the CLI (parsePlanOutput)
+ * 6. Estimating token usage for budget tracking (estimateTokens)
+ * 7. Reporting their capabilities for routing decisions (getCapabilities)
+ */
+interface WorkerAdapter {
+  /**
+   * Unique identifier for this adapter type.
+   * Used as the Map key in AdapterRegistry.
+   * @example "claude-code"
+   */
+  readonly id: AgentId;
+  /**
+   * Human-readable display name for the adapter.
+   * @example "Claude Code"
+   */
+  readonly displayName: string;
+  /**
+   * Semantic version of this adapter implementation.
+   * @example "1.0.0"
+   */
+  readonly adapterVersion: string;
+  /**
+   * Verify that the underlying CLI binary is installed, accessible, and
+   * able to respond in headless/non-interactive mode.
+   *
+   * This method must NOT throw — failures should be captured in the returned
+   * AdapterHealthResult.
+   *
+   * @returns A promise resolving to health check details
+   *
+   * @example
+   * ```typescript
+   * const result = await adapter.healthCheck()
+   * if (!result.healthy) console.error(result.error)
+   * ```
+   */
+  healthCheck(): Promise<AdapterHealthResult>;
+  /**
+   * Generate the spawn command to execute a coding task.
+   *
+   * The returned SpawnCommand must set `cwd` to options.worktreePath so the
+   * CLI agent operates in the correct git worktree (NFR10).
+   *
+   * @param prompt   Prompt or description of the task to execute
+   * @param options  Per-invocation execution options
+   * @returns SpawnCommand ready to be executed by the orchestrator
+   *
+   * @example
+   * ```typescript
+   * const cmd = adapter.buildCommand('Fix the failing tests', { worktreePath: '/tmp/wt', billingMode: 'api' })
+   * // spawn(cmd.binary, cmd.args, { cwd: cmd.cwd, env: { ...process.env, ...cmd.env } })
+   * ```
+   */
+  buildCommand(prompt: string, options: AdapterOptions): SpawnCommand;
+  /**
+   * Generate the spawn command to invoke the CLI agent for plan generation.
+   *
+   * @param request  Plan request with goal and context
+   * @param options  Per-invocation execution options
+   * @returns SpawnCommand for the planning invocation
+   */
+  buildPlanningCommand(request: PlanRequest, options: AdapterOptions): SpawnCommand;
+  /**
+   * Parse the raw CLI process output into a normalized TaskResult.
+   *
+   * This method must handle all output variations including:
+   * - Valid JSON stdout
+   * - Non-JSON stdout (fallback)
+   * - Non-zero exit codes
+   * - Combined stdout + stderr
+   *
+   * @param stdout    Standard output captured from the CLI process
+   * @param stderr    Standard error captured from the CLI process
+   * @param exitCode  Exit code from the CLI process
+   * @returns Normalized TaskResult
+   */
+  parseOutput(stdout: string, stderr: string, exitCode: number): TaskResult;
+  /**
+   * Parse the raw CLI output from a planning invocation into a PlanParseResult.
+   *
+   * @param stdout    Standard output from the planning invocation
+   * @param stderr    Standard error from the planning invocation
+   * @param exitCode  Exit code from the planning invocation
+   * @returns Parsed plan result
+   */
+  parsePlanOutput(stdout: string, stderr: string, exitCode: number): PlanParseResult;
+  /**
+   * Estimate the token count for a given prompt string.
+   *
+   * Used for pre-execution budget checks. Implementations may use heuristics
+   * (e.g., character count / 3) when exact tokenizers are unavailable.
+   *
+   * @param prompt  The prompt text to estimate
+   * @returns TokenEstimate with input, output, and total projections
+   *
+   * @example
+   * ```typescript
+   * const estimate = adapter.estimateTokens('Fix the failing tests in auth.ts')
+   * if (estimate.total > budgetCap) throw new BudgetExceededError(...)
+   * ```
+   */
+  estimateTokens(prompt: string): TokenEstimate;
+  /**
+   * Return the capabilities of this adapter's underlying CLI agent.
+   *
+   * The returned object is used by the orchestrator for:
+   * - Routing decisions (which adapter handles which task type)
+   * - Plan generation eligibility
+   * - Budget mode selection
+   *
+   * @returns AdapterCapabilities for this agent
+   */
+  getCapabilities(): AdapterCapabilities;
+}
+
+//#endregion
+//#region src/adapters/adapter-registry.d.ts
+//# sourceMappingURL=worker-adapter.d.ts.map
+/**
+ * Result from a single adapter discovery attempt.
+ */
+interface AdapterDiscoveryResult {
+  /** Adapter id that was tried */
+  adapterId: AgentId;
+  /** Display name of the adapter */
+  displayName: string;
+  /** Health check result */
+  healthResult: AdapterHealthResult;
+  /** Whether the adapter was registered (healthy) */
+  registered: boolean;
+}
+/**
+ * Summary result from discoverAndRegister().
+ */
+interface DiscoveryReport {
+  /** Number of adapters successfully registered */
+  registeredCount: number;
+  /** Number of adapters that failed health checks */
+  failedCount: number;
+  /** Per-adapter detail results */
+  results: AdapterDiscoveryResult[];
+}
+/**
+ * AdapterRegistry manages the lifecycle of WorkerAdapter instances.
+ *
+ * Usage:
+ * ```typescript
+ * const registry = new AdapterRegistry()
+ * const report = await registry.discoverAndRegister()
+ * const claude = registry.get('claude-code')
+ * ```
+ */
+declare class AdapterRegistry {
+  private readonly _adapters;
+  /**
+   * Register an adapter by its id.
+   * Overwrites any existing adapter with the same id.
+   */
+  register(adapter: WorkerAdapter): void;
+  /**
+   * Retrieve a registered adapter by id.
+   * @returns The adapter, or undefined if not registered
+   */
+  get(id: AgentId): WorkerAdapter | undefined;
+  /**
+   * Return all registered adapters as an array.
+   */
+  getAll(): WorkerAdapter[];
+  /**
+   * Return all registered adapters that support plan generation.
+   */
+  getPlanningCapable(): WorkerAdapter[];
+  /**
+   * Instantiate all built-in adapters, run health checks sequentially,
+   * and register those that pass.
+   *
+   * Failed adapters are included in the report but do NOT prevent startup.
+   *
+   * @returns Discovery report with per-adapter results
+   */
+  discoverAndRegister(): Promise<DiscoveryReport>;
+}
+
+//#endregion
+//#region src/adapters/claude-adapter.d.ts
+//# sourceMappingURL=adapter-registry.d.ts.map
+/**
+ * Adapter for the Claude Code CLI agent.
+ *
+ * Capabilities: JSON output, streaming, both billing modes, plan generation.
+ * Health check: runs `claude --version` to verify install.
+ * Billing detection: detects subscription vs API via version output or env.
+ */
+declare class ClaudeCodeAdapter implements WorkerAdapter {
+  readonly id: AgentId;
+  readonly displayName = "Claude Code";
+  readonly adapterVersion = "1.0.0";
+  /**
+   * Verify the `claude` binary is installed and responsive.
+   * Detects subscription vs API billing mode.
+   */
+  healthCheck(): Promise<AdapterHealthResult>;
+  /**
+   * Build spawn command for a coding task.
+   * Uses: `claude -p <prompt> --model <model> --dangerously-skip-permissions --system-prompt <minimal>`
+   */
+  buildCommand(prompt: string, options: AdapterOptions): SpawnCommand;
+  /**
+   * Build spawn command for plan generation.
+   * Appends a structured planning directive to the prompt.
+   */
+  buildPlanningCommand(request: PlanRequest, options: AdapterOptions): SpawnCommand;
+  /**
+   * Parse Claude CLI JSON stdout output into TaskResult.
+   */
+  parseOutput(stdout: string, stderr: string, exitCode: number): TaskResult;
+  /**
+   * Parse plan generation output from Claude.
+   */
+  parsePlanOutput(stdout: string, stderr: string, exitCode: number): PlanParseResult;
+  /**
+   * Estimate token count using character-based heuristic.
+   * Approximation: 1 token ≈ 3 characters for English text.
+   */
+  estimateTokens(prompt: string): TokenEstimate;
+  /**
+   * Return Claude Code's capabilities.
+   */
+  getCapabilities(): AdapterCapabilities;
+  private _detectBillingModes;
+  private _buildPlanningPrompt;
+}
+
+//#endregion
+//#region src/adapters/codex-adapter.d.ts
+//# sourceMappingURL=claude-adapter.d.ts.map
+/**
+ * Adapter for the OpenAI Codex CLI agent.
+ *
+ * Codex CLI uses stdin for the prompt and outputs JSON when --json flag is used.
+ * Codex supports subscription billing (via `codex login`) and API key billing.
+ */
+declare class CodexCLIAdapter implements WorkerAdapter {
+  readonly id: AgentId;
+  readonly displayName = "Codex CLI";
+  readonly adapterVersion = "1.0.0";
+  /**
+   * Verify the `codex` binary is installed and responsive.
+   */
+  healthCheck(): Promise<AdapterHealthResult>;
+  /**
+   * Build spawn command for a coding task.
+   * Uses: `codex exec --json` with prompt delivered via stdin.
+   */
+  buildCommand(prompt: string, options: AdapterOptions): SpawnCommand;
+  /**
+   * Build spawn command for plan generation.
+   * Uses codex exec with a JSON plan generation prompt via stdin.
+   */
+  buildPlanningCommand(request: PlanRequest, options: AdapterOptions): SpawnCommand;
+  /**
+   * Parse Codex CLI JSON output into a TaskResult.
+   */
+  parseOutput(stdout: string, stderr: string, exitCode: number): TaskResult;
+  /**
+   * Parse Codex plan generation output.
+   */
+  parsePlanOutput(stdout: string, stderr: string, exitCode: number): PlanParseResult;
+  /**
+   * Estimate token count using character-based heuristic.
+   */
+  estimateTokens(prompt: string): TokenEstimate;
+  /**
+   * Return Codex CLI capabilities.
+   */
+  getCapabilities(): AdapterCapabilities;
+  private _buildPlanningPrompt;
+}
+
+//#endregion
+//#region src/adapters/gemini-adapter.d.ts
+//# sourceMappingURL=codex-adapter.d.ts.map
+/**
+ * Adapter for the Google Gemini CLI agent.
+ *
+ * Gemini CLI follows similar patterns to Claude Code: prompt via `-p` flag,
+ * JSON output via `--output-format json`, and model via `--model`.
+ */
+declare class GeminiCLIAdapter implements WorkerAdapter {
+  readonly id: AgentId;
+  readonly displayName = "Gemini CLI";
+  readonly adapterVersion = "1.0.0";
+  /**
+   * Verify the `gemini` binary is installed and responsive.
+   * Detects subscription vs API billing mode.
+   */
+  healthCheck(): Promise<AdapterHealthResult>;
+  /**
+   * Build spawn command for a coding task.
+   * Uses: `gemini -p <prompt> --output-format json --model <model>`
+   */
+  buildCommand(prompt: string, options: AdapterOptions): SpawnCommand;
+  /**
+   * Build spawn command for plan generation.
+   */
+  buildPlanningCommand(request: PlanRequest, options: AdapterOptions): SpawnCommand;
+  /**
+   * Parse Gemini CLI JSON output into a TaskResult.
+   */
+  parseOutput(stdout: string, stderr: string, exitCode: number): TaskResult;
+  /**
+   * Parse Gemini plan generation output.
+   */
+  parsePlanOutput(stdout: string, stderr: string, exitCode: number): PlanParseResult;
+  /**
+   * Estimate token count using character-based heuristic.
+   */
+  estimateTokens(prompt: string): TokenEstimate;
+  /**
+   * Return Gemini CLI capabilities.
+   */
+  getCapabilities(): AdapterCapabilities;
+  private _detectBillingModes;
+  private _buildPlanningPrompt;
+}
+
+//#endregion
+//# sourceMappingURL=gemini-adapter.d.ts.map
+
+export { AdapterCapabilities, AdapterDiscoveryResult, AdapterHealthResult, AdapterOptions, AdapterRegistry, AdtError, AgentCapability, AgentId, BaseService, BillingMode, BudgetExceededError, ClaudeCodeAdapter, CodexCLIAdapter, ConfigError, ConfigIncompatibleFormatError, CostRecord, DiscoveryReport, GeminiCLIAdapter, GitError, LogLevel, Orchestrator, OrchestratorConfig, OrchestratorEvents, PlanParseResult, PlanRequest, PlannedTask, RecoveryError, ServiceRegistry, SessionConfig, SessionStatus, SpawnCommand, TaskConfigError, TaskGraphCycleError, TaskGraphError, TaskGraphIncompatibleFormatError, TaskId, TaskNode, TaskPriority, TaskResult, TaskStatus, TokenEstimate, TypedEventBus, WorkerAdapter, WorkerError, WorkerId, WorkerNotFoundError, assertDefined, childLogger, createEventBus, createLogger, createOrchestrator, deepClone, formatDuration, generateId, isPlainObject, logger, sleep, withRetry };
+//# sourceMappingURL=index.d.ts.map