@event4u/agent-config 14.21.0 → 14.23.0

package/dist/scripts/_lib/lean_projection_mode.js

@@ -37,4 +37,112 @@ export function writesThinFiles(mode) {
 export function deliversBodies(mode) {
     return mode === 'delivery';
 }
+/**
+ * The hosts a thinning mode may actually thin.
+ *
+ * Deliberately NOT "every host id the package knows". `condense`'s `TOOL_DIRS`
+ * writes a per-rule tree for exactly three hosts, so those are the only ids for
+ * which `lean_projection.hosts` can mean anything: naming `windsurf` there would
+ * be a request to thin a single concatenated file that has no per-rule stub
+ * shape, and naming `codex` a request to thin a tree the installer writes and
+ * `condense` never touches. Accepting such an id silently would leave the
+ * operator believing a host was scoped when nothing reads the entry.
+ */
+export const THINNABLE_HOSTS = ['claude-code', 'cursor', 'cline'];
+/**
+ * The shipped default host set for a thinning mode.
+ *
+ * One host, and it is the one host that both binds `pre_tool_use` and honours a
+ * deny (`docs/enforcement-by-host.md:18-28`) — i.e. the only host where the
+ * delivery concern's verdict is acted on. Widening this is a decision, never a
+ * default: see `resolveLeanProjectionHosts`, which never widens implicitly.
+ */
+export const DEFAULT_LEAN_PROJECTION_HOSTS = ['claude-code'];
+/**
+ * Resolve a configured `lean_projection.hosts` list.
+ *
+ * Three properties, each of which is a failure this repository has seen in a
+ * neighbouring config surface:
+ *
+ * 1. **Absent means the default, never "all".** An empty or missing list
+ *    resolves to `DEFAULT_LEAN_PROJECTION_HOSTS`. A key nobody set must not
+ *    thin every host — that is D1, the defect this axis exists to repair.
+ * 2. **The set never widens implicitly.** Every id is checked against
+ *    `THINNABLE_HOSTS`; anything else is dropped. A typo cannot enrol a host,
+ *    and neither can a real host id that has no per-rule tree.
+ * 3. **A drop is reported, not swallowed.** The caller gets the ids and the
+ *    reason so it can print them. Silently ignoring an entry an operator wrote
+ *    is how a setting comes to mean nothing while looking configured.
+ *
+ * A configured list that resolves to NOTHING keeps `usedDefault: false` and an
+ * empty `hosts` — that is "thin no host", which is a legitimate and safe answer
+ * and must not fall back to the default. Falling back there would turn a
+ * fully-typo'd list into a Claude Code flip the operator never asked for.
+ *
+ * WHICH FILES REACH THIS AT ALL, stated because R2 finding 6 read the drop path
+ * as unreachable: `agent-settings.schema.json` and the wizard's Zod schema both
+ * constrain the items to an `enum`, so an out-of-vocabulary id written through
+ * either surface is a hard validation FAILURE and never arrives here. What
+ * arrives here is a HAND-EDITED `.agent-settings.yml` — the file
+ * `condense._lean_projection_settings` and `hooks/rule_inject_hook.gateOpen`
+ * both read directly, with no validation step in between. The two layers are
+ * defence in depth, not one contract stated twice: the schema is the authoring
+ * gate, this function is the read-time gate, and the drop wording below exists
+ * for the file the schema never saw.
+ */
+export function resolveLeanProjectionHosts(raw) {
+    const known = new Set(THINNABLE_HOSTS);
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return { hosts: [...DEFAULT_LEAN_PROJECTION_HOSTS], dropped: [], usedDefault: true };
+    }
+    const hosts = [];
+    const dropped = [];
+    for (const entry of raw) {
+        const id = typeof entry === 'string' ? entry.trim().toLowerCase() : '';
+        if (id === '') {
+            dropped.push({ id: String(entry), reason: 'unknown' });
+            continue;
+        }
+        if (!known.has(id)) {
+            // `not-thinnable` is reserved for an id this package genuinely knows
+            // as a host but which owns no per-rule tree. Everything else is a
+            // typo or an invention, and the two deserve different wording
+            // because the operator's next action differs: fix the spelling, or
+            // learn that the host cannot be thinned at all.
+            dropped.push({ id, reason: KNOWN_NON_THINNABLE_HOSTS.has(id) ? 'not-thinnable' : 'unknown' });
+            continue;
+        }
+        if (!hosts.includes(id))
+            hosts.push(id);
+    }
+    hosts.sort();
+    return { hosts, dropped, usedDefault: false };
+}
+/**
+ * Host ids the package ships surfaces for that own no per-rule rule tree.
+ *
+ * Only used to word a drop precisely; it grants nothing. Sourced from
+ * `condense._ALL_TOOLS` plus the two hosts outside it that the host table
+ * carries (`codex`, `cowork`).
+ */
+const KNOWN_NON_THINNABLE_HOSTS = new Set([
+    'claude-desktop', 'augment', 'copilot', 'windsurf', 'gemini', 'codex', 'cowork',
+]);
+/** One line per dropped id, for a caller that prints warnings. Empty when nothing was dropped. */
+export function describeDroppedHosts(res) {
+    return res.dropped.map(({ id, reason }) => reason === 'not-thinnable'
+        ? `lean_projection.hosts: "${id}" is a known host but has no per-rule rule tree — dropped`
+        : `lean_projection.hosts: "${id}" is not a thinnable host id — dropped`);
+}
+/**
+ * Does the projector write stubs for this host, under this mode and host set?
+ *
+ * The single predicate `condense` calls. Mode is checked FIRST and on purpose:
+ * with `mode` unset the answer is `false` for every host regardless of what
+ * `hosts` says, so a `hosts:` list left behind after a rollback to `eager-all`
+ * thins nothing.
+ */
+export function thinsHost(mode, hosts, hostId) {
+    return writesThinFiles(mode) && hosts.includes(hostId);
+}
 //# sourceMappingURL=lean_projection_mode.js.map

