@haoyiyin/workflow 0.2.0 → 0.2.3

package/src/agents/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Agents module index
+ *
+ * Public API surface for the subagent dispatch engine.
+ */
+
+// Types
+export type {
+  SubagentConfig,
+  SubagentContract,
+  SubagentResult,
+  SubagentArtifact,
+  SubagentRole,
+  PermissionSet,
+  MainAgentGuard,
+} from './types.js';
+
+// Dispatcher
+export {
+  SubagentDispatcher,
+  createDispatcher,
+  createProcessExecutor,
+} from './dispatcher.js';
+
+export type {
+  SubagentExecutor,
+  ExecutorOptions,
+  ExecutorResult,
+  ProcessExecutorConfig,
+  DispatcherOptions,
+} from './dispatcher.js';
+
+// Contracts
+export {
+  explorerContract,
+  implementerContract,
+  reviewerContract,
+  debuggerContract,
+  verifierContract,
+} from './contracts.js';
+
+export type {
+  ExplorerParams,
+  ImplementerParams,
+  ReviewerParams,
+  DebuggerParams,
+  VerifierParams,
+} from './contracts.js';

package/src/agents/resilience.ts

@@ -0,0 +1,255 @@
+/**
+ * Circuit breaker and retry mechanisms for resilient subagent dispatch
+ */
+
+// Circuit breaker states
+enum CircuitState {
+  CLOSED = 'closed',      // Normal operation
+  OPEN = 'open',          // Circuit broken, reject requests
+  HALF_OPEN = 'half-open' // Testing if service recovered
+}
+
+export class CircuitBreakerError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'CircuitBreakerError'
+  }
+}
+
+export class RetryExhaustedError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'RetryExhaustedError'
+  }
+}
+
+export interface CircuitBreakerConfig {
+  failureThreshold: number      // Failures before opening circuit
+  successThreshold: number       // Successes to close from half-open
+  timeout: number               // How long to stay open (ms)
+}
+
+export interface CircuitBreakerMetrics {
+  state: CircuitState
+  failureCount: number
+  successCount: number
+  timeUntilRetry: number
+}
+
+export class CircuitBreaker {
+  private state: CircuitState = CircuitState.CLOSED
+  private failureCount: number = 0
+  private successCount: number = 0
+  private nextAttempt: number = 0
+  private config: CircuitBreakerConfig
+
+  constructor(config: Partial<CircuitBreakerConfig> = {}) {
+    this.config = {
+      failureThreshold: 5,
+      successThreshold: 3,
+      timeout: 60000,
+      ...config
+    }
+  }
+
+  /**
+   * Execute operation with circuit breaker protection
+   */
+  async execute<T>(
+    operation: () => Promise<T>,
+    fallback?: () => T
+  ): Promise<T> {
+    // Check circuit state
+    if (this.state === CircuitState.OPEN) {
+      if (Date.now() < this.nextAttempt) {
+        // Still in timeout, use fallback or throw
+        if (fallback) {
+          console.log('[CircuitBreaker] Using fallback')
+          return fallback()
+        }
+        throw new CircuitBreakerError(
+          `Circuit open. Retry after ${new Date(this.nextAttempt).toISOString()}`
+        )
+      }
+      // Timeout elapsed, try half-open
+      this.state = CircuitState.HALF_OPEN
+      console.log('[CircuitBreaker] Entering HALF_OPEN state')
+    }
+
+    try {
+      const result = await operation()
+      this.onSuccess()
+      return result
+    } catch (error) {
+      this.onFailure()
+      throw error
+    }
+  }
+
+  private onSuccess(): void {
+    this.failureCount = 0
+
+    if (this.state === CircuitState.HALF_OPEN) {
+      this.successCount++
+      if (this.successCount >= this.config.successThreshold) {
+        console.log('[CircuitBreaker] CLOSED - service recovered')
+        this.state = CircuitState.CLOSED
+        this.successCount = 0
+      }
+    }
+  }
+
+  private onFailure(): void {
+    this.failureCount++
+
+    if (this.state === CircuitState.HALF_OPEN) {
+      // Failed in half-open, go back to open
+      this.tripCircuit()
+    } else if (this.failureCount >= this.config.failureThreshold) {
+      // Reached threshold, open circuit
+      this.tripCircuit()
+    }
+  }
+
+  private tripCircuit(): void {
+    console.log(`[CircuitBreaker] OPEN - failures: ${this.failureCount}`)
+    this.state = CircuitState.OPEN
+    this.nextAttempt = Date.now() + this.config.timeout
+    this.successCount = 0
+  }
+
+  getState(): CircuitState {
+    return this.state
+  }
+
+  getMetrics(): CircuitBreakerMetrics {
+    return {
+      state: this.state,
+      failureCount: this.failureCount,
+      successCount: this.successCount,
+      timeUntilRetry: Math.max(0, this.nextAttempt - Date.now())
+    }
+  }
+}
+
+export interface RetryPolicyConfig {
+  maxRetries: number
+  baseDelay: number
+  maxDelay: number
+  backoffMultiplier: number
+  retryableErrors: string[]
+}
+
+export class RetryPolicy {
+  private config: RetryPolicyConfig
+
+  constructor(config: Partial<RetryPolicyConfig> = {}) {
+    this.config = {
+      maxRetries: 3,
+      baseDelay: 1000,
+      maxDelay: 30000,
+      backoffMultiplier: 2,
+      retryableErrors: ['RateLimitError', 'TimeoutError', 'NetworkError', 'BudgetExceededError'],
+      ...config
+    }
+  }
+
+  /**
+   * Execute operation with retry logic
+   */
+  async execute<T>(operation: () => Promise<T>): Promise<T> {
+    let lastError: Error | undefined
+
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      try {
+        return await operation()
+      } catch (error) {
+        lastError = error as Error
+
+        if (!this.isRetryable(error)) {
+          throw error
+        }
+
+        if (attempt < this.config.maxRetries) {
+          const delay = this.calculateDelay(attempt)
+          console.log(`[RetryPolicy] Attempt ${attempt + 1} failed, retrying in ${Math.round(delay)}ms`)
+          await this.sleep(delay)
+        }
+      }
+    }
+
+    throw new RetryExhaustedError(
+      `Failed after ${this.config.maxRetries} retries: ${lastError?.message}`
+    )
+  }
+
+  private isRetryable(error: unknown): boolean {
+    if (!(error instanceof Error)) return false
+
+    const errorName = error.constructor.name
+    return this.config.retryableErrors.some(re =>
+      errorName.includes(re) || error.message.includes(re)
+    )
+  }
+
+  private calculateDelay(attempt: number): number {
+    // Exponential backoff with jitter
+    const exponentialDelay = this.config.baseDelay *
+      Math.pow(this.config.backoffMultiplier, attempt)
+    const jitter = exponentialDelay * 0.25 * (Math.random() * 2 - 1)
+    return Math.min(exponentialDelay + jitter, this.config.maxDelay)
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms))
+  }
+}
+
+export interface ResilientDispatchOptions<T> {
+  fallback?: () => T
+  onRetry?: (attempt: number, error: Error) => void
+  onCircuitOpen?: () => void
+}
+
+export class ResilientDispatcher {
+  private circuitBreaker: CircuitBreaker
+  private retryPolicy: RetryPolicy
+
+  constructor(config?: {
+    circuitBreaker?: Partial<CircuitBreakerConfig>
+    retryPolicy?: Partial<RetryPolicyConfig>
+  }) {
+    this.circuitBreaker = new CircuitBreaker(config?.circuitBreaker)
+    this.retryPolicy = new RetryPolicy(config?.retryPolicy)
+  }
+
+  /**
+   * Dispatch with both circuit breaker and retry
+   */
+  async dispatch<T>(
+    operation: () => Promise<T>,
+    options: ResilientDispatchOptions<T> = {}
+  ): Promise<T> {
+    return this.circuitBreaker.execute(
+      async () => {
+        return await this.retryPolicy.execute(operation)
+      },
+      options.fallback
+    )
+  }
+
+  /**
+   * Get health metrics
+   */
+  getHealth(): {
+    circuitState: CircuitState
+    metrics: CircuitBreakerMetrics
+  } {
+    return {
+      circuitState: this.circuitBreaker.getState(),
+      metrics: this.circuitBreaker.getMetrics()
+    }
+  }
+}
+
+export { CircuitState }

