@haoyiyin/workflow 0.2.0 → 0.2.3

package/src/router/guard.ts

@@ -0,0 +1,483 @@
+/**
+ * Main Agent Guard - enforces that the main agent NEVER does substantive work.
+ *
+ * The guard is the enforcement mechanism for the "thin dispatcher" pattern.
+ * When embargo is active, the main agent is blocked from everything except
+ * meta-operations (reading plan files, state files, and dispatching subagents).
+ *
+ * Usage:
+ * ```typescript
+ * const guard = MainAgentGuard.create({
+ *   defaultModel: 'haiku',
+ *   planningThreshold: 0.6,
+ *   maxMainAgentTokens: 10000,
+ *   autoRoute: true,
+ * })
+ *
+ * const check = guard.checkOperation('read-source', { path: 'src/main.ts' })
+ * if (!check.allowed) {
+ *   throw new Error(check.reason)
+ * }
+ * ```
+ */
+
+import type { RouterConfig } from './types.js'
+import { MAIN_AGENT_PROHIBITED } from './types.js'
+
+// ---------------------------------------------------------------------------
+// Guard-specific types
+// ---------------------------------------------------------------------------
+
+/** Result of a guard check. */
+export interface GuardCheckResult {
+  /** Whether the operation is permitted */
+  allowed: boolean
+  /** Human-readable reason for the decision */
+  reason: string
+  /** The specific rule that triggered (for debugging) */
+  rule?: string
+}
+
+/** Context passed to guard checks for richer decision-making. */
+export interface GuardContext {
+  /** The operation being attempted */
+  operation: string
+  /** Optional file path involved */
+  path?: string
+  /** Optional subagent ID if dispatching */
+  subagentId?: string
+}
+
+/** Snapshot of guard state for monitoring/debugging. */
+export interface GuardStatus {
+  embargoActive: boolean
+  pendingSubagents: string[]
+  violations: GuardViolation[]
+  prohibitedOperations: string[]
+  allowedPaths: string[]
+  forbiddenPaths: string[]
+}
+
+/** Recorded violation for audit trail. */
+export interface GuardViolation {
+  operation: string
+  path?: string
+  timestamp: Date
+  reason: string
+}
+
+/** Operation categories recognized by the guard. */
+export type GuardOperation =
+  | 'read-source'
+  | 'search-codebase'
+  | 'write-files'
+  | 'edit-files'
+  | 'run-build'
+  | 'run-tests'
+  | 'git-commit'
+  | 'git-push'
+  | 'read-diffs'
+  | 'long-running-task'
+  | 'dispatch-subagent'
+  | 'read-meta-file'
+  | 'relay-results'
+  | 'read-plan'
+  | 'read-state'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const META_OPERATIONS: ReadonlySet<string> = new Set([
+  'dispatch-subagent',
+  'relay-results',
+  'read-meta-file',
+  'read-plan',
+  'read-state',
+  'list-plans',
+  'check-state',
+  'read-config',
+])
+
+const ALWAYS_ALLOWED_PATHS: ReadonlyArray<string> = [
+  '.pi/plans/**',
+  '.pi/yi-workflow/state/**',
+  'SKILL.md',
+  'AGENTS.md',
+  'CLAUDE.md',
+  'package.json',
+  '.claude/**',
+]
+
+const ALWAYS_FORBIDDEN_PATHS: ReadonlyArray<string> = [
+  'src/**',
+  'lib/**',
+  'app/**',
+  'dist/**',
+  'node_modules/**',
+  '**/*.test.ts',
+  '**/*.spec.ts',
+  '**/*.test.tsx',
+  '**/*.spec.tsx',
+]
+
+/**
+ * Parses a simple glob pattern into a regex for matching.
+ * Supports ** for recursive matching and * for single-segment.
+ */
+function globToRegex(pattern: string): RegExp {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '___DOUBLESTAR___')
+    .replace(/\*/g, '[^/]*')
+    .replace(/___DOUBLESTAR___/g, '.*')
+
+  return new RegExp(`^${escaped}$`)
+}
+
+/** Check whether a path matches any of the given glob patterns. */
+function matchesAnyGlob(filePath: string, patterns: readonly string[]): boolean {
+  const normalized = filePath.replace(/^\.\//, '')
+  for (const pattern of patterns) {
+    const regex = globToRegex(pattern)
+    if (regex.test(normalized)) {
+      return true
+    }
+  }
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// MainAgentGuard
+// ---------------------------------------------------------------------------
+
+/**
+ * Enforces the "main agent as thin dispatcher" constraint.
+ *
+ * When embargoActive is true, the main agent is FORBIDDEN from doing
+ * ANY substantive work. It can only read meta-files and dispatch subagents.
+ */
+export class MainAgentGuard {
+  private readonly config: Readonly<RouterConfig>
+  private readonly violations: GuardViolation[]
+  private readonly pendingSubagents: Set<string>
+  private embargoActive: boolean
+  private tokensUsed: number
+
+  constructor(config: RouterConfig) {
+    this.config = Object.freeze({ ...config })
+    this.violations = []
+    this.pendingSubagents = new Set()
+    this.embargoActive = false
+    this.tokensUsed = 0
+  }
+
+  // -----------------------------------------------------------------------
+  // Factory methods
+  // -----------------------------------------------------------------------
+
+  /** Create a guard with embargo active (strictest mode). */
+  static createEmbargoAll(config: RouterConfig): MainAgentGuard {
+    const guard = new MainAgentGuard(config)
+    guard.activateEmbargo()
+    return guard
+  }
+
+  /** Create a guard with embargo lifted (use with extreme caution). */
+  static createDisabled(config: RouterConfig): MainAgentGuard {
+    return new MainAgentGuard(config)
+  }
+
+  /** Convenience: create with default config. */
+  static create(config: RouterConfig): MainAgentGuard {
+    return new MainAgentGuard(config)
+  }
+
+  // -----------------------------------------------------------------------
+  // Operation checks
+  // -----------------------------------------------------------------------
+
+  /**
+   * Check whether an operation is permitted for the main agent.
+   *
+   * @param operation - The operation being attempted
+   * @returns GuardCheckResult with allowed flag and reason
+   */
+  checkOperation(operation: GuardOperation): GuardCheckResult {
+    // If embargo is inactive, everything is permitted
+    if (!this.embargoActive) {
+      return {
+        allowed: true,
+        reason: 'Embargo is inactive - main agent may operate',
+        rule: 'embargo-off',
+      }
+    }
+
+    // Meta-operations are always allowed (they ARE the main agent's job)
+    if (META_OPERATIONS.has(operation)) {
+      return {
+        allowed: true,
+        reason: 'Meta-operation permitted for orchestration',
+        rule: 'meta-operation',
+      }
+    }
+
+    // Check against prohibited operations
+    const prohibitionMap: Record<string, boolean> = {
+      'read-source': MAIN_AGENT_PROHIBITED.readSourceFiles,
+      'search-codebase': MAIN_AGENT_PROHIBITED.searchCodebase,
+      'write-files': MAIN_AGENT_PROHIBITED.writeFiles,
+      'edit-files': MAIN_AGENT_PROHIBITED.writeFiles,
+      'run-build': MAIN_AGENT_PROHIBITED.runBuildCommands,
+      'run-tests': MAIN_AGENT_PROHIBITED.runTests,
+      'git-commit': MAIN_AGENT_PROHIBITED.writeFiles,
+      'git-push': MAIN_AGENT_PROHIBITED.writeFiles,
+      'read-diffs': MAIN_AGENT_PROHIBITED.readSourceFiles,
+      'long-running-task': MAIN_AGENT_PROHIBITED.longRunningTasks,
+    }
+
+    if (prohibitionMap[operation]) {
+      return {
+        allowed: false,
+        reason: `Operation "${operation}" is prohibited for the main agent`,
+        rule: 'prohibited-operation',
+      }
+    }
+
+    // Unknown operations under embargo: deny by default
+    return {
+      allowed: false,
+      reason: `Operation "${operation}" is not recognized and embargo is active`,
+      rule: 'unknown-operation-deny',
+    }
+  }
+
+  /**
+   * Check whether a file path is permitted to be read by the main agent.
+   */
+  checkReadPath(filePath: string): GuardCheckResult {
+    if (!this.embargoActive) {
+      return { allowed: true, reason: 'Embargo is inactive', rule: 'embargo-off' }
+    }
+
+    const normalized = filePath.replace(/^\.\//, '')
+
+    // Explicitly forbidden paths take precedence
+    if (matchesAnyGlob(normalized, ALWAYS_FORBIDDEN_PATHS)) {
+      return {
+        allowed: false,
+        reason: `Path "${filePath}" is forbidden under embargo`,
+        rule: 'forbidden-path',
+      }
+    }
+
+    // Check if path is in the allowed list
+    if (matchesAnyGlob(normalized, ALWAYS_ALLOWED_PATHS)) {
+      return { allowed: true, reason: 'Path is in the allowed list', rule: 'allowed-path' }
+    }
+
+    // Default: deny
+    return {
+      allowed: false,
+      reason: `Path "${filePath}" is not in the allowed list and embargo is active`,
+      rule: 'default-deny-path',
+    }
+  }
+
+  /**
+   * Comprehensive check combining operation and optional file path/context.
+   */
+  check(context: GuardContext): GuardCheckResult {
+    // Check the operation
+    const opCheck = this.checkOperation(context.operation as GuardOperation)
+    if (!opCheck.allowed) {
+      return opCheck
+    }
+
+    // If a path is provided, check read access
+    if (context.path) {
+      const pathCheck = this.checkReadPath(context.path)
+      if (!pathCheck.allowed) {
+        return pathCheck
+      }
+    }
+
+    // Check token budget
+    if (this.tokensUsed > this.config.maxMainAgentTokens) {
+      return {
+        allowed: false,
+        reason: `Token budget exceeded: ${this.tokensUsed}/${this.config.maxMainAgentTokens}`,
+        rule: 'token-budget-exceeded',
+      }
+    }
+
+    return { allowed: true, reason: 'All checks passed' }
+  }
+
+  /**
+   * Assert an operation is allowed. Throws if violated.
+   */
+  assertAllowed(context: GuardContext): void {
+    const result = this.check(context)
+    if (!result.allowed) {
+      const error = new Error(
+        `GUARD VIOLATION: ${result.reason}\n` +
+          `Operation: ${context.operation}\n` +
+          `${context.path ? `Path: ${context.path}\n` : ''}` +
+          `Rule: ${result.rule}`
+      )
+      this.violations.push({
+        operation: context.operation,
+        path: context.path,
+        timestamp: new Date(),
+        reason: result.reason,
+      })
+      throw error
+    }
+  }
+
+  /**
+   * Record a violation without throwing (for audit trail).
+   */
+  recordViolation(context: GuardContext): void {
+    const result = this.check(context)
+    this.violations.push({
+      operation: context.operation,
+      path: context.path,
+      timestamp: new Date(),
+      reason: result.reason,
+    })
+  }
+
+  // -----------------------------------------------------------------------
+  // Embargo control
+  // -----------------------------------------------------------------------
+
+  /** Activate embargo mode - main agent must delegate everything. */
+  activateEmbargo(): void {
+    this.embargoActive = true
+  }
+
+  /** Deactivate embargo mode - main agent regains limited capabilities. */
+  deactivateEmbargo(): void {
+    this.embargoActive = false
+  }
+
+  /** Check if embargo is currently active. */
+  isEmbargoActive(): boolean {
+    return this.embargoActive
+  }
+
+  // -----------------------------------------------------------------------
+  // Subagent tracking
+  // -----------------------------------------------------------------------
+
+  /** Register a dispatched subagent. */
+  registerSubagent(id: string): void {
+    this.pendingSubagents.add(id)
+  }
+
+  /** Mark a subagent as completed. */
+  completeSubagent(id: string): void {
+    this.pendingSubagents.delete(id)
+  }
+
+  /** Check if there are any subagents still pending. */
+  hasPendingSubagents(): boolean {
+    return this.pendingSubagents.size > 0
+  }
+
+  // -----------------------------------------------------------------------
+  // Token tracking
+  // -----------------------------------------------------------------------
+
+  /** Track token usage by the main agent. */
+  trackTokens(count: number): void {
+    this.tokensUsed += count
+  }
+
+  /** Get current token usage. */
+  getTokensUsed(): number {
+    return this.tokensUsed
+  }
+
+  /** Percentage of token budget consumed (0-1). */
+  tokenBudgetUtilization(): number {
+    return this.tokensUsed / this.config.maxMainAgentTokens
+  }
+
+  // -----------------------------------------------------------------------
+  // Status and reporting
+  // -----------------------------------------------------------------------
+
+  /** Current guard status snapshot. */
+  getStatus(): GuardStatus {
+    return {
+      embargoActive: this.embargoActive,
+      pendingSubagents: [...this.pendingSubagents],
+      violations: [...this.violations],
+      prohibitedOperations: Object.entries(MAIN_AGENT_PROHIBITED)
+        .filter(([, prohibited]) => prohibited)
+        .map(([key]) => key),
+      allowedPaths: [...ALWAYS_ALLOWED_PATHS],
+      forbiddenPaths: [...ALWAYS_FORBIDDEN_PATHS],
+    }
+  }
+
+  /**
+   * Generate the system prompt fragment that enforces guard rules.
+   * Injected into the main agent's system prompt.
+   */
+  generateSystemPromptFragment(): string {
+    if (!this.embargoActive) {
+      return `
+## Main Agent Guard: INACTIVE
+
+The guard is currently disabled. You may operate normally,
+but prefer delegation to subagents for substantive work where possible.
+`
+    }
+
+    const prohibited = Object.entries(MAIN_AGENT_PROHIBITED)
+      .filter(([, v]) => v)
+      .map(([k]) => `- ❌ ${k}`)
+      .join('\n')
+
+    const allowed = [...ALWAYS_ALLOWED_PATHS].map((p) => `- ${p}`).join('\n')
+
+    const pendingCount = this.pendingSubagents.size
+    const tokenPct = Math.round(this.tokenBudgetUtilization() * 100)
+
+    return `
+## CRITICAL: Main Agent Guard — EMBARGO ACTIVE
+
+You are a **thin dispatcher**, NOT an executor. Your only job:
+1. Classify the user's request
+2. Dispatch subagents to do the actual work
+3. Relay subagent results back to the user
+
+### Prohibited (NEVER do these):
+${prohibited}
+
+### Allowed to read ONLY:
+${allowed}
+
+### Status:
+- Token budget: ${tokenPct}% used (${this.tokensUsed}/${this.config.maxMainAgentTokens})
+- Pending subagents: ${pendingCount}
+- Violations recorded: ${this.violations.length}
+
+### Routing rules:
+- Trivial typo/whitespace → handle directly (1-2 char fix)
+- Small scoped change → dispatch quick-task agent
+- New feature / complex change → dispatch to-plan → then execute-plan
+- Bug/debugging → dispatch systematic-debugging agent
+- Code review → dispatch review-diff agent
+- Research/exploration → dispatch explorer agent
+- TDD work → dispatch tdd agent
+- Everything else → dispatch general subagent
+
+### NEVER execute any task yourself. ALWAYS use the Agent tool.
+`
+  }
+}

package/src/router/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Router module index
+ *
+ * The router ensures ALL user requests go through subagents.
+ * Main Agent is a "thin dispatcher" — it NEVER executes tasks itself.
+ */
+
+export type {
+  IntentClassification,
+  IntentType,
+  RouterConfig,
+  RoutingDecision,
+  SubagentContract,
+  PermissionSet,
+  RouterInput,
+  RouterOutput,
+  MAIN_AGENT_PROHIBITED,
+  ROUTE_KEYWORDS,
+} from './types.js'
+
+export { createRouter } from './router.js'
+export type { Router } from './router.js'

package/src/router/router.ts

@@ -0,0 +1,108 @@
+/**
+ * Router - wires up classification and guard into a single dispatch pipeline.
+ *
+ * The createRouter factory produces an object that:
+ * 1. Classifies user requests
+ * 2. Validates against main-agent guard rules
+ * 3. Produces a routing decision (what subagent to dispatch)
+ *
+ * Usage:
+ * ```typescript
+ * import { createRouter } from './router/router.js'
+ * import type { RouterConfig } from './router/types.js'
+ *
+ * const config: RouterConfig = {
+ *   defaultModel: 'haiku',
+ *   planningThreshold: 0.6,
+ *   maxMainAgentTokens: 10000,
+ *   autoRoute: true,
+ * }
+ *
+ * const router = createRouter(config)
+ * const output = router.route({
+ *   request: "Fix the typo in src/utils.ts",
+ *   planFileExists: false,
+ *   isExecutingPlan: false,
+ *   hasUncommittedChanges: true,
+ *   mentionedFiles: ['src/utils.ts'],
+ * })
+ * // output.classification.type === 'quick-task'
+ * ```
+ */
+
+import type { RouterConfig, RouterInput, RouterOutput } from './types.js'
+import { RequestClassifier } from './classifier.js'
+import type { ClassificationContext } from './classifier.js'
+import { MainAgentGuard } from './guard.js'
+
+/**
+ * High-level router interface.
+ */
+export interface Router {
+  /** Classify a request and produce a routing decision */
+  route: (input: RouterInput) => RouterOutput
+
+  /** Get the underlying classifier */
+  classifier: RequestClassifier
+
+  /** Get the underlying guard */
+  guard: MainAgentGuard
+
+  /** Generate the system prompt fragment for the main agent */
+  generateSystemPrompt: () => string
+
+  /** Check if an operation is allowed under current guard state */
+  isOperationAllowed: (operation: string) => boolean
+}
+
+/**
+ * Create a router with the given configuration.
+ *
+ * Wires together:
+ * - RequestClassifier: analyzes user input, determines intent
+ * - MainAgentGuard: enforces thin-dispatcher constraints
+ */
+export function createRouter(config: RouterConfig): Router {
+  const classifier = new RequestClassifier(config)
+  const guard = new MainAgentGuard(config)
+
+  function route(input: RouterInput): RouterOutput {
+    const context: ClassificationContext = {
+      planFileExists: input.planFileExists,
+      isExecutingPlan: input.isExecutingPlan,
+      hasUncommittedChanges: input.hasUncommittedChanges,
+      currentBranch: input.currentBranch,
+      mentionedFiles: input.mentionedFiles,
+    }
+
+    const result = classifier.classify(input.request, context)
+
+    // Activate embargo after routing (unless trivial edit)
+    if (result.classification.type !== 'quick-task') {
+      guard.activateEmbargo()
+    }
+
+    return {
+      classification: result.classification,
+      routing: result.routing,
+      confidence: result.confidence,
+      matchedRule: result.matchedRule,
+    }
+  }
+
+  function generateSystemPrompt(): string {
+    return guard.generateSystemPromptFragment()
+  }
+
+  function isOperationAllowed(operation: string): boolean {
+    return guard.checkOperation(operation as Parameters<typeof guard.checkOperation>[0]).allowed
+  }
+
+  return {
+    route,
+    classifier,
+    guard,
+    generateSystemPrompt,
+    isOperationAllowed,
+  }
+}