package/dist/scripts/_lib/router_match.js

@@ -0,0 +1,243 @@
+/**
+ * THE single trigger-matcher implementation for `dist/router.json`.
+ *
+ * Parity by construction: every surface that answers "which rules fire on
+ * this prompt?" — router replay (`router_telemetry.ts`), trigger-coverage
+ * CI (`trigger_coverage.ts`), `agent-config explain route`, and
+ * `agent-config route:explain` — MUST import the matchers from this module.
+ * A second implementation of these semantics anywhere in the tree is a
+ * violation (enforced by `tests/scripts/router_match_parity.test.ts`); the
+ * historical divergence this kills was `cmd_explain.ts` shipping unanchored
+ * keyword matching while the replay path was anchored.
+ *
+ * Canonical semantics: `docs/contracts/rule-router.md` § `triggers:` shape
+ * (the trigger-semantics table — anchored `keyword`, unanchored `phrase`,
+ * `command` prefix, `path_prefix` / `file_pattern` over open files).
+ *
+ * Extracted verbatim from `router_telemetry.ts` (which re-exports the same
+ * names for existing importers). Behaviour is pinned by the routing-matrix
+ * and trigger-coverage suites — do not "fix" quirks here.
+ */
+// ── fnmatch (Python fnmatch.fnmatch) ─────────────────────────────────────
+/**
+ * Translate a Unix shell pattern into a RegExp, matching CPython's
+ * `fnmatch.translate`. `*` → `.*`, `?` → `.`, `[...]` char classes
+ * preserved (with `!` → `^` negation), everything else escaped.
+ * Matching is case-sensitive on POSIX (the corpus paths are POSIX).
+ */
+function _fnmatchToRegExp(pat) {
+    let res = "";
+    let i = 0;
+    const n = pat.length;
+    while (i < n) {
+        const c = pat[i];
+        i += 1;
+        if (c === "*") {
+            res += ".*";
+        }
+        else if (c === "?") {
+            res += ".";
+        }
+        else if (c === "[") {
+            let j = i;
+            if (j < n && pat[j] === "!") {
+                j += 1;
+            }
+            if (j < n && pat[j] === "]") {
+                j += 1;
+            }
+            while (j < n && pat[j] !== "]") {
+                j += 1;
+            }
+            if (j >= n) {
+                res += "\\[";
+            }
+            else {
+                let stuff = pat.slice(i, j);
+                if (!stuff.includes("-")) {
+                    stuff = stuff.replace(/\\/g, "\\\\");
+                }
+                else {
+                    // Faithful port of CPython's dash-handling in fnmatch.translate:
+                    // split the class body on `-` (bounded to [i, j)), escaping each
+                    // chunk, then re-join with `-` so ranges survive.
+                    const chunks = [];
+                    let k = pat[i] === "!" ? i + 2 : i + 1;
+                    let start = i;
+                    while (true) {
+                        const rel = pat.slice(k, j).indexOf("-");
+                        if (rel < 0) {
+                            break;
+                        }
+                        const idx = k + rel;
+                        chunks.push(pat.slice(start, idx));
+                        start = idx + 1;
+                        k = idx + 3;
+                    }
+                    chunks.push(pat.slice(start, j));
+                    stuff = chunks
+                        .map((s) => s.replace(/\\/g, "\\\\").replace(/-/g, "\\-"))
+                        .join("-");
+                }
+                // Escape regex set-meta chars except backslash/dash already handled.
+                stuff = stuff.replace(/([&~|])/g, "\\$1");
+                i = j + 1;
+                if (stuff.startsWith("!")) {
+                    stuff = "^" + stuff.slice(1);
+                }
+                else if (stuff.startsWith("^") || stuff.startsWith("[")) {
+                    stuff = "\\" + stuff;
+                }
+                res += `[${stuff}]`;
+            }
+        }
+        else {
+            res += c.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^(?:${res})$`, "s");
+}
+export function _fnmatch(name, pat) {
+    return _fnmatchToRegExp(pat).test(name);
+}
+// ── Trigger matching ─────────────────────────────────────────────────────
+/** Apply one trigger to a prompt + context; return True on match. */
+/** Unicode word character — letters, digits, underscore (incl. umlauts). */
+const _WORD_CHAR = /[\p{L}\p{N}_]/u;
+function _isWordChar(c) {
+    return c !== undefined && _WORD_CHAR.test(c);
+}
+/**
+ * Word-boundary-anchored keyword match (road-to-tested-routing Phase 3).
+ *
+ * A `keyword` occurrence counts only when its word-character edges sit on
+ * word boundaries: `ac` no longer fires inside "black", `plan` no longer
+ * fires inside "planet". Two deliberate reliefs:
+ *
+ * - An edge that is itself a NON-word character (e.g. `__()`, `/image:`,
+ *   `trans(`, an emoji) carries no boundary requirement on that side —
+ *   punctuation-shaped keywords keep their exact substring semantics.
+ * - The right boundary accepts one optional plural `s` ("icons", "options",
+ *   "secrets" still fire their singular keyword). Richer inflection (German
+ *   verb endings: "implementiere", "committen") is a DOCUMENTED accepted
+ *   recall cost of anchoring — the matrices carry standalone-token phrasings
+ *   for those languages instead.
+ *
+ * `phrase` deliberately stays unanchored substring; since this change the
+ * two trigger kinds genuinely differ.
+ */
+export function keyword_matches_anchored(prompt_lower, kw_lower) {
+    if (kw_lower === "") {
+        return false;
+    }
+    const needLeft = _isWordChar(kw_lower[0]);
+    const needRight = _isWordChar(kw_lower[kw_lower.length - 1]);
+    let idx = prompt_lower.indexOf(kw_lower);
+    while (idx !== -1) {
+        const leftOk = !needLeft || !_isWordChar(prompt_lower[idx - 1]);
+        let rightOk = true;
+        if (needRight) {
+            let end = idx + kw_lower.length;
+            if (prompt_lower[end] === "s") {
+                end += 1; // optional plural `s`
+            }
+            rightOk = !_isWordChar(prompt_lower[end]);
+        }
+        if (leftOk && rightOk) {
+            return true;
+        }
+        idx = prompt_lower.indexOf(kw_lower, idx + 1);
+    }
+    return false;
+}
+export function trigger_matches(trigger, prompt, open_files, command) {
+    const prompt_lower = prompt.toLowerCase();
+    if ("keyword" in trigger) {
+        return keyword_matches_anchored(prompt_lower, String(trigger["keyword"]).toLowerCase());
+    }
+    if ("phrase" in trigger) {
+        return prompt_lower.includes(String(trigger["phrase"]).toLowerCase());
+    }
+    if ("command" in trigger) {
+        if (!command) {
+            return false;
+        }
+        return command.startsWith(String(trigger["command"]));
+    }
+    if ("path_prefix" in trigger) {
+        if (!open_files) {
+            return false;
+        }
+        const pref = String(trigger["path_prefix"]);
+        for (const p of open_files) {
+            if (String(p).startsWith(pref)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    if ("file_pattern" in trigger) {
+        if (!open_files) {
+            return false;
+        }
+        const pat = String(trigger["file_pattern"]);
+        for (const p of open_files) {
+            if (_fnmatch(String(p), pat)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    return false;
+}
+export function _asRuleList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value;
+}
+export function _asTriggerList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value;
+}
+/**
+ * Return the matched-triggers + activated-rules for one prompt.
+ *
+ * Kernel rules are always active. tier_1 always considered. tier_2
+ * only considered when `profile == 'full'`.
+ */
+export function match_prompt(router, prompt, profile = "full", open_files, command) {
+    const tiers = [
+        ["tier_1", _asRuleList(router["tier_1"])],
+    ];
+    if (profile === "full") {
+        tiers.push(["tier_2", _asRuleList(router["tier_2"])]);
+    }
+    const matched_triggers = [];
+    const activated_rules = [];
+    for (const [tier_name, rules] of tiers) {
+        for (const rule of rules) {
+            const rule_id = rule["id"];
+            const rule_triggers = _asTriggerList(rule["triggers"]);
+            let rule_hit = false;
+            for (const trig of rule_triggers) {
+                if (trigger_matches(trig, prompt, open_files, command)) {
+                    matched_triggers.push({ tier: tier_name, rule: rule_id, trigger: trig });
+                    rule_hit = true;
+                }
+            }
+            if (rule_hit) {
+                activated_rules.push({ tier: tier_name, rule: rule_id });
+            }
+        }
+    }
+    // Kernel rules are always active.
+    const kernel = Array.isArray(router["kernel"]) ? router["kernel"] : [];
+    for (const kid of kernel) {
+        activated_rules.push({ tier: "kernel", rule: kid });
+    }
+    return { matched_triggers, activated_rules };
+}
+//# sourceMappingURL=router_match.js.map

package/dist/scripts/_lib/rule_injection.js

@@ -0,0 +1,216 @@
+/**
+ * Rule-injection core — THE single module both the offline model and the
+ * runtime concern read.
+ *
+ * WHY ONE MODULE. `road-to-trigger-delivered-rule-bodies` step 0.5 states the
+ * failure this prevents in as many words: *an experiment whose offline pricing
+ * and runtime delivery use different matchers measures nothing*. So the price /
+ * recall model (`src/scripts/model_rule_injection.ts`) and the delivery concern
+ * (`src/scripts/hooks/rule_inject_hook.ts`) both import THIS file, and neither
+ * re-implements selection, ordering, capping, or body loading.
+ *
+ * IT OWNS NO MATCHER. Trigger semantics belong to
+ * [`_lib/router_match.ts`](router_match.ts), which is already the single
+ * implementation for every surface that answers "which rules fire on this
+ * prompt?" and is pinned by `tests/scripts/router_match_parity.test.ts`. A
+ * second matcher here would be the violation that test exists to catch, so
+ * `matchTierRules` is a thin, deterministic wrapper over `match_prompt` and
+ * nothing more. Step 0.3's pre-registered comparison found no reason to write
+ * one — see `model_rule_injection.ts`'s header for the measured verdict.
+ *
+ * KERNEL IS NEVER INJECTED. The nine kernel rules are in standing context by
+ * definition; injecting one would be paying twice for a body that is already
+ * there. `match_prompt` returns kernel ids in `activated_rules` because kernel
+ * rules are always active — this module filters them out by construction rather
+ * than relying on a caller to remember.
+ *
+ * IT IMPORTS NO TOKENIZER, AND THAT IS A HOT-PATH FACT RATHER THAN A STYLE
+ * CHOICE. `_lib/token_count.ts` resolves `js-tiktoken` AT MODULE LOAD, and the
+ * concern that imports this file is statically reachable from
+ * `concern_registry.ts` — so importing it here made every hook dispatch on
+ * every slot pay a tokenizer load for a concern that is default-OFF and emits
+ * nothing. Measured on this tree: unbinding the concern moved the
+ * `pre_tool_use` p95 from 202 ms to 196 ms, and the CI latency gate went red on
+ * the branch that introduced it while passing on main.
+ *
+ * So the runtime cap is in BYTES. That is not a weaker bound — it is the same
+ * bound in the unit the budget actually enforces: `hook-token-budget.json`
+ * measures "bytes of concern stdout payload fields", so the cap and its
+ * registered row are now the same number instead of two units that need a
+ * conversion factor to compare. The offline model keeps exact-BPE tokens for
+ * its price table, where the tokenizer is the point and nothing is on a hot
+ * path.
+ *
+ * DETERMINISM IS THE CONTRACT, and the collision cases are the reason it needs
+ * stating. Two triggers on the SAME rule collapse to one entry (a rule is
+ * delivered once, however many of its triggers fired) while the trigger count
+ * survives as `score`. Two DIFFERENT rules both firing are returned in router
+ * declaration order, tier_1 before tier_2 — never in match order, which would
+ * make the output depend on trigger authoring order inside a rule. Capping
+ * sorts by descending score with router order as the tie-break, so the same
+ * prompt against the same router always yields the same bytes.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { match_prompt } from './router_match.js';
+/** Kinds of trigger a prompt alone can never fire. */
+export const PATH_TRIGGER_KINDS = ['path_prefix', 'file_pattern'];
+export function loadRouter(repoRoot) {
+    const p = path.join(repoRoot, 'dist', 'router.json');
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+/** Kernel rule ids, as declared by the router. */
+export function kernelIds(router) {
+    const k = Array.isArray(router['kernel']) ? router['kernel'] : [];
+    return new Set(k.map((x) => String(x)));
+}
+function tierEntries(router, tier) {
+    const raw = router[tier];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((r) => ({
+        id: String(r['id'] ?? ''),
+        triggers: Array.isArray(r['triggers']) ? r['triggers'] : [],
+    }));
+}
+/** Every tier rule declared by the router, with its trigger list. */
+export function allTierRules(router) {
+    const out = [];
+    for (const tier of ['tier_1', 'tier_2']) {
+        for (const e of tierEntries(router, tier))
+            out.push({ ...e, tier });
+    }
+    return out;
+}
+/** Rules whose triggers are ALL path-shaped — unreachable from a prompt alone. */
+export function pathOnlyRuleIds(router) {
+    const ids = new Set();
+    for (const r of allTierRules(router)) {
+        if (r.triggers.length === 0)
+            continue;
+        const allPath = r.triggers.every((t) => PATH_TRIGGER_KINDS.some((k) => k in t));
+        if (allPath)
+            ids.add(r.id);
+    }
+    return ids;
+}
+/** Rules declaring at least one path-shaped trigger. */
+export function pathCapableRuleIds(router) {
+    const ids = new Set();
+    for (const r of allTierRules(router)) {
+        if (r.triggers.some((t) => PATH_TRIGGER_KINDS.some((k) => k in t)))
+            ids.add(r.id);
+    }
+    return ids;
+}
+/** Rules declaring no trigger at all — cannot be delivered, must stay eager. */
+export function triggerlessRuleIds(router) {
+    return allTierRules(router)
+        .filter((r) => r.triggers.length === 0)
+        .map((r) => r.id);
+}
+/**
+ * Which tier rules fire on this prompt (+ optional open files / command).
+ *
+ * Kernel is excluded. Order is router declaration order, tier_1 first.
+ */
+export function matchTierRules(router, prompt, openFiles, command) {
+    const kernel = kernelIds(router);
+    const res = match_prompt(router, prompt, 'full', openFiles, command);
+    const scores = new Map();
+    for (const mt of res.matched_triggers) {
+        const id = String(mt.rule ?? '');
+        if (id === '' || kernel.has(id))
+            continue;
+        scores.set(id, (scores.get(id) ?? 0) + 1);
+    }
+    const out = [];
+    let order = 0;
+    for (const r of allTierRules(router)) {
+        const s = scores.get(r.id);
+        if (s === undefined) {
+            order += 1;
+            continue;
+        }
+        out.push({ id: r.id, tier: r.tier, score: s, order });
+        order += 1;
+    }
+    return out;
+}
+/** Where the projected body of a rule lives. */
+export function ruleBodyPath(repoRoot, id) {
+    return path.join(repoRoot, 'dist', 'agent-src', 'rules', `${id}.md`);
+}
+/** The projected body, or `null` when the rule has no projected file. */
+export function loadRuleBody(repoRoot, id) {
+    const p = ruleBodyPath(repoRoot, id);
+    if (!fs.existsSync(p))
+        return null;
+    return fs.readFileSync(p, 'utf8');
+}
+/**
+ * UTF-8 byte length — the runtime measure, dependency-free by design.
+ *
+ * Deliberately NOT a token count: see the header. Bytes are exact, need no
+ * tokenizer, and are the unit `hook-token-budget.json` enforces.
+ */
+export function bytesOf(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+/**
+ * Apply the per-prompt BYTE cap.
+ *
+ * Highest score first, router order as tie-break; a rule whose body would push
+ * the running total past `capBytes` is dropped and the walk continues, so one
+ * oversized body cannot starve the rest. The returned `selected` list is
+ * re-sorted back into router order — cap order is a budgeting concern, delivery
+ * order is not.
+ *
+ * ONE selection for both callers. The offline model and the runtime concern
+ * call THIS function with THE SAME cap, so the set the price table prices is
+ * byte-for-byte the set the concern delivers. That is step 0.5's requirement,
+ * and expressing the cap in bytes makes it hold without a token/byte
+ * conversion sitting between the two arms.
+ */
+export function selectForInjection(repoRoot, matches, capBytes, shortlist) {
+    const bodyBytes = new Map();
+    for (const m of matches) {
+        const body = loadRuleBody(repoRoot, m.id);
+        bodyBytes.set(m.id, body === null ? 0 : bytesOf(body));
+    }
+    // STEP 6.3 — the optional lexical shortlist, as a TIE-BREAK and nothing more.
+    //
+    // Absent (the default), the cap order is exactly what it was: score, then
+    // router order. Present, it sits BETWEEN them, never above `score` — the
+    // matcher's verdict is read first and the shortlist only orders what the
+    // matcher already tied. Membership is untouched in both directions: a
+    // shortlisted id the matcher did not return is not in `matches` and so is
+    // never consulted, and no matched id is dropped for being unshortlisted
+    // (it sorts at Infinity, behind the shortlisted ones, and still competes
+    // for the cap). That is `_lib/lexical_shortlist.ts`'s "never decides
+    // alone" expressed at the one place the cap actually binds.
+    const rank = new Map();
+    for (const [i, id] of (shortlist ?? []).entries()) {
+        if (!rank.has(id))
+            rank.set(id, i);
+    }
+    const ranked = [...matches].sort((a, b) => b.score - a.score ||
+        (rank.get(a.id) ?? Infinity) - (rank.get(b.id) ?? Infinity) ||
+        a.order - b.order);
+    const selected = [];
+    const dropped = [];
+    let total = 0;
+    for (const m of ranked) {
+        const t = bodyBytes.get(m.id) ?? 0;
+        if (total + t > capBytes && selected.length > 0) {
+            dropped.push(m);
+            continue;
+        }
+        selected.push(m);
+        total += t;
+    }
+    selected.sort((a, b) => a.order - b.order);
+    dropped.sort((a, b) => a.order - b.order);
+    return { selected, dropped, bytes: total, bodyBytes };
+}
+//# sourceMappingURL=rule_injection.js.map