package/src/agents/token-budget.ts

@@ -0,0 +1,83 @@
+/**
+ * Token budget management for context window management
+ */
+
+export interface TokenUsage {
+  used: number
+  limit: number
+  percentage: number
+}
+
+export interface TokenBudgetConfig {
+  limit: number
+  warningThreshold: number
+}
+
+export class TokenBudget {
+  private used: number = 0
+  private readonly limit: number
+  private readonly warningThreshold: number
+
+  constructor(config: TokenBudgetConfig = { limit: 1_000_000, warningThreshold: 0.8 }) {
+    this.limit = config.limit
+    this.warningThreshold = config.warningThreshold
+  }
+
+  /**
+   * Check if we can afford the estimated tokens
+   */
+  canAfford(estimatedTokens: number): boolean {
+    return this.used + estimatedTokens <= this.limit
+  }
+
+  /**
+   * Record token usage
+   */
+  recordUsage(tokens: number): void {
+    this.used += tokens
+
+    if (this.used > this.limit * this.warningThreshold) {
+      console.warn(`[TokenBudget] Warning: ${this.used}/${this.limit} tokens used (${Math.round(this.getUsage().percentage)}%)`)
+    }
+  }
+
+  /**
+   * Get remaining tokens
+   */
+  getRemaining(): number {
+    return Math.max(0, this.limit - this.used)
+  }
+
+  /**
+   * Get current usage stats
+   */
+  getUsage(): TokenUsage {
+    return {
+      used: this.used,
+      limit: this.limit,
+      percentage: (this.used / this.limit) * 100
+    }
+  }
+
+  /**
+   * Estimate tokens for a text string (rough approximation)
+   * ~4 chars per token for English text
+   */
+  static estimateTokens(text: string): number {
+    return Math.ceil(text.length / 4)
+  }
+
+  /**
+   * Reset budget (for testing or new milestone)
+   */
+  reset(): void {
+    this.used = 0
+  }
+}
+
+export class BudgetExceededError extends Error {
+  constructor(message: string = 'Token budget exceeded') {
+    super(message)
+    this.name = 'BudgetExceededError'
+  }
+}

