@event4u/agent-config 16.2.0 → 16.3.0

package/src/scripts/ai_council/clients.ts

@@ -88,6 +88,7 @@ import * as user_global_paths from '../_lib/user_global_paths.js';
 import { jsonDumpsIndent2 as _jsonDumpsIndent2 } from './_py_json.js';
 import * as budget from './cli_call_budget.js';
 import { appendEvent } from './events_log.js';
+import { OPENAI_CLI_VENDOR_DEFAULT } from './vendor_defaults.js';
 
 export const ANTHROPIC_KEY_FILENAME = 'anthropic.key';
 export const OPENAI_KEY_FILENAME = 'openai.key';
@@ -124,23 +125,12 @@ export const DEFAULT_PERPLEXITY_MODEL = 'sonar-pro';
 // divergence is a one-line change, not a hunt through inline literals.
 // (`xai` / `perplexity` CLI reuse their API constants: their CLIs are
 // community wrappers around the same paid API, so the values do not diverge.)
-/**
- * Sentinel: let the codex CLI pick its own model, by omitting `--model`.
- *
- * This is not a placeholder for a value nobody looked up. Measured
- * 2026-08-15 against `codex exec --json` on a ChatGPT-account (subscription)
- * transport, every explicitly named candidate was refused with
- * `400 invalid_request_error: The '<model>' model is not supported when using
- * Codex with a ChatGPT account.` — `gpt-4o`, `gpt-5` (this constant's previous
- * value) and `gpt-5.1-codex` alike. Omitting the flag answered normally.
- *
- * So the only value known to work on this transport is "whatever the CLI
- * chooses", and pinning ANY name here would re-break the seat the next time
- * the vendor rotates its lineup. The label is carried into records as-is so a
- * reader can see that no model was pinned, rather than a name being implied
- * that nobody verified.
- */
-export const OPENAI_CLI_VENDOR_DEFAULT = 'codex-default';
+// `OPENAI_CLI_VENDOR_DEFAULT` lives in `vendor_defaults.ts`, re-exported here
+// so every existing importer keeps resolving. It moved because `config.ts`
+// wanted that one string and was charged this whole module for it in the
+// composed hook bundle — 51,523 bytes on every dispatch; the reasoning and the
+// measurement are in that file's header.
+export { OPENAI_CLI_VENDOR_DEFAULT } from './vendor_defaults.js';
 
 /**
  * Models MEASURED to be refused by the codex subscription transport, with the
@@ -1011,6 +1001,7 @@ export const CLI_CALLS_FILENAME = 'cli-calls.json';
 export {
     CLI_CALLS_ATTRIBUTION_SUFFIX,
     CLI_CONSUMER_COUNCIL,
+    CLI_CONSUMER_SELF_REVIEW,
     CLI_CONSUMER_TEAM,
     CLI_CONSUMER_UNKNOWN,
     QUOTA_SOURCE_LOCAL_BUDGET,
@@ -1678,16 +1669,22 @@ export function _foldSystemPrompt(system_prompt: string, user_prompt: string): s
 export class AnthropicCliClient extends CliClient {
     override subscription_label = 'claude-pro';
 
+    // `...opts` rather than a field list, in all five CLI subclasses, and the
+    // spread IS the fix rather than a tidy. Each of these constructors used to
+    // name six option fields explicitly and forward those — so when
+    // `CliClientOptions` grew a seventh, `consumer`, every subclass silently
+    // dropped it. Both construction sites passed it, `CliClient` read
+    // `opts.consumer ?? CLI_CONSUMER_UNKNOWN`, and the sidecar recorded
+    // `unknown` for every CLI call ever booked: measured 2026-10-05 as
+    // `{"anthropic":{"unknown":2},"openai":{"unknown":2}}` after a council
+    // round. A field list can forget a field. A spread cannot, so the eighth
+    // option needs no edit here and cannot repeat this.
+    //
+    // `model` stays explicit because it is the one field each subclass
+    // overrides with its own pinned default; everything else passes through.
     constructor(opts: CliClientOptions = {}) {
         super(
-            {
-                model: opts.model ?? DEFAULT_ANTHROPIC_CLI_MODEL,
-                binary: opts.binary,
-                timeout_seconds: opts.timeout_seconds,
-                max_calls_per_day: opts.max_calls_per_day,
-                warn_at: opts.warn_at,
-                cli_calls_path: opts.cli_calls_path,
-            },
+            { ...opts, model: opts.model ?? DEFAULT_ANTHROPIC_CLI_MODEL },
             { name: 'anthropic', default_binary: 'claude' },
         );
     }
@@ -1817,14 +1814,7 @@ export class OpenAICliClient extends CliClient {
 
     constructor(opts: CliClientOptions = {}) {
         super(
-            {
-                model: opts.model ?? DEFAULT_OPENAI_CLI_MODEL,
-                binary: opts.binary,
-                timeout_seconds: opts.timeout_seconds,
-                max_calls_per_day: opts.max_calls_per_day,
-                warn_at: opts.warn_at,
-                cli_calls_path: opts.cli_calls_path,
-            },
+            { ...opts, model: opts.model ?? DEFAULT_OPENAI_CLI_MODEL },
             { name: 'openai', default_binary: 'codex' },
         );
     }
@@ -2064,14 +2054,7 @@ export class GeminiCliClient extends CliClient {
 
     constructor(opts: CliClientOptions = {}) {
         super(
-            {
-                model: opts.model ?? DEFAULT_GEMINI_CLI_MODEL,
-                binary: opts.binary,
-                timeout_seconds: opts.timeout_seconds,
-                max_calls_per_day: opts.max_calls_per_day,
-                warn_at: opts.warn_at,
-                cli_calls_path: opts.cli_calls_path,
-            },
+            { ...opts, model: opts.model ?? DEFAULT_GEMINI_CLI_MODEL },
             { name: 'gemini', default_binary: 'gemini' },
         );
     }
@@ -2217,14 +2200,7 @@ export class XAICliClient extends CliClient {
 
     constructor(opts: CliClientOptions = {}) {
         super(
-            {
-                model: opts.model ?? DEFAULT_XAI_MODEL,
-                binary: opts.binary,
-                timeout_seconds: opts.timeout_seconds,
-                max_calls_per_day: opts.max_calls_per_day,
-                warn_at: opts.warn_at,
-                cli_calls_path: opts.cli_calls_path,
-            },
+            { ...opts, model: opts.model ?? DEFAULT_XAI_MODEL },
             { name: 'xai', default_binary: 'grok' },
         );
     }
@@ -2289,14 +2265,7 @@ export class PerplexityCliClient extends CliClient {
 
     constructor(opts: CliClientOptions = {}) {
         super(
-            {
-                model: opts.model ?? DEFAULT_PERPLEXITY_MODEL,
-                binary: opts.binary,
-                timeout_seconds: opts.timeout_seconds,
-                max_calls_per_day: opts.max_calls_per_day,
-                warn_at: opts.warn_at,
-                cli_calls_path: opts.cli_calls_path,
-            },
+            { ...opts, model: opts.model ?? DEFAULT_PERPLEXITY_MODEL },
             { name: 'perplexity', default_binary: 'perplexity' },
         );
     }

package/src/scripts/ai_council/config.ts

@@ -82,7 +82,7 @@ import * as budget from './cli_call_budget.js';
 // `import type` and is erased at build, so there is no runtime cycle today.
 // Converting it to a value import — or adding any other runtime import from
 // quorum into config — creates a real ESM cycle in the loader's init path.
-import { OPENAI_CLI_VENDOR_DEFAULT } from './clients.js';
+import { OPENAI_CLI_VENDOR_DEFAULT } from './vendor_defaults.js';
 import { parseSeatFields, type PolicyExclusion } from './seat_policy.js';
 import type { ContentClass } from './content_ceiling.js';
 import { SOLO_FLOOR_MIN_PRESENT } from './quorum.js';

package/src/scripts/ai_council/vendor_defaults.ts

@@ -0,0 +1,45 @@
+/**
+ * Vendor-CLI sentinel values that are DATA, carried in a module with no
+ * dependencies of its own.
+ *
+ * WHY THIS FILE EXISTS, measured rather than argued. `OPENAI_CLI_VENDOR_DEFAULT`
+ * is a single string, and it used to live in `clients.ts` beside the transport
+ * classes that compare against it. `ai_council/config.ts` imports that one
+ * string and nothing else from `clients.ts`; `config.ts` is reachable from
+ * `council-availability`, which is bound on `session_start`. So every hook
+ * dispatch on every slot carried the whole council transport layer —
+ * `clients.ts` and its closure, **51,523 bytes** of the composed
+ * `dist/hooks/dispatch.js` — to compare one string against another. Breaking
+ * that one import edge removes exactly that, with no capability removed
+ * anywhere: every entry point that actually talks to a vendor CLI imports
+ * `clients.ts` directly and still does.
+ *
+ * The bytes are not an abstraction. `src/config/hook-bundle-budget.json` caps
+ * the composed bundle, the cap is a shrink-only ratchet, and on 2026-10-02 the
+ * tree stood 75 bytes under it — a state in which no concern anywhere could add
+ * a line. This module is how `road-to-a-rule-carrier-that-works-outside-the-repo`
+ * Phase 1 paid for its own runtime code instead of asking for a raise.
+ *
+ * WHAT BELONGS HERE: a vendor-facing constant that a CONFIGURATION reader needs
+ * and a TRANSPORT reader also happens to use. Nothing that imports anything.
+ * The moment this file gains an import it stops being the cheap half of the
+ * split and the split stops being worth its own file.
+ */
+
+/**
+ * Sentinel: let the codex CLI pick its own model, by omitting `--model`.
+ *
+ * This is not a placeholder for a value nobody looked up. Measured
+ * 2026-08-15 against `codex exec --json` on a ChatGPT-account (subscription)
+ * transport, every explicitly named candidate was refused with
+ * `400 invalid_request_error: The '<model>' model is not supported when using
+ * Codex with a ChatGPT account.` — `gpt-4o`, `gpt-5` (this constant's previous
+ * value) and `gpt-5.1-codex` alike. Omitting the flag answered normally.
+ *
+ * So the only value known to work on this transport is "whatever the CLI
+ * chooses", and pinning ANY name here would re-break the seat the next time
+ * the vendor rotates its lineup. The label is carried into records as-is so a
+ * reader can see that no model was pinned, rather than a name being implied
+ * that nobody verified.
+ */
+export const OPENAI_CLI_VENDOR_DEFAULT = 'codex-default';

