@haoyiyin/workflow 0.2.0 → 0.2.3

package/src/router/classifier.ts

@@ -0,0 +1,610 @@
+/**
+ * Request Classifier - determines what type of subagent should handle a request.
+ *
+ * Analyzes user request text and contextual signals to produce an
+ * IntentClassification, then builds a RoutingDecision with the appropriate
+ * SubagentConfig and SubagentContract.
+ *
+ * Classification follows a priority-ordered chain:
+ *   1. execute (plan file exists / mid-execution)
+ *   2. quick-task (trivial typo/whitespace, small scoped change)
+ *   3. review (code review request)
+ *   4. debug (root cause analysis)
+ *   5. tdd (test-driven development request)
+ *   6. plan (new feature / significant change)
+ *   7. general (catch-all)
+ */
+
+import type { SubagentConfig } from '../agents/types.js'
+import type {
+  IntentType,
+  IntentClassification,
+  RoutingDecision,
+  SubagentContract,
+  PermissionSet,
+  RouterConfig,
+} from './types.js'
+import { ROUTE_KEYWORDS } from './types.js'
+
+// ---------------------------------------------------------------------------
+// Classification context
+// ---------------------------------------------------------------------------
+
+/** Context signals used alongside the raw request text. */
+export interface ClassificationContext {
+  /** Whether a plan file already exists for this task/feature */
+  planFileExists: boolean
+  /** Whether the user is in the middle of executing a plan */
+  isExecutingPlan: boolean
+  /** Whether there are uncommitted changes in the working tree */
+  hasUncommittedChanges: boolean
+  /** The current branch name (if available) */
+  currentBranch?: string
+  /** Any files the user explicitly mentioned */
+  mentionedFiles: string[]
+}
+
+/** Extended classification result with diagnostic metadata. */
+export interface ClassifierResult {
+  /** The intent classification */
+  classification: IntentClassification
+  /** The full routing decision (contract + config) */
+  routing: RoutingDecision
+  /** Confidence score 0-1 */
+  confidence: number
+  /** Which rule matched */
+  matchedRule: string
+  /** Alternative classifications that were considered */
+  alternatives: Array<{ type: IntentType; confidence: number }>
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Token budget recommendations by intent type (in thousands). */
+const TOKEN_BUDGETS: Record<IntentType, number> = {
+  plan: 64,
+  'quick-task': 32,
+  execute: 64,
+  review: 32,
+  debug: 64,
+  tdd: 64,
+  general: 32,
+}
+
+/** Subagent roles mapped from intent types. */
+const SUBAGENT_ROLES: Record<IntentType, SubagentConfig['role']> = {
+  plan: 'planner',
+  'quick-task': 'implementer',
+  execute: 'implementer',
+  review: 'reviewer',
+  debug: 'debugger',
+  tdd: 'implementer',
+  general: 'general',
+}
+
+/** Default permissions by intent type. */
+const SUBAGENT_PERMISSIONS: Record<IntentType, PermissionSet> = {
+  plan: {
+    readFiles: true,
+    searchCode: true,
+    runCommands: false,
+    writeFiles: true,
+    gitOperations: false,
+  },
+  'quick-task': {
+    readFiles: true,
+    searchCode: true,
+    runCommands: true,
+    writeFiles: true,
+    gitOperations: false,
+  },
+  execute: {
+    readFiles: true,
+    searchCode: true,
+    runCommands: true,
+    writeFiles: true,
+    gitOperations: true,
+  },
+  review: {
+    readFiles: true,
+    searchCode: true,
+    runCommands: false,
+    writeFiles: false,
+    gitOperations: false,
+  },
+  debug: {
+    readFiles: true,
+    searchCode: true,
+    runCommands: true,
+    writeFiles: false,
+    gitOperations: false,
+  },
+  tdd: {
+    readFiles: true,
+    searchCode: true,
+    runCommands: true,
+    writeFiles: true,
+    gitOperations: false,
+  },
+  general: {
+    readFiles: true,
+    searchCode: true,
+    runCommands: false,
+    writeFiles: false,
+    gitOperations: false,
+  },
+}
+
+/** Whether a given intent type uses worktree isolation. */
+const SUBAGENT_ISOLATION: Partial<Record<IntentType, 'worktree'>> = {
+  execute: 'worktree',
+  plan: 'worktree',
+}
+
+// ---------------------------------------------------------------------------
+// Decision builders
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an IntentClassification from type and metadata.
+ */
+function buildClassification(
+  type: IntentType,
+  confidence: number,
+  reasoning: string
+): IntentClassification {
+  return {
+    type,
+    confidence,
+    reasoning,
+    suggestedAgent: SUBAGENT_ROLES[type],
+  }
+}
+
+/**
+ * Build a RoutingDecision: subagent config + contract + async flag.
+ */
+function buildRouting(
+  type: IntentType,
+  prompt: string,
+  config: RouterConfig,
+  owns: string[] = [],
+  reads: string[] = []
+): RoutingDecision {
+  const subagentConfig: SubagentConfig = {
+    role: SUBAGENT_ROLES[type],
+    model: config.defaultModel,
+    isolation: SUBAGENT_ISOLATION[type],
+    tokenBudget: TOKEN_BUDGETS[type] * 1000,
+  }
+
+  const contract: SubagentContract = {
+    permissions: { ...SUBAGENT_PERMISSIONS[type] },
+    prompt,
+    owns,
+    reads,
+  }
+
+  return {
+    subagent: subagentConfig,
+    contract,
+    async: type !== 'quick-task',
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pattern matchers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if request matches a trivial edit (typo, whitespace, single-line fix).
+ * The ONE exception to full delegation — quick-task can handle directly.
+ */
+function matchTrivialEdit(
+  request: string
+): { type: IntentType; confidence: number; reasoning: string } | null {
+  const normalized = request.toLowerCase().trim()
+
+  const patterns = [
+    /^fix\s+(a\s+)?typo\b/i,
+    /^fix\s+(a\s+)?spell(ing)?\s+(error|mistake)\b/i,
+    /^fix\s+whitespace\b/i,
+    /^remove\s+trailing\s+whitespace\b/i,
+    /^fix\s+lint(ing)?\s+(error|warning)\b/i,
+    /^format\s+(this|a|the)\s+(file|code)\b/i,
+    /^(add|remove)\s+(a\s+)?missing\s+semicolon/i,
+    /^change\s+(a\s+)?single\s+(character|char|letter)\b/i,
+    /^rename\s+(a\s+)?single\s+variable\b/i,
+  ]
+
+  for (const p of patterns) {
+    if (p.test(normalized)) {
+      return {
+        type: 'quick-task',
+        confidence: 0.85,
+        reasoning: 'Trivial single-line fix — route to quick-task',
+      }
+    }
+  }
+
+  // Short request referencing a specific line number
+  if (normalized.length < 60 && /\bline\s+\d+\b/.test(normalized)) {
+    return {
+      type: 'quick-task',
+      confidence: 0.7,
+      reasoning: 'Very short request references a specific line number',
+    }
+  }
+
+  return null
+}
+
+/**
+ * Check if request is a code review.
+ */
+function matchReview(
+  request: string
+): { type: IntentType; confidence: number; reasoning: string } | null {
+  const keywords = ROUTE_KEYWORDS.review
+  const normalized = request.toLowerCase().trim()
+
+  for (const kw of keywords) {
+    if (normalized.includes(kw)) {
+      return {
+        type: 'review',
+        confidence: 0.9,
+        reasoning: `Request matches review keyword: "${kw}"`,
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Check if request is about debugging / root cause analysis.
+ */
+function matchDebug(
+  request: string
+): { type: IntentType; confidence: number; reasoning: string } | null {
+  const keywords = ROUTE_KEYWORDS.debug
+  const normalized = request.toLowerCase().trim()
+
+  for (const kw of keywords) {
+    if (normalized.includes(kw)) {
+      return {
+        type: 'debug',
+        confidence: 0.85,
+        reasoning: `Request matches debug keyword: "${kw}"`,
+      }
+    }
+  }
+
+  // Broader debug patterns
+  const broadPatterns = [
+    /\bwhy\s+(is|does|am\s*i|are)\b.*\b(error|fail|break|crash|wrong|bug)\b/i,
+    /\b(stack\s*trace|backtrace)\b/i,
+    /\binvestigate\s+(the|a|this|an)\s+(issue|error|bug|crash|problem)\b/i,
+  ]
+
+  for (const p of broadPatterns) {
+    if (p.test(normalized)) {
+      return {
+        type: 'debug',
+        confidence: 0.75,
+        reasoning: 'Request matches broad debug pattern',
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Check if request is about test-driven development.
+ */
+function matchTdd(
+  request: string
+): { type: IntentType; confidence: number; reasoning: string } | null {
+  const keywords = ROUTE_KEYWORDS.tdd
+  const normalized = request.toLowerCase().trim()
+
+  for (const kw of keywords) {
+    if (normalized.includes(kw)) {
+      return {
+        type: 'tdd',
+        confidence: 0.9,
+        reasoning: `Request matches TDD keyword: "${kw}"`,
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Check if request needs a full plan (complex, multi-step).
+ */
+function matchPlan(
+  request: string
+): { type: IntentType; confidence: number; reasoning: string } | null {
+  const keywords = ROUTE_KEYWORDS.plan
+  const normalized = request.toLowerCase().trim()
+
+  for (const kw of keywords) {
+    if (normalized.includes(kw)) {
+      return {
+        type: 'plan',
+        confidence: 0.85,
+        reasoning: `Request matches planning keyword: "${kw}"`,
+      }
+    }
+  }
+
+  // Additional complexity indicators
+  const planIndicators = [
+    /\b(complex|major|big|large|significant)\s+(change|refactor|update|feature)\b/i,
+    /\b(multi[-\s]?(file|step|phase)|several\s+files?)\b/i,
+    /\b(end[-\s]?to[-\s]?end|full[-\s]?stack)\b/i,
+    /\b(from\s+scratch|restructure|reorgani[sz]e|rearchitect)\b/i,
+  ]
+
+  for (const p of planIndicators) {
+    if (p.test(normalized)) {
+      return {
+        type: 'plan',
+        confidence: 0.75,
+        reasoning: 'Request contains complexity indicators — planning likely needed',
+      }
+    }
+  }
+
+  // Long requests (>500 chars) often need planning
+  if (normalized.length > 500) {
+    return {
+      type: 'plan',
+      confidence: 0.55,
+      reasoning: 'Long request suggests complex, multi-step work',
+    }
+  }
+
+  return null
+}
+
+/**
+ * Check if request is a read-only / informational question.
+ */
+function matchGeneral(
+  request: string
+): { type: IntentType; confidence: number; reasoning: string } | null {
+  const keywords = ROUTE_KEYWORDS.general
+  const normalized = request.toLowerCase().trim()
+
+  for (const kw of keywords) {
+    if (normalized.includes(kw)) {
+      return {
+        type: 'general',
+        confidence: 0.7,
+        reasoning: `Request matches general keyword: "${kw}"`,
+      }
+    }
+  }
+
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// RequestClassifier
+// ---------------------------------------------------------------------------
+
+/**
+ * Analyzes user requests and produces routing decisions.
+ *
+ * Classification runs through a priority-ordered chain:
+ * 1. Context-based: plan exists → 'execute'
+ * 2. Pattern-based: trivial-edit → quick-task, review, debug, tdd, plan, general
+ * 3. Fallback: 'general'
+ *
+ * Usage:
+ * ```typescript
+ * const classifier = new RequestClassifier(config)
+ * const result = classifier.classify("Fix the typo in src/utils.ts", {
+ *   planFileExists: false,
+ *   isExecutingPlan: false,
+ *   hasUncommittedChanges: true,
+ *   mentionedFiles: ['src/utils.ts'],
+ * })
+ * // result.classification.type === 'quick-task'
+ * ```
+ */
+export class RequestClassifier {
+  private readonly config: Readonly<RouterConfig>
+
+  /** Priority-ordered classification rules. */
+  private readonly rules: ReadonlyArray<{
+    name: string
+    match: (
+      request: string,
+      ctx: ClassificationContext
+    ) => { type: IntentType; confidence: number; reasoning: string } | null
+  }>
+
+  constructor(config: RouterConfig) {
+    this.config = Object.freeze({ ...config })
+
+    this.rules = Object.freeze([
+      { name: 'context-execute', match: (_req, ctx) => this.checkContextExecute(ctx) },
+      { name: 'trivial-edit', match: (req, _ctx) => matchTrivialEdit(req) },
+      { name: 'review', match: (req, _ctx) => matchReview(req) },
+      { name: 'debug', match: (req, _ctx) => matchDebug(req) },
+      { name: 'tdd', match: (req, _ctx) => matchTdd(req) },
+      { name: 'plan', match: (req, _ctx) => matchPlan(req) },
+      { name: 'general-keywords', match: (req, _ctx) => matchGeneral(req) },
+    ])
+  }
+
+  /**
+   * If a plan file exists or we are mid-execution, route to execute.
+   */
+  private checkContextExecute(
+    ctx: ClassificationContext
+  ): { type: IntentType; confidence: number; reasoning: string } | null {
+    if (ctx.isExecutingPlan) {
+      return {
+        type: 'execute',
+        confidence: 0.95,
+        reasoning: 'Currently executing a plan — continue with execute agent',
+      }
+    }
+    if (ctx.planFileExists) {
+      return {
+        type: 'execute',
+        confidence: 0.8,
+        reasoning: 'A plan file already exists for this task',
+      }
+    }
+    return null
+  }
+
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Classify a user request and produce a full routing decision.
+   *
+   * @param request - Raw user request text
+   * @param context - Contextual signals to improve accuracy
+   * @returns ClassifierResult with classification metadata and routing decision
+   */
+  classify(request: string, context: ClassificationContext): ClassifierResult {
+    if (!request || request.trim().length === 0) {
+      const classification = buildClassification('general', 0.1, 'Empty request')
+      const routing = buildRouting('general', request, this.config)
+      return {
+        classification,
+        routing,
+        confidence: 0.1,
+        matchedRule: 'empty-request',
+        alternatives: [],
+      }
+    }
+
+    // Run through the priority-ordered rule chain
+    for (const rule of this.rules) {
+      try {
+        const match = rule.match(request, context)
+        if (match) {
+          const classification = buildClassification(match.type, match.confidence, match.reasoning)
+          const routing = buildRouting(match.type, request, this.config)
+          return {
+            classification,
+            routing,
+            confidence: match.confidence,
+            matchedRule: rule.name,
+            alternatives: this.computeAlternatives(match.type, match.confidence),
+          }
+        }
+      } catch (error) {
+        console.error(`Classifier rule "${rule.name}" failed:`, error)
+      }
+    }
+
+    // Fallback: general
+    const classification = buildClassification(
+      'general',
+      0.3,
+      'No specific pattern matched — routing to general agent'
+    )
+    const routing = buildRouting('general', request, this.config)
+    return {
+      classification,
+      routing,
+      confidence: 0.3,
+      matchedRule: 'fallback',
+      alternatives: [
+        { type: 'plan', confidence: 0.3 },
+        { type: 'quick-task', confidence: 0.2 },
+        { type: 'debug', confidence: 0.2 },
+      ],
+    }
+  }
+
+  /**
+   * Classify intent only (without building a full routing decision).
+   */
+  classifyIntent(request: string, context: ClassificationContext): IntentClassification {
+    return this.classify(request, context).classification
+  }
+
+  /**
+   * Produce just the routing decision.
+   */
+  route(request: string, context: ClassificationContext): RoutingDecision {
+    return this.classify(request, context).routing
+  }
+
+  // -----------------------------------------------------------------------
+  // Configuration queries
+  // -----------------------------------------------------------------------
+
+  /** Get recommended token budget for an intent type. */
+  getTokenBudget(type: IntentType): number {
+    return TOKEN_BUDGETS[type] * 1000
+  }
+
+  /** Get subagent role for an intent type. */
+  getSubagentRole(type: IntentType): SubagentConfig['role'] {
+    return SUBAGENT_ROLES[type]
+  }
+
+  /** Get default permissions for an intent type (returns a copy). */
+  getSubagentPermissions(type: IntentType): PermissionSet {
+    return { ...SUBAGENT_PERMISSIONS[type] }
+  }
+
+  // -----------------------------------------------------------------------
+  // Reporting
+  // -----------------------------------------------------------------------
+
+  /**
+   * Generate a human-readable classification summary for logging.
+   */
+  describeClassification(result: ClassifierResult): string {
+    const { classification, confidence, matchedRule, routing } = result
+    return [
+      `Intent: ${classification.type}`,
+      `Confidence: ${(confidence * 100).toFixed(0)}%`,
+      `Rule: ${matchedRule}`,
+      `Agent: ${classification.suggestedAgent}`,
+      `Reason: ${classification.reasoning}`,
+      `Async: ${routing.async}`,
+      routing.subagent.isolation ? `Isolation: ${routing.subagent.isolation}` : null,
+    ]
+      .filter(Boolean)
+      .join(' | ')
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+
+  /**
+   * Compute alternative classifications based on the winning type.
+   */
+  private computeAlternatives(
+    winningType: IntentType,
+    winningConfidence: number
+  ): Array<{ type: IntentType; confidence: number }> {
+    const remaining = 1 - winningConfidence
+    const allTypes: IntentType[] = ['plan', 'quick-task', 'execute', 'review', 'debug', 'tdd', 'general']
+    const others = allTypes.filter((t) => t !== winningType)
+
+    return others.slice(0, 3).map((type, i) => ({
+      type,
+      confidence: Math.round((remaining / (others.length - i)) * 100) / 100,
+    }))
+  }
+}