package/src/agents/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Subagent system types
+ */
+
+export type SubagentRole =
+  | 'explorer'       // Read-only exploration
+  | 'implementer'    // Code implementation
+  | 'reviewer'       // Code review
+  | 'planner'        // Plan creation
+  | 'debugger'       // Root cause analysis
+  | 'verifier'       // Goal verification
+  | 'researcher'     // Internet research and information gathering
+  | 'general'        // Catch-all
+
+export interface SubagentConfig {
+  role: SubagentRole
+  model?: string
+  isolation?: 'worktree'
+  tokenBudget?: number
+  timeout?: number
+}
+
+export interface SubagentContract {
+  /** What this subagent is allowed to do */
+  permissions: PermissionSet
+  /** Exact prompt to send */
+  prompt: string
+  /** Required output format */
+  outputSchema?: Record<string, unknown>
+  /** Files this subagent owns */
+  owns: string[]
+  /** Files this subagent may read */
+  reads: string[]
+}
+
+export interface PermissionSet {
+  readFiles: boolean
+  searchCode: boolean
+  runCommands: boolean
+  writeFiles: boolean
+  gitOperations: boolean
+}
+
+export interface SubagentResult {
+  id: string
+  role: SubagentRole
+  status: 'success' | 'failure' | 'timeout'
+  output: string
+  artifacts: SubagentArtifact[]
+  tokensUsed: number
+  duration: number
+  errors: string[]
+}
+
+export interface SubagentArtifact {
+  type: 'file' | 'diff' | 'test-result' | 'report'
+  path?: string
+  content: string
+}
+
+/** Controls what the main agent is allowed to do */
+export interface MainAgentGuard {
+  /** Is the main agent currently allowed to read source files? */
+  canReadSource: boolean
+  /** Is the main agent currently allowed to search the codebase? */
+  canSearchCodebase: boolean
+  /** Is the main agent currently allowed to write files? */
+  canWriteFiles: boolean
+  /** Is the main agent in "embargo" mode (must delegate everything)? */
+  embargoActive: boolean
+  /** Active subagent IDs that must complete before guard lifts */
+  pendingSubagents: string[]
+}

