@event4u/agent-config 9.3.0 → 9.4.0

package/src/scripts/build_catalog_index.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env tsx
+/**
+ * Build the lazy-catalog index — `dist/catalog-index-v1.json`.
+ *
+ * A queryable metadata index over every skill, persona, and domain command:
+ * `{ id, cls, name, description, tags, path }` — **metadata only, no bodies**.
+ * Bodies load lazily from disk at `catalog_load` time (the stdio server has the
+ * repo underneath it, unlike the upstream Hermes plugin which embeds bodies).
+ *
+ * Feeds the `catalog_search / _inspect / _load` MCP tools (built as discovery
+ * stubs; activation deferred behind a quality A/B — see
+ * road-to-persona-library-harvest.md Phase 2). Deterministic output (entries
+ * sorted by (cls, id), stable keys) so the artifact diffs cleanly. `--check`
+ * fails on drift instead of writing (CI mode), mirroring the
+ * build_mcp_registry_manifest convention.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+// The `-v1` namespace tracks `schema_version` below (per lint_versioned_cache):
+// bump both together on a shape change so any stale cached copy self-invalidates
+// by name rather than being read as the new shape.
+export const OUT = path.join(ROOT, 'dist', 'catalog-index-v1.json');
+
+export type CatalogClass = 'skill' | 'persona' | 'command';
+
+export interface CatalogIndexEntry {
+    /** Globally unique handle: `<cls>:<slug>`. */
+    id: string;
+    cls: CatalogClass;
+    name: string;
+    description: string;
+    /** Domain / packs / tier — for filtering and search-text weighting. */
+    tags: string[];
+    /** Repo-relative path to the body (resolved by catalog_load). */
+    path: string;
+}
+
+const SKILLS_DIR = path.join(ROOT, 'src', 'skills');
+const PERSONAS_DIR = path.join(ROOT, 'src', 'agent-src', 'personas');
+const DOMAINS_DIR = path.join(ROOT, 'src', 'domains');
+
+function _isDir(p: string): boolean {
+    try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+function _isFile(p: string): boolean {
+    try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+function _rel(abs: string): string {
+    return path.relative(ROOT, abs).split(path.sep).join('/');
+}
+
+function _frontmatter(abs: string): Record<string, unknown> {
+    const text = fs.readFileSync(abs, 'utf-8');
+    const m = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (!m || m.index !== 0) return {};
+    try {
+        const fm = parseYaml(m[1] as string, { version: '1.1' });
+        return fm !== null && typeof fm === 'object' && !Array.isArray(fm) ? (fm as Record<string, unknown>) : {};
+    } catch {
+        return {};
+    }
+}
+
+function _str(v: unknown): string {
+    return typeof v === 'string' ? v.trim() : v == null ? '' : String(v);
+}
+function _list(v: unknown): string[] {
+    if (Array.isArray(v)) return v.map((x) => _str(x)).filter((s) => s.length > 0);
+    const s = _str(v);
+    return s ? [s] : [];
+}
+
+function _walkLeaf(dir: string, leaf: string, out: string[]): void {
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const ent of entries) {
+        const full = path.join(dir, ent.name);
+        if (ent.isDirectory() || (ent.isSymbolicLink() && _isDir(full))) _walkLeaf(full, leaf, out);
+        else if (ent.name === leaf) out.push(full);
+    }
+}
+
+export function buildEntries(): CatalogIndexEntry[] {
+    const out: CatalogIndexEntry[] = [];
+
+    // Skills
+    if (_isDir(SKILLS_DIR)) {
+        for (const slug of fs.readdirSync(SKILLS_DIR).sort()) {
+            const abs = path.join(SKILLS_DIR, slug, 'SKILL.md');
+            if (!_isFile(abs)) continue;
+            const fm = _frontmatter(abs);
+            out.push({
+                id: `skill:${slug}`,
+                cls: 'skill',
+                name: _str(fm['name']) || slug,
+                description: _str(fm['description']),
+                tags: [_str(fm['domain']), ..._list(fm['packs'])].filter((s) => s.length > 0),
+                path: _rel(abs),
+            });
+        }
+    }
+
+    // Personas (top-level *.md, skip _template/advisors and underscore-prefixed)
+    if (_isDir(PERSONAS_DIR)) {
+        for (const name of fs.readdirSync(PERSONAS_DIR).sort()) {
+            if (!name.endsWith('.md') || name.startsWith('_')) continue;
+            const abs = path.join(PERSONAS_DIR, name);
+            if (!_isFile(abs)) continue;
+            const fm = _frontmatter(abs);
+            const id = _str(fm['id']) || name.replace(/\.md$/, '');
+            out.push({
+                id: `persona:${id}`,
+                cls: 'persona',
+                name: _str(fm['role']) || id,
+                description: _str(fm['description']),
+                tags: [_str(fm['tier']), _str(fm['mode'])].filter((s) => s.length > 0),
+                path: _rel(abs),
+            });
+        }
+    }
+
+    // Domain commands
+    const cmds: string[] = [];
+    _walkLeaf(DOMAINS_DIR, 'command.md', cmds);
+    for (const abs of cmds.sort()) {
+        const fm = _frontmatter(abs);
+        // logical id = <pack>/<subpath> under src/domains, without /command.md
+        const relFromDomains = path.relative(DOMAINS_DIR, path.dirname(abs)).split(path.sep).join('/');
+        const name = _str(fm['name']) || relFromDomains.split('/').pop() || relFromDomains;
+        out.push({
+            id: `command:${relFromDomains}`,
+            cls: 'command',
+            name,
+            description: _str(fm['description']) || _str(fm['intent']),
+            tags: [_str(fm['pack']), _str(fm['tier']), _str(fm['visibility'])].filter((s) => s.length > 0),
+            path: _rel(abs),
+        });
+    }
+
+    // Deterministic order: (cls, id).
+    out.sort((a, b) => (a.cls < b.cls ? -1 : a.cls > b.cls ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return out;
+}
+
+export function serialize(entries: CatalogIndexEntry[]): string {
+    return JSON.stringify({ schema_version: 1, count: entries.length, entries }, null, 2) + '\n';
+}
+
+export function main(argv?: string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const check = args.includes('--check');
+    const quiet = args.includes('--quiet');
+    const entries = buildEntries();
+    const rendered = serialize(entries);
+
+    if (check) {
+        const current = _isFile(OUT) ? fs.readFileSync(OUT, 'utf-8') : '';
+        if (current !== rendered) {
+            process.stderr.write(`build_catalog_index: DRIFT — ${_rel(OUT)} is stale; run build_catalog_index to regenerate.\n`);
+            return 1;
+        }
+        if (!quiet) process.stdout.write(`build_catalog_index: OK — ${entries.length} entries, index up to date.\n`);
+        return 0;
+    }
+
+    fs.mkdirSync(path.dirname(OUT), { recursive: true });
+    fs.writeFileSync(OUT, rendered, 'utf-8');
+    if (!quiet) process.stdout.write(`build_catalog_index: wrote ${entries.length} entries → ${_rel(OUT)}\n`);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch { return false; }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/council_cli.ts

@@ -98,7 +98,9 @@ import {
 } from './ai_council/orchestrator.js';
 import {
     type PriceTable,
+    downgrade_coupling,
     estimate_cost,
+    estimate_input_tokens,
     load_prices,
     prices_file_for,
 } from './ai_council/pricing.js';
@@ -1605,7 +1607,8 @@ function _necessity_gate(opts: {
 function _resolve_model_downgrade(ai_cfg: Dict, lens: string): [boolean, boolean] {
     const md_block = (ai_cfg['model_downgrade'] as Dict) || {};
     let enabled = md_block['enabled'] === undefined ? true : Boolean(_pyBool(md_block['enabled']));
-    let auto_apply = md_block['auto_apply'] === undefined ? false : Boolean(_pyBool(md_block['auto_apply']));
+    // A3: auto-downgrade is the default; `auto_apply: false` is the opt-out.
+    let auto_apply = md_block['auto_apply'] === undefined ? true : Boolean(_pyBool(md_block['auto_apply']));
     const overrides = ((ai_cfg['lens_overrides'] as Dict) || {})['model_downgrade'] || {};
     const lens_override = _isDict(overrides) ? (overrides as Dict)[lens] : null;
     if (_isDict(lens_override)) {
@@ -1622,6 +1625,10 @@ function _size_fit_gate(opts: {
     members: ExternalAIClient[];
     ai_cfg: Dict;
     stdout?: ((s: string) => void) | null;
+    /** Planned rounds for the run; expected same-model cache reads = rounds − 1. */
+    rounds?: number;
+    /** Price table for the A1↔A3 cache-coupling gate; null → coupling skipped. */
+    price_table?: PriceTable | null;
 }): Array<[string, SizeFitVerdict, boolean]> {
     const out = opts.stdout ?? _stdout;
     const [enabled, auto_apply] = _resolve_model_downgrade(opts.ai_cfg, opts.lens);
@@ -1629,8 +1636,25 @@ function _size_fit_gate(opts: {
     if (!enabled) {
         return decisions;
     }
+    const md_block = (opts.ai_cfg['model_downgrade'] as Dict) || {};
+    const tier_override = (md_block['model_tier_override'] as Dict) || {};
+    const cache_enabled = opts.ai_cfg['prompt_cache'] !== false;
+    const expected_reads = Math.max(0, (opts.rounds ?? 1) - 1);
     const members_cfg = (opts.ai_cfg['members'] as Dict) || {};
     for (const member of opts.members) {
+        // Per-run escape hatch: a member pinned in model_tier_override gets
+        // exactly that model — classifier and coupling both skipped.
+        const pinned = tier_override[member.name];
+        if (typeof pinned === 'string' && pinned.length > 0) {
+            if (pinned !== member.model) {
+                out(
+                    `council:size-fit · ${member.name} · model_tier_override ` +
+                        `\`${member.model}\` → \`${pinned}\` (operator pin)\n`,
+                );
+                member.model = pinned;
+            }
+            continue;
+        }
         const member_cfg = (members_cfg[member.name] as Dict) || {};
         const ladder = (member_cfg['model_ladder'] as string[]) || [];
         if (ladder.length === 0) {
@@ -1639,6 +1663,35 @@ function _size_fit_gate(opts: {
         const verdict = classify_size_fit(opts.prompt, member.model, ladder, opts.lens);
         let applied = false;
         if (!verdict.fit && verdict.suggested_model) {
+            // A1↔A3 coupling: a downgraded member misses the model-scoped
+            // prompt cache — downgrade only when the model saving beats the
+            // forfeited cache reads. No price table → conservative skip is
+            // wrong for the cost goal, so coupling only gates when computable.
+            if (opts.price_table) {
+                const prefix_tokens = estimate_input_tokens(opts.prompt);
+                const coupling = downgrade_coupling(
+                    member.name,
+                    member.model,
+                    verdict.suggested_model,
+                    prefix_tokens,
+                    4096,
+                    {
+                        enabled: cache_enabled,
+                        cacheable_prefix_tokens: prefix_tokens,
+                        expected_reads,
+                    },
+                    opts.price_table,
+                );
+                if (!coupling.net_positive) {
+                    out(
+                        `council:size-fit · ${member.name} · downgrade skipped — ` +
+                            `lost cache savings $${coupling.lost_cache_savings_usd.toFixed(4)} ` +
+                            `≥ model savings $${coupling.downgrade_savings_usd.toFixed(4)}\n`,
+                    );
+                    decisions.push([member.name, verdict, false]);
+                    continue;
+                }
+            }
             if (auto_apply) {
                 out(
                     `council:size-fit · ${member.name} · auto-downgrade ` +
@@ -1845,6 +1898,8 @@ function cmd_run(
         lens: question.mode,
         members,
         ai_cfg,
+        rounds: _getattr(args, 'rounds', 1) as number,
+        price_table: table,
     });
     const project = detect_project_context(REPO_ROOT);
     const billable = members.filter((m) => _getattr(m, 'billable', true));

package/src/scripts/generate_index.ts

@@ -232,7 +232,10 @@ export function _collect_skills(): Entry[] {
                 kind: 'skill',
                 name,
                 description: _truncate(fm['description'] ?? ''),
-                extra: '',
+                // Provenance: `official` unless the skill declares
+                // `provenance: community` (external contribution — credited in
+                // CREDITS.md; the catalog column makes the credit visible).
+                extra: fm['provenance'] ?? 'official',
                 path: _relativeToPosix(skillMd, ROOT),
             });
         }
@@ -372,7 +375,7 @@ export function _render_index(
         '',
         `## Skills (${skills.length})`,
         '',
-        _render_table(skills, ['kind', 'name', 'extra', 'description'], '../'),
+        _render_table(skills, ['kind', 'name', 'source', 'description'], '../'),
         '',
         `## Rules (${rules.length})`,
         '',
@@ -428,7 +431,7 @@ export function _render_catalog(
         '> (`./scripts-run src/scripts/domain_soundness_status`). A disclaimer',
         '> floor bounds liability, not correctness — see [the proof page](proof.md).',
         '',
-        _render_table(skills, ['kind', 'name', 'extra', 'description'], '../', _to_shipped_path),
+        _render_table(skills, ['kind', 'name', 'source', 'description'], '../', _to_shipped_path),
         '',
         `## Rules (${publicRules.length})`,
         '',