@winspan/claude-forge 8.13.1 → 8.16.0

package/dist/engine/experiment-router.js

@@ -0,0 +1,289 @@
+/**
+ * ExperimentRouter — wraps AgentRouter with A/B-testing capability.
+ *
+ * Responsibilities:
+ *   - Load ~/.claude-forge/routing-experiments.yaml
+ *   - Assign incoming requests to one of N experiment groups via a sticky,
+ *     session-scoped consistent hash
+ *   - Delegate the actual routing decision to a per-group AgentRouter built
+ *     from the group's inline rules
+ *   - Fall back to a provided defaultRouter when the experiment is disabled,
+ *     concluded, or misconfigured
+ *
+ * Stickiness is persisted in the `experiment_assignments` table so group
+ * assignment stays stable across hot reloads and daemon restarts. The hash
+ * input mixes experiment.id so switching to a new experiment reshuffles.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import yaml from 'js-yaml';
+import { logger } from '../core/utils/logger.js';
+import { AgentRouter } from './agent-router.js';
+export class ExperimentRouter {
+    storage;
+    defaultRouter;
+    experimentsPath;
+    config = { enabled: false, experiment: null };
+    groupRouters = new Map();
+    watcher = null;
+    isRuleDisabled = null;
+    constructor(opts) {
+        this.storage = opts.storage;
+        this.defaultRouter = opts.defaultRouter;
+        this.experimentsPath = opts.experimentsPath ?? path.join(homedir(), '.claude-forge', 'routing-experiments.yaml');
+        this.isRuleDisabled = opts.isRuleDisabled ?? null;
+        this.load();
+    }
+    /**
+     * Make a routing decision. If the experiment is active, assigns the session
+     * to a group (sticky) and uses that group's rules. Otherwise delegates to
+     * the default router.
+     */
+    decide(input, sessionId) {
+        if (!this.isExperimentActive()) {
+            const decision = this.defaultRouter.decide(input);
+            return { ...decision, experimentId: null, groupId: null };
+        }
+        const exp = this.config.experiment;
+        const groupId = this.assignGroup(sessionId, exp);
+        const router = this.groupRouters.get(groupId) ?? this.defaultRouter;
+        const decision = router.decide(input);
+        return { ...decision, experimentId: exp.id, groupId };
+    }
+    getConfigSnapshot() {
+        return {
+            enabled: this.config.enabled,
+            experiment: this.config.experiment
+                ? {
+                    ...this.config.experiment,
+                    groups: this.config.experiment.groups.map(g => ({ ...g, rules: g.rules.slice() })),
+                }
+                : null,
+        };
+    }
+    enableHotReload() {
+        if (this.watcher)
+            return;
+        const dir = path.dirname(this.experimentsPath);
+        if (!fs.existsSync(dir)) {
+            logger.debug(`[ExperimentRouter] Hot-reload skipped: ${dir} does not exist`);
+            return;
+        }
+        try {
+            this.watcher = fs.watch(dir, (_eventType, filename) => {
+                if (filename === path.basename(this.experimentsPath)) {
+                    logger.info(`[ExperimentRouter] Detected change in ${this.experimentsPath}, reloading...`);
+                    this.load();
+                }
+            });
+            logger.info(`[ExperimentRouter] Hot-reload enabled for ${this.experimentsPath}`);
+        }
+        catch (err) {
+            logger.warn(`[ExperimentRouter] Failed to enable hot-reload: ${err}`);
+        }
+    }
+    disableHotReload() {
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+    }
+    /** Rebuild config and per-group routers from disk. Idempotent. */
+    load() {
+        const parsed = this.tryReadConfig();
+        if (!parsed) {
+            this.config = { enabled: false, experiment: null };
+            this.groupRouters = new Map();
+            return;
+        }
+        this.config = parsed;
+        // Rebuild group routers atomically — construct a new Map, then swap.
+        const next = new Map();
+        if (parsed.experiment) {
+            for (const group of parsed.experiment.groups) {
+                const router = new AgentRouter({ rules: group.rules });
+                if (this.isRuleDisabled)
+                    router.setIsRuleDisabled(this.isRuleDisabled);
+                next.set(group.id, router);
+            }
+        }
+        this.groupRouters = next;
+        logger.info(parsed.enabled && parsed.experiment
+            ? `[ExperimentRouter] Loaded experiment '${parsed.experiment.id}' with ${parsed.experiment.groups.length} group(s)`
+            : `[ExperimentRouter] Loaded config (experiment disabled or absent)`);
+    }
+    tryReadConfig() {
+        if (!fs.existsSync(this.experimentsPath))
+            return null;
+        let raw;
+        try {
+            raw = fs.readFileSync(this.experimentsPath, 'utf-8');
+        }
+        catch (err) {
+            logger.warn(`[ExperimentRouter] Failed to read ${this.experimentsPath}: ${err}`);
+            return null;
+        }
+        try {
+            // CORE_SCHEMA disallows !!js/function and other unsafe js-yaml tags.
+            const parsed = yaml.load(raw, { schema: yaml.CORE_SCHEMA });
+            return validateConfig(parsed);
+        }
+        catch (err) {
+            logger.warn(`[ExperimentRouter] Failed to parse experiments YAML: ${err}`);
+            return null;
+        }
+    }
+    isExperimentActive() {
+        return Boolean(this.config.enabled &&
+            this.config.experiment &&
+            this.config.experiment.endedAt == null &&
+            this.config.experiment.groups.length > 0 &&
+            this.groupRouters.size > 0);
+    }
+    assignGroup(sessionId, exp) {
+        const existing = this.storage.getExperimentAssignment(sessionId, exp.id);
+        if (existing && this.groupRouters.has(existing)) {
+            return existing;
+        }
+        const groupId = pickGroup(sessionId, exp);
+        try {
+            this.storage.setExperimentAssignment(sessionId, exp.id, groupId);
+        }
+        catch (err) {
+            logger.warn(`[ExperimentRouter] Failed to persist assignment for ${sessionId}: ${err}`);
+        }
+        return groupId;
+    }
+}
+/**
+ * Deterministic bucket selection using murmur3_32 of `sessionId:experimentId`.
+ * Mixing the experiment id ensures that starting a new experiment does not
+ * leave a given session permanently stuck on the first bucket.
+ */
+export function pickGroup(sessionId, exp) {
+    const bucket = murmur3_32(`${sessionId}:${exp.id}`) % 100;
+    let acc = 0;
+    for (const group of exp.groups) {
+        acc += group.weight;
+        if (bucket < acc)
+            return group.id;
+    }
+    // Floating-point/rounding safety net: return last group.
+    return exp.groups[exp.groups.length - 1].id;
+}
+/**
+ * murmur3_32 — a small, self-contained hash. Public-domain reference impl.
+ * We avoid adding a dependency for ~30 lines of code.
+ */
+export function murmur3_32(str, seed = 0) {
+    let h1 = seed >>> 0;
+    const c1 = 0xcc9e2d51;
+    const c2 = 0x1b873593;
+    const data = new TextEncoder().encode(str);
+    const len = data.length;
+    const blocks = Math.floor(len / 4);
+    for (let i = 0; i < blocks; i++) {
+        let k1 = data[i * 4] |
+            (data[i * 4 + 1] << 8) |
+            (data[i * 4 + 2] << 16) |
+            (data[i * 4 + 3] << 24);
+        k1 = Math.imul(k1, c1) >>> 0;
+        k1 = ((k1 << 15) | (k1 >>> 17)) >>> 0;
+        k1 = Math.imul(k1, c2) >>> 0;
+        h1 = (h1 ^ k1) >>> 0;
+        h1 = ((h1 << 13) | (h1 >>> 19)) >>> 0;
+        h1 = (Math.imul(h1, 5) + 0xe6546b64) >>> 0;
+    }
+    let k1 = 0;
+    const tail = len & 3;
+    const tailStart = blocks * 4;
+    if (tail === 3)
+        k1 ^= data[tailStart + 2] << 16;
+    if (tail >= 2)
+        k1 ^= data[tailStart + 1] << 8;
+    if (tail >= 1) {
+        k1 ^= data[tailStart];
+        k1 = Math.imul(k1, c1) >>> 0;
+        k1 = ((k1 << 15) | (k1 >>> 17)) >>> 0;
+        k1 = Math.imul(k1, c2) >>> 0;
+        h1 = (h1 ^ k1) >>> 0;
+    }
+    h1 = (h1 ^ len) >>> 0;
+    h1 ^= h1 >>> 16;
+    h1 = Math.imul(h1, 0x85ebca6b) >>> 0;
+    h1 ^= h1 >>> 13;
+    h1 = Math.imul(h1, 0xc2b2ae35) >>> 0;
+    h1 ^= h1 >>> 16;
+    return h1 >>> 0;
+}
+/**
+ * Validate raw YAML shape. Returns null on any structural error; logs details.
+ * Exported so the Web API can reject invalid PUTs with the same rules.
+ */
+export function validateConfig(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const enabled = raw.enabled === true;
+    const exp = raw.experiment;
+    if (!exp || typeof exp !== 'object') {
+        return { enabled: false, experiment: null };
+    }
+    if (typeof exp.id !== 'string' || exp.id.length === 0) {
+        logger.warn('[ExperimentRouter] experiment.id missing or empty');
+        return null;
+    }
+    if (!Array.isArray(exp.groups) || exp.groups.length === 0) {
+        logger.warn('[ExperimentRouter] experiment.groups must be a non-empty array');
+        return null;
+    }
+    const groups = [];
+    const ids = new Set();
+    let totalWeight = 0;
+    for (const g of exp.groups) {
+        if (!g || typeof g !== 'object') {
+            logger.warn('[ExperimentRouter] invalid group entry');
+            return null;
+        }
+        if (typeof g.id !== 'string' || g.id.length === 0) {
+            logger.warn('[ExperimentRouter] group.id missing');
+            return null;
+        }
+        if (ids.has(g.id)) {
+            logger.warn(`[ExperimentRouter] duplicate group id '${g.id}'`);
+            return null;
+        }
+        ids.add(g.id);
+        if (typeof g.weight !== 'number' || !Number.isFinite(g.weight) || g.weight < 0) {
+            logger.warn(`[ExperimentRouter] group '${g.id}' has invalid weight`);
+            return null;
+        }
+        if (!Array.isArray(g.rules) || g.rules.length === 0) {
+            logger.warn(`[ExperimentRouter] group '${g.id}' has no rules`);
+            return null;
+        }
+        totalWeight += g.weight;
+        groups.push({
+            id: g.id,
+            name: typeof g.name === 'string' ? g.name : g.id,
+            weight: g.weight,
+            rules: g.rules,
+        });
+    }
+    if (totalWeight !== 100) {
+        logger.warn(`[ExperimentRouter] group weights sum to ${totalWeight}, expected 100`);
+        return null;
+    }
+    const endedAt = typeof exp.endedAt === 'string' && exp.endedAt.length > 0 ? exp.endedAt : null;
+    return {
+        enabled,
+        experiment: {
+            id: exp.id,
+            name: typeof exp.name === 'string' ? exp.name : exp.id,
+            startedAt: typeof exp.startedAt === 'string' ? exp.startedAt : new Date().toISOString(),
+            endedAt,
+            groups,
+        },
+    };
+}
+//# sourceMappingURL=experiment-router.js.map