package/src/guard/main-agent.ts

@@ -0,0 +1,245 @@
+/**
+ * Main Agent Guard - Enforces that Main Agent NEVER does actual work
+ *
+ * This is the CORE architectural constraint:
+ * - Main Agent = Orchestrator only
+ * - All real work = Subagents only
+ */
+
+import type { Logger } from '../types.js'
+
+export interface GuardConfig {
+  /** Token budget before forced checkpoint */
+  tokenBudget: number
+  /** Whether embargo is active */
+  embargoActive: boolean
+  /** List of prohibited operations */
+  prohibited: ProhibitedOperations
+}
+
+export interface ProhibitedOperations {
+  readSourceFiles: boolean
+  searchCodebase: boolean
+  writeFiles: boolean
+  runBuildCommands: boolean
+  runTests: boolean
+  editLargeFiles: boolean
+  longRunningTasks: boolean
+}
+
+export interface OperationRequest {
+  type: 'read' | 'search' | 'write' | 'run' | 'edit'
+  target?: string
+  estimatedLines?: number
+  estimatedDuration?: number
+}
+
+export interface GuardDecision {
+  allowed: boolean
+  /** If not allowed, which subagent to dispatch instead */
+  dispatchInstead?: string
+  /** Why this operation was blocked */
+  reason: string
+  /** Suggested action */
+  suggestion: string
+}
+
+export class MainAgentGuard {
+  private config: GuardConfig
+  private logger: Logger
+  private tokensUsed: number = 0
+
+  constructor(config: GuardConfig, logger: Logger) {
+    this.config = config
+    this.logger = logger
+  }
+
+  /**
+   * Check if an operation is allowed for Main Agent
+   * ALWAYS returns false for actual work - forces subagent dispatch
+   */
+  checkOperation(request: OperationRequest): GuardDecision {
+    // ALWAYS block file reads (except config files)
+    if (request.type === 'read' && this.isSourceFile(request.target)) {
+      return {
+        allowed: false,
+        dispatchInstead: 'explorer',
+        reason: 'Main Agent is prohibited from reading source files',
+        suggestion: 'Dispatch explorer subagent to read and summarize',
+      }
+    }
+
+    // ALWAYS block code search
+    if (request.type === 'search') {
+      return {
+        allowed: false,
+        dispatchInstead: 'explorer',
+        reason: 'Main Agent is prohibited from searching codebase',
+        suggestion: 'Dispatch explorer subagent with search query',
+      }
+    }
+
+    // ALWAYS block file writes
+    if (request.type === 'write') {
+      return {
+        allowed: false,
+        dispatchInstead: 'implementer',
+        reason: 'Main Agent is prohibited from writing files',
+        suggestion: 'Dispatch implementer subagent to write files',
+      }
+    }
+
+    // ALWAYS block edits (except tiny ones)
+    if (request.type === 'edit') {
+      if ((request.estimatedLines || 0) > 10) {
+        return {
+          allowed: false,
+          dispatchInstead: 'implementer',
+          reason: 'Main Agent is prohibited from editing large files',
+          suggestion: 'Dispatch implementer subagent for edits >10 lines',
+        }
+      }
+    }
+
+    // ALWAYS block long-running commands
+    if (request.type === 'run') {
+      if ((request.estimatedDuration || 0) > 30) {
+        return {
+          allowed: false,
+          dispatchInstead: 'runner',
+          reason: 'Main Agent is prohibited from long-running commands',
+          suggestion: 'Dispatch runner subagent for commands >30s',
+        }
+      }
+
+      // Block build/test commands
+      if (this.isBuildCommand(request.target)) {
+        return {
+          allowed: false,
+          dispatchInstead: 'runner',
+          reason: 'Main Agent is prohibited from build/test commands',
+          suggestion: 'Dispatch runner subagent for build/test',
+        }
+      }
+    }
+
+    // Check token budget
+    if (this.tokensUsed > this.config.tokenBudget) {
+      return {
+        allowed: false,
+        dispatchInstead: 'checkpoint',
+        reason: `Token budget exceeded: ${this.tokensUsed}/${this.config.tokenBudget}`,
+        suggestion: 'Force checkpoint: summarize and ask user to continue',
+      }
+    }
+
+    // Check embargo
+    if (this.config.embargoActive) {
+      return {
+        allowed: false,
+        dispatchInstead: 'coordinator',
+        reason: 'Embargo active: all work must be delegated to subagents',
+        suggestion: 'Wait for subagents to complete or dispatch coordinator',
+      }
+    }
+
+    // Only allow meta-operations (orchestration)
+    return {
+      allowed: true,
+      reason: 'Operation permitted for orchestration',
+      suggestion: 'Proceed with orchestration',
+    }
+  }
+
+  /**
+   * Assert that Main Agent is NOT doing work - throws if violated
+   */
+  assertNotDoingWork(operation: string): void {
+    const decision = this.checkOperation({
+      type: this.inferOperationType(operation),
+      target: operation,
+    })
+
+    if (!decision.allowed) {
+      const error = new Error(
+        `🚫 MAIN AGENT GUARD VIOLATION\n` +
+        `Operation: ${operation}\n` +
+        `Reason: ${decision.reason}\n` +
+        `Action: ${decision.suggestion}`
+      )
+      this.logger.error(error.message)
+      throw error
+    }
+  }
+
+  /**
+   * Track token usage
+   */
+  trackTokens(tokens: number): void {
+    this.tokensUsed += tokens
+    if (this.tokensUsed > this.config.tokenBudget * 0.8) {
+      this.logger.warn(
+        `⚠️  Token budget at ${Math.round((this.tokensUsed / this.config.tokenBudget) * 100)}%`
+      )
+    }
+  }
+
+  /**
+   * Activate embargo mode (post subagent dispatch)
+   */
+  activateEmbargo(): void {
+    this.config.embargoActive = true
+    this.logger.info('🔒 Embargo activated: Main Agent hands off to subagents')
+  }
+
+  /**
+   * Deactivate embargo (all subagents complete)
+   */
+  deactivateEmbargo(): void {
+    this.config.embargoActive = false
+    this.logger.info('🔓 Embargo lifted: Main Agent can orchestrate')
+  }
+
+  private isSourceFile(path?: string): boolean {
+    if (!path) return false
+    const sourceExts = ['.ts', '.js', '.tsx', '.jsx', '.py', '.java', '.go', '.rs', '.cpp', '.c', '.h']
+    return sourceExts.some((ext) => path.endsWith(ext))
+  }
+
+  private isBuildCommand(cmd?: string): boolean {
+    if (!cmd) return false
+    const buildCmds = ['npm run build', 'tsc', 'vite build', 'webpack', 'rollup', 'esbuild', 'jest', 'vitest', 'pytest']
+    return buildCmds.some((bc) => cmd.includes(bc))
+  }
+
+  private inferOperationType(operation: string): 'read' | 'search' | 'write' | 'run' | 'edit' {
+    if (operation.includes('read') || operation.includes('open')) return 'read'
+    if (operation.includes('search') || operation.includes('find') || operation.includes('grep')) return 'search'
+    if (operation.includes('write') || operation.includes('create')) return 'write'
+    if (operation.includes('edit') || operation.includes('modify')) return 'edit'
+    return 'run'
+  }
+}
+
+export function createMainAgentGuard(
+  config: Partial<GuardConfig> = {},
+  logger: Logger
+): MainAgentGuard {
+  return new MainAgentGuard(
+    {
+      tokenBudget: config.tokenBudget || 60000,
+      embargoActive: config.embargoActive || false,
+      prohibited: {
+        readSourceFiles: true,
+        searchCodebase: true,
+        writeFiles: true,
+        runBuildCommands: true,
+        runTests: true,
+        editLargeFiles: true,
+        longRunningTasks: true,
+        ...config.prohibited,
+      },
+    },
+    logger
+  )
+}

package/src/hooks/builtin/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Built-in hooks index
+ */
+export * as prePlan from './pre-plan.js'
+export * as postPlan from './post-plan.js'
+export * as preExecute from './pre-execute.js'
+export * as postExecute from './post-execute.js'
+export * as onError from './on-error.js'