@haoyiyin/workflow 0.2.0

package/dist/src/router/classifier.js

@@ -0,0 +1,476 @@
+/**
+ * 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 { ROUTE_KEYWORDS } from './types.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Token budget recommendations by intent type (in thousands). */
+const TOKEN_BUDGETS = {
+    plan: 64,
+    'quick-task': 32,
+    execute: 64,
+    review: 32,
+    debug: 64,
+    tdd: 64,
+    general: 32,
+};
+/** Subagent roles mapped from intent types. */
+const SUBAGENT_ROLES = {
+    plan: 'planner',
+    'quick-task': 'implementer',
+    execute: 'implementer',
+    review: 'reviewer',
+    debug: 'debugger',
+    tdd: 'implementer',
+    general: 'general',
+};
+/** Default permissions by intent type. */
+const SUBAGENT_PERMISSIONS = {
+    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 = {
+    execute: 'worktree',
+    plan: 'worktree',
+};
+// ---------------------------------------------------------------------------
+// Decision builders
+// ---------------------------------------------------------------------------
+/**
+ * Build an IntentClassification from type and metadata.
+ */
+function buildClassification(type, confidence, reasoning) {
+    return {
+        type,
+        confidence,
+        reasoning,
+        suggestedAgent: SUBAGENT_ROLES[type],
+    };
+}
+/**
+ * Build a RoutingDecision: subagent config + contract + async flag.
+ */
+function buildRouting(type, prompt, config, owns = [], reads = []) {
+    const subagentConfig = {
+        role: SUBAGENT_ROLES[type],
+        model: config.defaultModel,
+        isolation: SUBAGENT_ISOLATION[type],
+        tokenBudget: TOKEN_BUDGETS[type] * 1000,
+    };
+    const contract = {
+        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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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 {
+    config;
+    /** Priority-ordered classification rules. */
+    rules;
+    constructor(config) {
+        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.
+     */
+    checkContextExecute(ctx) {
+        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, context) {
+        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, context) {
+        return this.classify(request, context).classification;
+    }
+    /**
+     * Produce just the routing decision.
+     */
+    route(request, context) {
+        return this.classify(request, context).routing;
+    }
+    // -----------------------------------------------------------------------
+    // Configuration queries
+    // -----------------------------------------------------------------------
+    /** Get recommended token budget for an intent type. */
+    getTokenBudget(type) {
+        return TOKEN_BUDGETS[type] * 1000;
+    }
+    /** Get subagent role for an intent type. */
+    getSubagentRole(type) {
+        return SUBAGENT_ROLES[type];
+    }
+    /** Get default permissions for an intent type (returns a copy). */
+    getSubagentPermissions(type) {
+        return { ...SUBAGENT_PERMISSIONS[type] };
+    }
+    // -----------------------------------------------------------------------
+    // Reporting
+    // -----------------------------------------------------------------------
+    /**
+     * Generate a human-readable classification summary for logging.
+     */
+    describeClassification(result) {
+        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.
+     */
+    computeAlternatives(winningType, winningConfidence) {
+        const remaining = 1 - winningConfidence;
+        const allTypes = ['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,
+        }));
+    }
+}
+//# sourceMappingURL=classifier.js.map

package/dist/src/router/classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.js","sourceRoot":"","sources":["../../../src/router/classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAkC3C,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,kEAAkE;AAClE,MAAM,aAAa,GAA+B;IAChD,IAAI,EAAE,EAAE;IACR,YAAY,EAAE,EAAE;IAChB,OAAO,EAAE,EAAE;IACX,MAAM,EAAE,EAAE;IACV,KAAK,EAAE,EAAE;IACT,GAAG,EAAE,EAAE;IACP,OAAO,EAAE,EAAE;CACZ,CAAA;AAED,+CAA+C;AAC/C,MAAM,cAAc,GAA+C;IACjE,IAAI,EAAE,SAAS;IACf,YAAY,EAAE,aAAa;IAC3B,OAAO,EAAE,aAAa;IACtB,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,UAAU;IACjB,GAAG,EAAE,aAAa;IAClB,OAAO,EAAE,SAAS;CACnB,CAAA;AAED,0CAA0C;AAC1C,MAAM,oBAAoB,GAAsC;IAC9D,IAAI,EAAE;QACJ,SAAS,EAAE,IAAI;QACf,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,KAAK;QAClB,UAAU,EAAE,IAAI;QAChB,aAAa,EAAE,KAAK;KACrB;IACD,YAAY,EAAE;QACZ,SAAS,EAAE,IAAI;QACf,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,IAAI;QAChB,aAAa,EAAE,KAAK;KACrB;IACD,OAAO,EAAE;QACP,SAAS,EAAE,IAAI;QACf,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,IAAI;QAChB,aAAa,EAAE,IAAI;KACpB;IACD,MAAM,EAAE;QACN,SAAS,EAAE,IAAI;QACf,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,KAAK;QAClB,UAAU,EAAE,KAAK;QACjB,aAAa,EAAE,KAAK;KACrB;IACD,KAAK,EAAE;QACL,SAAS,EAAE,IAAI;QACf,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,KAAK;QACjB,aAAa,EAAE,KAAK;KACrB;IACD,GAAG,EAAE;QACH,SAAS,EAAE,IAAI;QACf,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,IAAI;QAChB,aAAa,EAAE,KAAK;KACrB;IACD,OAAO,EAAE;QACP,SAAS,EAAE,IAAI;QACf,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,KAAK;QAClB,UAAU,EAAE,KAAK;QACjB,aAAa,EAAE,KAAK;KACrB;CACF,CAAA;AAED,2DAA2D;AAC3D,MAAM,kBAAkB,GAA4C;IAClE,OAAO,EAAE,UAAU;IACnB,IAAI,EAAE,UAAU;CACjB,CAAA;AAED,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;GAEG;AACH,SAAS,mBAAmB,CAC1B,IAAgB,EAChB,UAAkB,EAClB,SAAiB;IAEjB,OAAO;QACL,IAAI;QACJ,UAAU;QACV,SAAS;QACT,cAAc,EAAE,cAAc,CAAC,IAAI,CAAC;KACrC,CAAA;AACH,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CACnB,IAAgB,EAChB,MAAc,EACd,MAAoB,EACpB,OAAiB,EAAE,EACnB,QAAkB,EAAE;IAEpB,MAAM,cAAc,GAAmB;QACrC,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC,YAAY;QAC1B,SAAS,EAAE,kBAAkB,CAAC,IAAI,CAAC;QACnC,WAAW,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI;KACxC,CAAA;IAED,MAAM,QAAQ,GAAqB;QACjC,WAAW,EAAE,EAAE,GAAG,oBAAoB,CAAC,IAAI,CAAC,EAAE;QAC9C,MAAM;QACN,IAAI;QACJ,KAAK;KACN,CAAA;IAED,OAAO;QACL,QAAQ,EAAE,cAAc;QACxB,QAAQ;QACR,KAAK,EAAE,IAAI,KAAK,YAAY;KAC7B,CAAA;AACH,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,gBAAgB,CACvB,OAAe;IAEf,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAA;IAE/C,MAAM,QAAQ,GAAG;QACf,uBAAuB;QACvB,gDAAgD;QAChD,sBAAsB;QACtB,oCAAoC;QACpC,wCAAwC;QACxC,yCAAyC;QACzC,6CAA6C;QAC7C,sDAAsD;QACtD,uCAAuC;KACxC,CAAA;IAED,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACvB,OAAO;gBACL,IAAI,EAAE,YAAY;gBAClB,UAAU,EAAE,IAAI;gBAChB,SAAS,EAAE,+CAA+C;aAC3D,CAAA;QACH,CAAC;IACH,CAAC;IAED,mDAAmD;IACnD,IAAI,UAAU,CAAC,MAAM,GAAG,EAAE,IAAI,gBAAgB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAChE,OAAO;YACL,IAAI,EAAE,YAAY;YAClB,UAAU,EAAE,GAAG;YACf,SAAS,EAAE,sDAAsD;SAClE,CAAA;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;GAEG;AACH,SAAS,WAAW,CAClB,OAAe;IAEf,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAA;IACtC,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAA;IAE/C,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5B,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,GAAG;gBACf,SAAS,EAAE,oCAAoC,EAAE,GAAG;aACrD,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CACjB,OAAe;IAEf,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAA;IACrC,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAA;IAE/C,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5B,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,UAAU,EAAE,IAAI;gBAChB,SAAS,EAAE,mCAAmC,EAAE,GAAG;aACpD,CAAA;QACH,CAAC;IACH,CAAC;IAED,yBAAyB;IACzB,MAAM,aAAa,GAAG;QACpB,yEAAyE;QACzE,gCAAgC;QAChC,sEAAsE;KACvE,CAAA;IAED,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QAC9B,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACvB,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,UAAU,EAAE,IAAI;gBAChB,SAAS,EAAE,qCAAqC;aACjD,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CACf,OAAe;IAEf,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAA;IACnC,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAA;IAE/C,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5B,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,UAAU,EAAE,GAAG;gBACf,SAAS,EAAE,iCAAiC,EAAE,GAAG;aAClD,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAChB,OAAe;IAEf,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAA;IACpC,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAA;IAE/C,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5B,OAAO;gBACL,IAAI,EAAE,MAAM;gBACZ,UAAU,EAAE,IAAI;gBAChB,SAAS,EAAE,sCAAsC,EAAE,GAAG;aACvD,CAAA;QACH,CAAC;IACH,CAAC;IAED,mCAAmC;IACnC,MAAM,cAAc,GAAG;QACrB,+EAA+E;QAC/E,sDAAsD;QACtD,6CAA6C;QAC7C,6DAA6D;KAC9D,CAAA;IAED,KAAK,MAAM,CAAC,IAAI,cAAc,EAAE,CAAC;QAC/B,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACvB,OAAO;gBACL,IAAI,EAAE,MAAM;gBACZ,UAAU,EAAE,IAAI;gBAChB,SAAS,EAAE,iEAAiE;aAC7E,CAAA;QACH,CAAC;IACH,CAAC;IAED,iDAAiD;IACjD,IAAI,UAAU,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAC5B,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,UAAU,EAAE,IAAI;YAChB,SAAS,EAAE,gDAAgD;SAC5D,CAAA;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CACnB,OAAe;IAEf,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAA;IACvC,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAA;IAE/C,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC5B,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,UAAU,EAAE,GAAG;gBACf,SAAS,EAAE,qCAAqC,EAAE,GAAG;aACtD,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,iBAAiB;IACX,MAAM,CAAwB;IAE/C,6CAA6C;IAC5B,KAAK,CAMpB;IAEF,YAAY,MAAoB;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,CAAA;QAE1C,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;YACzB,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE;YAChF,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE;YACrE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE;YAC1D,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;YACxD,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;YACpD,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE;YACtD,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE;SACtE,CAAC,CAAA;IACJ,CAAC;IAED;;OAEG;IACK,mBAAmB,CACzB,GAA0B;QAE1B,IAAI,GAAG,CAAC,eAAe,EAAE,CAAC;YACxB,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,UAAU,EAAE,IAAI;gBAChB,SAAS,EAAE,0DAA0D;aACtE,CAAA;QACH,CAAC;QACD,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;YACvB,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,UAAU,EAAE,GAAG;gBACf,SAAS,EAAE,0CAA0C;aACtD,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,0EAA0E;IAC1E,aAAa;IACb,0EAA0E;IAE1E;;;;;;OAMG;IACH,QAAQ,CAAC,OAAe,EAAE,OAA8B;QACtD,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5C,MAAM,cAAc,GAAG,mBAAmB,CAAC,SAAS,EAAE,GAAG,EAAE,eAAe,CAAC,CAAA;YAC3E,MAAM,OAAO,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;YAC7D,OAAO;gBACL,cAAc;gBACd,OAAO;gBACP,UAAU,EAAE,GAAG;gBACf,WAAW,EAAE,eAAe;gBAC5B,YAAY,EAAE,EAAE;aACjB,CAAA;QACH,CAAC;QAED,8CAA8C;QAC9C,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;gBAC1C,IAAI,KAAK,EAAE,CAAC;oBACV,MAAM,cAAc,GAAG,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;oBACzF,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;oBAC9D,OAAO;wBACL,cAAc;wBACd,OAAO;wBACP,UAAU,EAAE,KAAK,CAAC,UAAU;wBAC5B,WAAW,EAAE,IAAI,CAAC,IAAI;wBACtB,YAAY,EAAE,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC;qBACrE,CAAA;gBACH,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,oBAAoB,IAAI,CAAC,IAAI,WAAW,EAAE,KAAK,CAAC,CAAA;YAChE,CAAC;QACH,CAAC;QAED,oBAAoB;QACpB,MAAM,cAAc,GAAG,mBAAmB,CACxC,SAAS,EACT,GAAG,EACH,wDAAwD,CACzD,CAAA;QACD,MAAM,OAAO,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAC7D,OAAO;YACL,cAAc;YACd,OAAO;YACP,UAAU,EAAE,GAAG;YACf,WAAW,EAAE,UAAU;YACvB,YAAY,EAAE;gBACZ,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE;gBACjC,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,EAAE;gBACvC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE;aACnC;SACF,CAAA;IACH,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,OAAe,EAAE,OAA8B;QAC5D,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,cAAc,CAAA;IACvD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAe,EAAE,OAA8B;QACnD,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,OAAO,CAAA;IAChD,CAAC;IAED,0EAA0E;IAC1E,wBAAwB;IACxB,0EAA0E;IAE1E,uDAAuD;IACvD,cAAc,CAAC,IAAgB;QAC7B,OAAO,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACnC,CAAC;IAED,4CAA4C;IAC5C,eAAe,CAAC,IAAgB;QAC9B,OAAO,cAAc,CAAC,IAAI,CAAC,CAAA;IAC7B,CAAC;IAED,mEAAmE;IACnE,sBAAsB,CAAC,IAAgB;QACrC,OAAO,EAAE,GAAG,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAA;IAC1C,CAAC;IAED,0EAA0E;IAC1E,YAAY;IACZ,0EAA0E;IAE1E;;OAEG;IACH,sBAAsB,CAAC,MAAwB;QAC7C,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,MAAM,CAAA;QACnE,OAAO;YACL,WAAW,cAAc,CAAC,IAAI,EAAE;YAChC,eAAe,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;YAC/C,SAAS,WAAW,EAAE;YACtB,UAAU,cAAc,CAAC,cAAc,EAAE;YACzC,WAAW,cAAc,CAAC,SAAS,EAAE;YACrC,UAAU,OAAO,CAAC,KAAK,EAAE;YACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,OAAO,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI;SAC/E;aACE,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,KAAK,CAAC,CAAA;IAChB,CAAC;IAED,0EAA0E;IAC1E,WAAW;IACX,0EAA0E;IAE1E;;OAEG;IACK,mBAAmB,CACzB,WAAuB,EACvB,iBAAyB;QAEzB,MAAM,SAAS,GAAG,CAAC,GAAG,iBAAiB,CAAA;QACvC,MAAM,QAAQ,GAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAA;QACrG,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,WAAW,CAAC,CAAA;QAExD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YAC1C,IAAI;YACJ,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG;SACtE,CAAC,CAAC,CAAA;IACL,CAAC;CACF"}

package/dist/src/router/guard.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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';
+/** 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';
+/**
+ * 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 declare class MainAgentGuard {
+    private readonly config;
+    private readonly violations;
+    private readonly pendingSubagents;
+    private embargoActive;
+    private tokensUsed;
+    constructor(config: RouterConfig);
+    /** Create a guard with embargo active (strictest mode). */
+    static createEmbargoAll(config: RouterConfig): MainAgentGuard;
+    /** Create a guard with embargo lifted (use with extreme caution). */
+    static createDisabled(config: RouterConfig): MainAgentGuard;
+    /** Convenience: create with default config. */
+    static create(config: RouterConfig): MainAgentGuard;
+    /**
+     * 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;
+    /**
+     * Check whether a file path is permitted to be read by the main agent.
+     */
+    checkReadPath(filePath: string): GuardCheckResult;
+    /**
+     * Comprehensive check combining operation and optional file path/context.
+     */
+    check(context: GuardContext): GuardCheckResult;
+    /**
+     * Assert an operation is allowed. Throws if violated.
+     */
+    assertAllowed(context: GuardContext): void;
+    /**
+     * Record a violation without throwing (for audit trail).
+     */
+    recordViolation(context: GuardContext): void;
+    /** Activate embargo mode - main agent must delegate everything. */
+    activateEmbargo(): void;
+    /** Deactivate embargo mode - main agent regains limited capabilities. */
+    deactivateEmbargo(): void;
+    /** Check if embargo is currently active. */
+    isEmbargoActive(): boolean;
+    /** Register a dispatched subagent. */
+    registerSubagent(id: string): void;
+    /** Mark a subagent as completed. */
+    completeSubagent(id: string): void;
+    /** Check if there are any subagents still pending. */
+    hasPendingSubagents(): boolean;
+    /** Track token usage by the main agent. */
+    trackTokens(count: number): void;
+    /** Get current token usage. */
+    getTokensUsed(): number;
+    /** Percentage of token budget consumed (0-1). */
+    tokenBudgetUtilization(): number;
+    /** Current guard status snapshot. */
+    getStatus(): GuardStatus;
+    /**
+     * Generate the system prompt fragment that enforces guard rules.
+     * Injected into the main agent's system prompt.
+     */
+    generateSystemPromptFragment(): string;
+}
+//# sourceMappingURL=guard.d.ts.map

package/dist/src/router/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/router/guard.ts"],"names":[],"mappings":"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"}