package/dist/engine/experiment-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment-router.js","sourceRoot":"","sources":["../../src/engine/experiment-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,IAAI,MAAM,SAAS,CAAC;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACjD,OAAO,EAAE,WAAW,EAA8E,MAAM,mBAAmB,CAAC;AA6C5H,MAAM,OAAO,gBAAgB;IACnB,OAAO,CAAgB;IACvB,aAAa,CAAc;IAC3B,eAAe,CAAS;IACxB,MAAM,GAAqB,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAChE,YAAY,GAA6B,IAAI,GAAG,EAAE,CAAC;IACnD,OAAO,GAAwB,IAAI,CAAC;IACpC,cAAc,GAA0B,IAAI,CAAC;IAErD,YAAY,IAKX;QACC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,eAAe,EAAE,0BAA0B,CAAC,CAAC;QACjH,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC;QAClD,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAiB,EAAE,SAAiB;QACzC,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC;YAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAClD,OAAO,EAAE,GAAG,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC5D,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,UAAW,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC;QACpE,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtC,OAAO,EAAE,GAAG,QAAQ,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC;IACxD,CAAC;IAED,iBAAiB;QACf,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;gBAChC,CAAC,CAAC;oBACE,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU;oBACzB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;iBACnF;gBACH,CAAC,CAAC,IAAI;SACT,CAAC;IACJ,CAAC;IAED,eAAe;QACb,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAC/C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,CAAC,KAAK,CAAC,0CAA0C,GAAG,iBAAiB,CAAC,CAAC;YAC7E,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,EAAE;gBACpD,IAAI,QAAQ,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;oBACrD,MAAM,CAAC,IAAI,CAAC,yCAAyC,IAAI,CAAC,eAAe,gBAAgB,CAAC,CAAC;oBAC3F,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,CAAC;YACH,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,IAAI,CAAC,6CAA6C,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;QACnF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,mDAAmD,GAAG,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED,gBAAgB;QACd,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,CAAC;IACH,CAAC;IAED,kEAAkE;IAC1D,IAAI;QACV,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACpC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,IAAI,CAAC,MAAM,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;YACnD,IAAI,CAAC,YAAY,GAAG,IAAI,GAAG,EAAE,CAAC;YAC9B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,qEAAqE;QACrE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAuB,CAAC;QAC5C,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACtB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;gBAC7C,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;gBACvD,IAAI,IAAI,CAAC,cAAc;oBAAE,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;gBACvE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,MAAM,CAAC,IAAI,CACT,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,UAAU;YACjC,CAAC,CAAC,yCAAyC,MAAM,CAAC,UAAU,CAAC,EAAE,UAAU,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,WAAW;YACnH,CAAC,CAAC,kEAAkE,CACvE,CAAC;IACJ,CAAC;IAEO,aAAa;QACnB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC;YAAE,OAAO,IAAI,CAAC;QACtD,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,qCAAqC,IAAI,CAAC,eAAe,KAAK,GAAG,EAAE,CAAC,CAAC;YACjF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC;YACH,qEAAqE;YACrE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,CAA2B,CAAC;YACtF,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,wDAAwD,GAAG,EAAE,CAAC,CAAC;YAC3E,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAEO,kBAAkB;QACxB,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,CAAC,OAAO;YACnB,IAAI,CAAC,MAAM,CAAC,UAAU;YACtB,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,IAAI,IAAI;YACtC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;YACxC,IAAI,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,CAC3B,CAAC;IACJ,CAAC;IAEO,WAAW,CAAC,SAAiB,EAAE,GAAmB;QACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,uBAAuB,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACzE,IAAI,QAAQ,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChD,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,OAAO,GAAG,SAAS,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,uBAAuB,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACnE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,uDAAuD,SAAS,KAAK,GAAG,EAAE,CAAC,CAAC;QAC1F,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,SAAiB,EAAE,GAAmB;IAC9D,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,SAAS,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC;IAC1D,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC/B,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC;QACpB,IAAI,MAAM,GAAG,GAAG;YAAE,OAAO,KAAK,CAAC,EAAE,CAAC;IACpC,CAAC;IACD,yDAAyD;IACzD,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,IAAI,GAAG,CAAC;IAC9C,IAAI,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;IACpB,MAAM,EAAE,GAAG,UAAU,CAAC;IACtB,MAAM,EAAE,GAAG,UAAU,CAAC;IACtB,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;IACxB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,IAAI,EAAE,GACJ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACX,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;YACtB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;YACvB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1B,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;QAC7B,EAAE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QACtC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;QAC7B,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;QACrB,EAAE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QACtC,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,EAAE,GAAG,CAAC,CAAC;IACX,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC;IACrB,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,CAAC;IAC7B,IAAI,IAAI,KAAK,CAAC;QAAE,EAAE,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAChD,IAAI,IAAI,IAAI,CAAC;QAAE,EAAE,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACd,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;QACtB,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;QAC7B,EAAE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QACtC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;QAC7B,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAED,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;IACtB,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAChB,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IACrC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAChB,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IACrC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,EAAE,KAAK,CAAC,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,GAAuC;IACpE,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEjD,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC;IACrC,MAAM,GAAG,GAAG,GAAG,CAAC,UAAU,CAAC;IAC3B,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,GAAG,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;QACjE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,MAAM,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;YACtD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClD,MAAM,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;YACnD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YAClB,MAAM,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YAC/D,OAAO,IAAI,CAAC;QACd,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACd,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/E,MAAM,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;YAC/D,OAAO,IAAI,CAAC;QACd,CAAC;QACD,WAAW,IAAI,CAAC,CAAC,MAAM,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC;YACV,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE;YAChD,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,KAAK,EAAE,CAAC,CAAC,KAAK;SACf,CAAC,CAAC;IACL,CAAC;IACD,IAAI,WAAW,KAAK,GAAG,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,2CAA2C,WAAW,gBAAgB,CAAC,CAAC;QACpF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GACX,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAEjF,OAAO;QACL,OAAO;QACP,UAAU,EAAE;YACV,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,IAAI,EAAE,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE;YACtD,SAAS,EAAE,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACvF,OAAO;YACP,MAAM;SACP;KACF,CAAC;AACJ,CAAC"}