package/src/scripts/audit_skill_overlap.ts

@@ -30,6 +30,7 @@
  * quietly until the gate means nothing. Cross-pack pairs never block — a
  * cross-pack merge changes install shape and is a different decision.
  */
+import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -47,6 +48,7 @@ export const OUT_MD_NAME = 'skill-overlap.md';
 export const OUT_JSON = path.join(REPORT_DIR, OUT_JSON_NAME);
 export const OUT_MD = path.join(REPORT_DIR, OUT_MD_NAME);
 export const ALLOWLIST = path.join(ROOT, 'src', 'scripts', 'audit_skill_overlap_allowlist.json');
+export const CROSS_CACHE_NAME = 'neighbour-overlap.json';
 export const ALLOWLIST_CAP = 20;
 // re.compile(r"^---\n(.*?)\n---", re.DOTALL) — used with .search (anywhere).
 const FM_RE = /^---\n([\s\S]*?)\n---/m;
@@ -68,6 +70,8 @@ type Json = any;
 interface Skill {
     name: string;
     relpath: string;
+    /** Absolute `SKILL.md` path — the key a cross-root result is returned under. */
+    abspath: string;
     packs: Set<string>;
     vector: Map<string, number>;
 }
@@ -178,6 +182,7 @@ export function _parse(md: string, field: Field = 'body'): Skill {
     return {
         name: name ? String(name) : path.basename(path.dirname(md)),
         relpath: _relPosix(md, ROOT),
+        abspath: path.resolve(md),
         packs: Array.isArray(packsVal) ? new Set(packsVal.map((x) => String(x))) : new Set(),
         vector: _keyword_vector(source),
     };
@@ -322,6 +327,193 @@ export function find_pairs(skills: Skill[], threshold: number): Pair[] {
     return stableSort(pairs, (p) => [p.same_domain ? 0 : 1, -p.similarity]);
 }
 
+/**
+ * One neighbour skill against one of ours, at or above the threshold.
+ *
+ * `neighbour_path` is absolute, because the two sides live under different roots
+ * and a repo-relative path would be a `../..` string that no caller can key on.
+ */
+export interface CrossPair {
+    neighbour: string;
+    neighbour_path: string;
+    ours: string;
+    similarity: number;
+}
+
+/**
+ * Cross-root pairs: every NEIGHBOUR skill against every one of OURS.
+ *
+ * NOT `find_pairs` over a merged list, and the difference is the whole point of
+ * the mode. `find_pairs` is `combinations(skills, 2)` over one corpus, so a
+ * merged list would also compare our skills against each other — re-deriving the
+ * same-corpus report under a different name, at the cost of the pairs the caller
+ * actually asked for being buried in it. This emits exactly the cross product,
+ * which is also the cheaper half: |neighbours| × |ours| rather than C(n+m, 2).
+ *
+ * The THRESHOLD is the caller's and defaults to {@link OVERLAP_THRESHOLD} — the
+ * same 0.70 every historical same-corpus report is calibrated against. Reusing it
+ * is deliberate: a second, softer bar invented for neighbours would make
+ * `compat: overlapping` mean something no existing number can be compared to.
+ */
+export function crossRootPairs(
+    neighbourRoot: string,
+    ourRoot: string,
+    threshold: number = OVERLAP_THRESHOLD,
+    field: Field = 'body',
+): CrossPair[] {
+    return crossPairsForFiles(skillMdsUnder(neighbourRoot), ourRoot, threshold, field);
+}
+
+/** Non-archived `SKILL.md` paths under a root, in the collector's own order. */
+export function skillMdsUnder(root: string): string[] {
+    return _rglobSkillMd(root).filter((md) => !md.split(path.sep).includes('_archive'));
+}
+
+/**
+ * The same cross product, over an EXPLICIT neighbour file list.
+ *
+ * This is the shape the census actually needs, and the root-taking wrapper above
+ * is the convenience layer rather than the other way round. A census's neighbour
+ * skills are the UNCLAIMED entries of two roots that also hold claimed ones —
+ * `agent-config install` writes our own skills into `~/.claude/skills` — so
+ * pairing a whole root would compare this package's installed copies against its
+ * own source tree and report the install as an overlap.
+ */
+export function crossPairsForFiles(
+    neighbourFiles: readonly string[],
+    ourRoot: string,
+    threshold: number = OVERLAP_THRESHOLD,
+    field: Field = 'body',
+): CrossPair[] {
+    const theirs: Skill[] = [];
+    for (const md of neighbourFiles) {
+        try {
+            theirs.push(_parse(md, field));
+        } catch {
+            // Unreadable neighbour file: not a pair, and not a crash.
+        }
+    }
+    const ours = collect(ourRoot, field);
+    const out: CrossPair[] = [];
+    for (const n of theirs) {
+        for (const o of ours) {
+            const sim = _cosine(n.vector, o.vector);
+            if (sim < threshold) continue;
+            out.push({
+                neighbour: n.name,
+                neighbour_path: n.abspath,
+                ours: o.name,
+                similarity: pyRound(sim, 3),
+            });
+        }
+    }
+    return stableSort(out, (p) => [-p.similarity]);
+}
+
+/**
+ * Cross-root pairs folded the way the census reads them: highest-scoring hit per
+ * neighbour `SKILL.md`, with every our-skill name that crossed the bar.
+ */
+export function crossRootOverlapMap(
+    pairs: readonly CrossPair[],
+): Map<string, { names: string[]; similarity: number }> {
+    const out = new Map<string, { names: string[]; similarity: number }>();
+    for (const p of pairs) {
+        const hit = out.get(p.neighbour_path);
+        if (hit === undefined) {
+            out.set(p.neighbour_path, { names: [p.ours], similarity: p.similarity });
+            continue;
+        }
+        if (!hit.names.includes(p.ours)) hit.names.push(p.ours);
+        if (p.similarity > hit.similarity) hit.similarity = p.similarity;
+    }
+    for (const hit of out.values()) hit.names.sort();
+    return out;
+}
+
+/**
+ * The census digest the cross-root cache is keyed by.
+ *
+ * Over the INPUTS and nothing else: every skill's absolute path and the sha256
+ * of its bytes, on both sides, plus the threshold and the field. Risk-register
+ * row 3 is why a cache exists at all — a pairwise pass per prompt is not a
+ * hook-budget shape — and keying it on the bytes is what makes "a changed digest
+ * rescans first" true rather than aspirational. A key over NAMES alone would
+ * hand a stale score to a body that was rewritten underneath it.
+ */
+export function censusDigest(
+    neighbourFiles: readonly string[],
+    ourRoot: string,
+    threshold: number,
+    field: Field = 'body',
+): string {
+    const h = createHash('sha256');
+    h.update(`${String(threshold)}\n${field}\n`);
+    const sides: ReadonlyArray<readonly string[]> = [
+        [...neighbourFiles].sort(),
+        skillMdsUnder(ourRoot),
+    ];
+    for (const side of sides) {
+        h.update('side\n');
+        for (const md of side) {
+            let bytes: Buffer;
+            try {
+                bytes = fs.readFileSync(md);
+            } catch {
+                continue;
+            }
+            h.update(path.resolve(md));
+            h.update('\0');
+            h.update(createHash('sha256').update(bytes).digest('hex'));
+            h.update('\n');
+        }
+    }
+    return h.digest('hex');
+}
+
+export interface CrossCache {
+    schema_version: 1;
+    digest: string;
+    threshold: number;
+    pairs: CrossPair[];
+}
+
+/**
+ * Cross-root pairs, recomputed only when the census digest moved.
+ *
+ * A cache miss is never silent: the result says `cached: false`, so a caller
+ * reporting "this came from the cache" cannot be reporting it about a pass that
+ * actually ran. A write failure is not fatal — the pairs are correct either way,
+ * and refusing to answer because a report directory is read-only would turn a
+ * cache into a dependency.
+ */
+export function cachedCrossRootPairs(
+    neighbourFiles: readonly string[],
+    ourRoot: string,
+    cacheFile: string,
+    threshold: number = OVERLAP_THRESHOLD,
+    field: Field = 'body',
+): { pairs: CrossPair[]; digest: string; cached: boolean } {
+    const digest = censusDigest(neighbourFiles, ourRoot, threshold, field);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cacheFile, 'utf-8')) as Partial<CrossCache>;
+        if (parsed.digest === digest && Array.isArray(parsed.pairs)) {
+            return { pairs: parsed.pairs as CrossPair[], digest, cached: true };
+        }
+    } catch {
+        // No cache, or an unreadable one: compute.
+    }
+    const pairs = crossPairsForFiles(neighbourFiles, ourRoot, threshold, field);
+    const payload: CrossCache = { schema_version: 1, digest, threshold, pairs };
+    try {
+        fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+        fs.writeFileSync(cacheFile, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+    } catch {
+        // A cache that cannot be written is still a correct answer.
+    }
+    return { pairs, digest, cached: false };
+}
+
 /** Stable sort by a tuple-of-numbers key (Python tuple compare). */
 function stableSort<T>(arr: T[], key: (x: T) => number[]): T[] {
     return arr
@@ -484,6 +676,9 @@ class FloatTag {
 export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
     const root = args.root ?? _default_skill_root();
+    if (args.neighbourRoot !== undefined) {
+        return _mainCrossRoot(args, root);
+    }
     const skills = collect(root, args.field);
     try {
         assertScanned({
@@ -570,6 +765,55 @@ export function main(argv: string[] | null = null): number {
     return 1;
 }
 
+/**
+ * `--neighbour-root` — the cross-root pair mode.
+ *
+ * A SECOND QUESTION, not a second answer to the first. The same-corpus report
+ * asks "are two of our skills so alike that one should absorb the other", and a
+ * merge is the action it leads to. This asks "is a skill another package
+ * installed close enough to one of ours that a reader of the route line needs to
+ * know", and NOTHING is merged, removed or suppressed on the answer — the
+ * neighbour is not ours to merge. So it writes its own artifact and leaves
+ * `skill-overlap.json` alone.
+ *
+ * Exit 0 always. A finding here is a report; `--strict` belongs to the
+ * same-corpus mode, where the pair is between two files this package owns.
+ */
+function _mainCrossRoot(args: Args, ourRoot: string): number {
+    const neighbourRoot = args.neighbourRoot as string;
+    const outDir = args.outDir ?? REPORT_DIR;
+    const cacheFile = args.crossCache ?? path.join(outDir, CROSS_CACHE_NAME);
+    const { pairs, digest, cached } = cachedCrossRootPairs(
+        skillMdsUnder(neighbourRoot),
+        ourRoot,
+        cacheFile,
+        args.threshold,
+        args.field,
+    );
+    const theirs = collect(neighbourRoot, args.field);
+    // The counts line the gate-coverage contract asks for, on stderr like its
+    // sibling, so the report body on stdout stays machine-readable.
+    process.stderr.write(`scanned: ${String(theirs.length)}\n`);
+    if (!args.quiet) {
+        process.stdout.write(
+            `\u2705  Neighbour overlap: ${theirs.length} neighbour skill(s) \u00d7 ` +
+                `${collect(ourRoot, args.field).length} of ours, ${pairs.length} pair(s) ` +
+                `\u2265 ${_pct(args.threshold)} (${cached ? 'from cache' : 'recomputed'}).\n`,
+        );
+        process.stdout.write(`   census digest: ${digest.slice(0, 12)}\n`);
+        process.stdout.write(`   cache: ${_relPosix(cacheFile, ROOT)}\n`);
+    }
+    const byPath = crossRootOverlapMap(pairs);
+    for (const skill of theirs) {
+        const hit = byPath.get(skill.abspath);
+        if (hit === undefined) continue;
+        process.stdout.write(
+            `   ${hit.similarity.toFixed(3)}  ${skill.name}  also: ${hit.names.join(', ')}\n`,
+        );
+    }
+    return 0;
+}
+
 /** Order-independent key for an unordered pair. */
 export function _pairKey(a: string, b: string): string {
     return a < b ? `${a}::${b}` : `${b}::${a}`;
@@ -662,6 +906,10 @@ interface Args {
     strict: boolean;
     /** Allowlist path override (tests); `undefined` = the shipped file. */
     allowlist?: string;
+    /** Cross-root mode: the NEIGHBOUR tree to pair against `--root`. */
+    neighbourRoot?: string;
+    /** Cross-root cache path; `undefined` = `<out-dir>/neighbour-overlap.json`. */
+    crossCache?: string;
     /** Which text the vector is built from. `description` is NON-canonical. */
     field: Field;
 }
@@ -698,6 +946,19 @@ export function parse_args(argv: string[]): Args {
         } else if (a === '--threshold' || a.startsWith('--threshold=')) {
             const inline = a.startsWith('--threshold=') ? a.slice('--threshold='.length) : undefined;
             args.threshold = Number(takeValue('--threshold', inline, () => argv[++i]));
+        } else if (a === '--neighbour-root' || a.startsWith('--neighbour-root=')) {
+            const inline = a.startsWith('--neighbour-root=')
+                ? a.slice('--neighbour-root='.length)
+                : undefined;
+            args.neighbourRoot = path.resolve(
+                ROOT,
+                takeValue('--neighbour-root', inline, () => argv[++i]),
+            );
+        } else if (a === '--cross-cache' || a.startsWith('--cross-cache=')) {
+            const inline = a.startsWith('--cross-cache=')
+                ? a.slice('--cross-cache='.length)
+                : undefined;
+            args.crossCache = path.resolve(ROOT, takeValue('--cross-cache', inline, () => argv[++i]));
         } else if (a === '--root' || a.startsWith('--root=')) {
             const inline = a.startsWith('--root=') ? a.slice('--root='.length) : undefined;
             args.root = path.resolve(ROOT, takeValue('--root', inline, () => argv[++i]));