package/dist/engine/recommender.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Recommender — analyzes routing_events history to suggest rule changes.
+ *
+ * Heuristic (MVP):
+ *   1. For each (taskType, complexity?) slot seen in the last N days,
+ *      aggregate how many times Claude actually invoked each agent
+ *      (either as the first Task subagent_type, or anywhere in the
+ *      downstream chain).
+ *   2. Compare against the current AgentRouter decision for that slot.
+ *   3. Emit a recommendation when:
+ *        - A different agent was actually used > 50% of the time
+ *        - Sample size >= 10
+ *        - The recommended agent exists in AgentRegistry
+ *   4. Sort by confidence (sample size * rate delta).
+ *
+ * This is intentionally conservative — we do not attempt to learn rule
+ * ordering or compose new when-clauses. Recommendations are suggestions
+ * for the user to apply manually (or via a one-click button later).
+ */
+import type { SQLiteStorage } from '../core/storage/sqlite.js';
+import type { AgentRouter, TaskType, Complexity } from './agent-router.js';
+import type { AgentRegistry } from '../agents/registry.js';
+export interface Recommendation {
+    taskType: TaskType;
+    complexity: Complexity | null;
+    currentAgent: string | null;
+    recommendedAgent: string;
+    sampleSize: number;
+    currentObeyedRate: number;
+    recommendedUsageRate: number;
+    confidence: number;
+    reason: string;
+}
+export interface RecommenderOptions {
+    /** Analysis window (ms). Default 7d. */
+    windowMs?: number;
+    /** Minimum attempts per slot before a recommendation is considered. */
+    minSampleSize?: number;
+    /** The actual-use rate threshold for a challenger agent. */
+    minChallengerRate?: number;
+}
+export declare class Recommender {
+    private storage;
+    private router;
+    private agents;
+    private windowMs;
+    private minSampleSize;
+    private minChallengerRate;
+    constructor(storage: SQLiteStorage, router: AgentRouter, agents: AgentRegistry, opts?: RecommenderOptions);
+    analyze(): Recommendation[];
+}
+//# sourceMappingURL=recommender.d.ts.map

package/dist/engine/recommender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommender.d.ts","sourceRoot":"","sources":["../../src/engine/recommender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAqBD,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,iBAAiB,CAAS;gBAGhC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,aAAa,EACrB,IAAI,GAAE,kBAAuB;IAU/B,OAAO,IAAI,cAAc,EAAE;CA+F5B"}

package/dist/engine/recommender.js

@@ -0,0 +1,150 @@
+/**
+ * Recommender — analyzes routing_events history to suggest rule changes.
+ *
+ * Heuristic (MVP):
+ *   1. For each (taskType, complexity?) slot seen in the last N days,
+ *      aggregate how many times Claude actually invoked each agent
+ *      (either as the first Task subagent_type, or anywhere in the
+ *      downstream chain).
+ *   2. Compare against the current AgentRouter decision for that slot.
+ *   3. Emit a recommendation when:
+ *        - A different agent was actually used > 50% of the time
+ *        - Sample size >= 10
+ *        - The recommended agent exists in AgentRegistry
+ *   4. Sort by confidence (sample size * rate delta).
+ *
+ * This is intentionally conservative — we do not attempt to learn rule
+ * ordering or compose new when-clauses. Recommendations are suggestions
+ * for the user to apply manually (or via a one-click button later).
+ */
+import { logger } from '../core/utils/logger.js';
+const TASK_TYPES = [
+    'build_system', 'add_feature', 'refactor', 'migrate', 'fix_bug',
+    'analyze_requirement', 'design_architecture', 'design_api', 'design_schema',
+    'write_code', 'write_test', 'review', 'audit_security', 'optimize_perf',
+    'write_spec', 'review_doc', 'create_pr', 'explain', 'other',
+];
+const COMPLEXITIES = ['simple', 'moderate', 'complex'];
+export class Recommender {
+    storage;
+    router;
+    agents;
+    windowMs;
+    minSampleSize;
+    minChallengerRate;
+    constructor(storage, router, agents, opts = {}) {
+        this.storage = storage;
+        this.router = router;
+        this.agents = agents;
+        this.windowMs = opts.windowMs ?? 7 * 24 * 3600 * 1000;
+        this.minSampleSize = opts.minSampleSize ?? 10;
+        this.minChallengerRate = opts.minChallengerRate ?? 0.5;
+    }
+    analyze() {
+        const since = Date.now() - this.windowMs;
+        const events = this.storage.queryRoutingEvents({ since_ts: since, limit: 20000 });
+        const slots = new Map();
+        for (const e of events) {
+            if (!e.is_forced)
+                continue;
+            let taskType = null;
+            let complexity = null;
+            try {
+                const parsed = JSON.parse(e.intent_json ?? '{}');
+                if (typeof parsed.taskType === 'string' && TASK_TYPES.includes(parsed.taskType)) {
+                    taskType = parsed.taskType;
+                }
+                if (typeof parsed.complexity === 'string' && COMPLEXITIES.includes(parsed.complexity)) {
+                    complexity = parsed.complexity;
+                }
+            }
+            catch { /* ignore */ }
+            if (!taskType)
+                continue;
+            const key = `${taskType}__${complexity ?? 'any'}`;
+            const agg = slots.get(key) ?? {
+                taskType,
+                complexity,
+                attempts: 0,
+                obeyedCount: 0,
+                agentUsage: new Map(),
+                currentAgent: null,
+            };
+            agg.attempts++;
+            if (e.obeyed === 1)
+                agg.obeyedCount++;
+            // Count agent usage — the agent Claude actually invoked (if we know).
+            // Priority order: first_tool_name=Task's subagent (encoded indirectly
+            // via obeyed + routed_to_name), then the downstream chain.
+            const chain = parseChain(e.downstream_task_chain);
+            if (chain.length > 0) {
+                // The chain is the authoritative signal: which agents Claude engaged.
+                const first = chain[0];
+                agg.agentUsage.set(first, (agg.agentUsage.get(first) ?? 0) + 1);
+            }
+            else if (e.obeyed === 1 && e.routed_to_name) {
+                // Obeyed path with no chain recorded (non-Task first tool but match) —
+                // count the routed agent.
+                agg.agentUsage.set(e.routed_to_name, (agg.agentUsage.get(e.routed_to_name) ?? 0) + 1);
+            }
+            slots.set(key, agg);
+        }
+        // Fill in currentAgent via the router's live decision.
+        for (const agg of slots.values()) {
+            const decision = this.router.decide({
+                taskType: agg.taskType,
+                complexity: agg.complexity ?? 'moderate',
+            });
+            agg.currentAgent = decision.action.type === 'route_to_agent' ? decision.action.name : null;
+        }
+        const recommendations = [];
+        for (const agg of slots.values()) {
+            if (agg.attempts < this.minSampleSize)
+                continue;
+            if (agg.agentUsage.size === 0)
+                continue;
+            // Rank agents by usage count.
+            const sorted = [...agg.agentUsage.entries()].sort((a, b) => b[1] - a[1]);
+            const [topAgent, topCount] = sorted[0];
+            const topRate = topCount / agg.attempts;
+            if (topRate < this.minChallengerRate)
+                continue;
+            if (topAgent === agg.currentAgent)
+                continue; // Already routing here.
+            if (!this.agents.get(topAgent))
+                continue; // Unknown agent — skip.
+            const currentObeyedRate = agg.obeyedCount / agg.attempts;
+            const confidence = Math.min(1, (agg.attempts / 50) * Math.max(0, topRate - currentObeyedRate));
+            const reason = agg.currentAgent
+                ? `当前路由到 ${agg.currentAgent} 听话率 ${(currentObeyedRate * 100).toFixed(0)}%，` +
+                    `但 Claude 实际使用 ${topAgent} 达 ${(topRate * 100).toFixed(0)}%（${topCount}/${agg.attempts}）`
+                : `当前无路由（走 skill 回退），但 Claude 实际使用 ${topAgent} 达 ${(topRate * 100).toFixed(0)}%`;
+            recommendations.push({
+                taskType: agg.taskType,
+                complexity: agg.complexity,
+                currentAgent: agg.currentAgent,
+                recommendedAgent: topAgent,
+                sampleSize: agg.attempts,
+                currentObeyedRate,
+                recommendedUsageRate: topRate,
+                confidence,
+                reason,
+            });
+        }
+        recommendations.sort((a, b) => b.confidence - a.confidence);
+        logger.debug(`[Recommender] ${recommendations.length} recommendation(s) from ${slots.size} slot(s)`);
+        return recommendations;
+    }
+}
+function parseChain(raw) {
+    if (!raw)
+        return [];
+    try {
+        const arr = JSON.parse(raw);
+        return Array.isArray(arr) ? arr.filter(x => typeof x === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=recommender.js.map

package/dist/engine/recommender.js.map

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

package/dist/intelligence/classifier.d.ts

@@ -1,27 +1,41 @@
 /**
- * IntentClassifier — simplified intent classification
+ * IntentClassifier — intent classification for UserPromptSubmit routing
  *
- * Classifies user prompts into complexity levels using:
- * 1. Ground-truth regex rules (fast, deterministic)
- * 2. AI fallback (for ambiguous cases)
+ * Output contract:
+ *   { complexity, taskType, searchKeywords, reasoning }
+ *
+ * Layered strategy (fast → slow):
+ *   1. Regex ground-truth   — explicit simple commands (ls/pwd/...) → skip AI
+ *   2. LRU cache            — repeated prompts
+ *   3. AI classification    — 3s hard timeout
+ *   4. Regex fallback       — AI timeout/failure
  */
 import type { AIProvider } from '../core/ai/types.js';
 export type Complexity = 'simple' | 'moderate' | 'complex';
+export type TaskType = 'build_system' | 'add_feature' | 'refactor' | 'migrate' | 'fix_bug' | 'analyze_requirement' | 'design_architecture' | 'design_api' | 'design_schema' | 'write_code' | 'write_test' | 'review' | 'audit_security' | 'optimize_perf' | 'write_spec' | 'review_doc' | 'create_pr' | 'explain' | 'other';
+export declare const TASK_TYPES: readonly TaskType[];
 export interface IntentAnalysis {
     requirement: string;
     complexity: Complexity;
+    taskType: TaskType;
     searchKeywords: string[];
     reasoning: string;
+    /** True when AI timed out or failed and regex fallback was used. */
+    fallbackUsed?: boolean;
+    /** AI classification latency in ms (undefined when fallback-only path). */
+    classificationMs?: number;
 }
 export declare class IntentClassifier {
     private ai;
     private cache;
-    constructor(ai: AIProvider);
+    constructor(ai: AIProvider | null);
     classify(prompt: string, projectPath: string): Promise<IntentAnalysis>;
     private matchGroundTruth;
+    private aiClassifyWithTimeout;
     private aiClassify;
     private parseAIResponse;
     private fallback;
+    private guessTaskType;
     private extractKeywords;
 }
 //# sourceMappingURL=classifier.d.ts.map

package/dist/intelligence/classifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../src/intelligence/classifier.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAItD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAeD,qBAAa,gBAAgB;IAGf,OAAO,CAAC,EAAE;IAFtB,OAAO,CAAC,KAAK,CAA4C;gBAErC,EAAE,EAAE,UAAU;IAE5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA2B5E,OAAO,CAAC,gBAAgB;YA4BV,UAAU;IAqBxB,OAAO,CAAC,eAAe;IAuBvB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,eAAe;CAQxB"}
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../src/intelligence/classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAItD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3D,MAAM,MAAM,QAAQ,GAChB,cAAc,GACd,aAAa,GACb,UAAU,GACV,SAAS,GACT,SAAS,GACT,qBAAqB,GACrB,qBAAqB,GACrB,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,YAAY,GACZ,QAAQ,GACR,gBAAgB,GAChB,eAAe,GACf,YAAY,GACZ,YAAY,GACZ,WAAW,GACX,SAAS,GACT,OAAO,CAAC;AAEZ,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAKhC,CAAC;AAEX,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA4CD,qBAAa,gBAAgB;IAGf,OAAO,CAAC,EAAE;IAFtB,OAAO,CAAC,KAAK,CAA4C;gBAErC,EAAE,EAAE,UAAU,GAAG,IAAI;IAEnC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAwC5E,OAAO,CAAC,gBAAgB;YA4BV,qBAAqB;YAYrB,UAAU;IAgCxB,OAAO,CAAC,eAAe;IA2BvB,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,eAAe;CAOxB"}