@event4u/agent-config 6.0.0 → 7.0.0

package/src/scripts/ai_council/solo_dispatch.ts

@@ -0,0 +1,281 @@
+/**
+ * Solo-member dispatch — step-9 P9 (U2).
+ *
+ * TypeScript twin of `src/scripts/ai_council/solo_dispatch.py` (ADR-200 —
+ * Python→TS migration, Phase 1). Picks the first enabled, auth-valid member
+ * from `routing.solo_member_fallback_chain` so low-impact decisions can
+ * optionally route to a single member instead of the full council. The
+ * selection is intentionally side-effect-free: callers own logging,
+ * dispatch, and the all-invalid → full-council fallback.
+ *
+ * Iron Law: a null selection from `select_solo_member` is the caller's
+ * signal to fall back to the full council with a WARN log — NEVER to fail
+ * the decision. The dispatcher must never break a user's flow because a CLI
+ * was offline.
+ *
+ * Parity notes:
+ * - `time.monotonic()` → `performance.now() / 1000` (seconds, monotonic).
+ * - `os.environ` → `process.env`.
+ * - `should_escalate(solo, floor=…)` keyword call → positional `(solo, floor)`
+ *   in the confidence_gate twin.
+ * - `except Exception` around the probe mirrors Python's broad catch (any
+ *   thrown value → auth-invalid).
+ */
+import { type EscalationDecision, should_escalate } from './confidence_gate.js';
+import type { MemberConfig, RoutingConfig } from './config.js';
+
+//: TTL for cached auth-probe results. Lazy probe per session; bumped
+//: forward whenever a probe is re-run.
+const _AUTH_CACHE_TTL_SECONDS = 15 * 60;
+
+//: Env var that forces every solo-dispatch path back to full council
+//: for the current invocation. Honored by `select_solo_member` and
+//: surfaced through `force_full_council`.
+export const FORCE_FULL_ENV = 'AGENT_CONFIG_FORCE_FULL_COUNCIL';
+
+/** One auth-probe result with the expiry it was cached against. */
+export class AuthCacheEntry {
+    valid: boolean;
+    expires_at: number;
+
+    constructor(args: { valid: boolean; expires_at: number }) {
+        this.valid = args.valid;
+        this.expires_at = args.expires_at;
+    }
+}
+
+/** In-memory cache for auth-probe verdicts (per-process). */
+export class AuthCache {
+    entries: Map<string, AuthCacheEntry>;
+
+    constructor(entries?: Map<string, AuthCacheEntry>) {
+        this.entries = entries ?? new Map<string, AuthCacheEntry>();
+    }
+
+    get(name: string, opts: { now: number }): boolean | null {
+        const entry = this.entries.get(name);
+        if (entry === undefined || entry.expires_at <= opts.now) {
+            return null;
+        }
+        return entry.valid;
+    }
+
+    set(name: string, opts: { valid: boolean; now: number }): void {
+        this.entries.set(
+            name,
+            new AuthCacheEntry({
+                valid: opts.valid,
+                expires_at: opts.now + _AUTH_CACHE_TTL_SECONDS,
+            }),
+        );
+    }
+}
+
+/** Read-only mapping accessor mirroring Python `Mapping.get` semantics. */
+function _mapGet<V>(m: ReadonlyMap<string, V> | undefined | null, key: string): V | undefined {
+    if (m === undefined || m === null) {
+        return undefined;
+    }
+    return m.get(key);
+}
+
+/**
+ * Return True iff the env-var override is set to `1`.
+ *
+ * Truthy values other than `1` are intentionally rejected — the override
+ * is a hard one-bit switch, not a free-form bool.
+ */
+export function force_full_council(env?: ReadonlyMap<string, string> | Record<string, string> | null): boolean {
+    let value: string;
+    if (env === undefined || env === null) {
+        // Python: src = os.environ; src.get(FORCE_FULL_ENV, "")
+        value = process.env[FORCE_FULL_ENV] ?? '';
+    } else if (env instanceof Map) {
+        value = env.get(FORCE_FULL_ENV) ?? '';
+    } else {
+        const v = (env as Record<string, string>)[FORCE_FULL_ENV];
+        value = v === undefined ? '' : v;
+    }
+    return value === '1';
+}
+
+export interface SelectSoloMemberOptions {
+    auth_cache: AuthCache;
+    probe: (name: string, timeout_s: number) => boolean;
+    now?: number | null;
+    env?: ReadonlyMap<string, string> | Record<string, string> | null;
+}
+
+/**
+ * Return the first chain entry whose member is enabled + auth-valid.
+ *
+ * Walks `routing.solo_member_fallback_chain` in order. For each entry:
+ * skip when the member is missing or disabled; consult the auth cache;
+ * on miss probe lazily with the configured timeout and cache the result.
+ * Returns the provider name of the first valid member, or `null` when
+ * every chain entry is unavailable.
+ *
+ * `probe(name, timeout_s) -> boolean` is the caller-supplied auth check.
+ * It MUST honor `timeout_s` and return false on timeout so the dispatcher
+ * cannot stall on a wedged CLI.
+ *
+ * Env-var override (`AGENT_CONFIG_FORCE_FULL_COUNCIL=1`) short-circuits to
+ * null, treating the whole chain as unavailable.
+ */
+export function select_solo_member(
+    routing: RoutingConfig,
+    members: ReadonlyMap<string, MemberConfig>,
+    opts: SelectSoloMemberOptions,
+): string | null {
+    const env = opts.env ?? null;
+    if (force_full_council(env)) {
+        return null;
+    }
+    let now = opts.now ?? null;
+    if (now === null) {
+        now = _monotonic();
+    }
+    const timeout_s = routing.auth_check_timeout_seconds;
+    for (const name of routing.solo_member_fallback_chain) {
+        const member = _mapGet(members, name);
+        if (member === undefined || !member.enabled) {
+            continue;
+        }
+        const cached = opts.auth_cache.get(name, { now });
+        if (cached === false) {
+            continue;
+        }
+        if (cached === true) {
+            return name;
+        }
+        let valid: boolean;
+        try {
+            valid = Boolean(opts.probe(name, timeout_s));
+        } catch {
+            // Probe blew up — treat as auth-invalid so the chain walks to
+            // the next entry. (Callers should log probe failures.)
+            valid = false;
+        }
+        opts.auth_cache.set(name, { valid, now });
+        if (valid) {
+            return name;
+        }
+    }
+    return null;
+}
+
+/**
+ * Outcome of `dispatch_with_escalation`.
+ *
+ * `verdict` is the final answer text returned to the caller. `escalated`
+ * is true when the solo response was rejected by the confidence gate and
+ * the full council ran. `solo_member` / `solo_response` are populated even
+ * on escalation so the shadow log can record both sides without re-running
+ * the solo step.
+ */
+export class SoloDispatchResult {
+    readonly verdict: string;
+    readonly escalated: boolean;
+    /** 'low_confidence' | 'split' | 'refusal' | 'short_response' | 'ok' | 'no_solo_member' */
+    readonly escalation_reason: string;
+    readonly solo_member: string | null;
+    readonly solo_response: string | null;
+    readonly solo_confidence: number | null;
+
+    constructor(args: {
+        verdict: string;
+        escalated: boolean;
+        escalation_reason: string;
+        solo_member: string | null;
+        solo_response: string | null;
+        solo_confidence: number | null;
+    }) {
+        this.verdict = args.verdict;
+        this.escalated = args.escalated;
+        this.escalation_reason = args.escalation_reason;
+        this.solo_member = args.solo_member;
+        this.solo_response = args.solo_response;
+        this.solo_confidence = args.solo_confidence;
+    }
+}
+
+export interface DispatchWithEscalationOptions {
+    auth_cache: AuthCache;
+    probe: (name: string, timeout_s: number) => boolean;
+    run_solo: (name: string) => string;
+    run_full: () => string;
+    confidence_floor: number;
+    now?: number | null;
+    env?: ReadonlyMap<string, string> | Record<string, string> | null;
+}
+
+/**
+ * Solo-dispatch with auto-escalation on low-confidence / split / refusal.
+ *
+ * Step-9 P13 — defense-in-depth on top of shadow-mode SLO.
+ *
+ * Flow:
+ *
+ * 1. `select_solo_member` picks the chain entry.
+ * 2. null → escalate immediately (`no_solo_member`).
+ * 3. `run_solo` is invoked; response is scored via `should_escalate`.
+ * 4. Verdict `escalate=true` → `run_full` is invoked and that verdict is
+ *    returned; the solo response stays on the result for shadow logging.
+ * 5. `escalate=false` → solo verdict is returned as-is.
+ *
+ * `run_solo(name) -> string` and `run_full() -> string` are caller-
+ * supplied; this module owns no LLM transport. Callers MUST throw on
+ * transport errors — escalation is for *content* low-confidence, not
+ * infrastructure failures.
+ */
+export function dispatch_with_escalation(
+    routing: RoutingConfig,
+    members: ReadonlyMap<string, MemberConfig>,
+    opts: DispatchWithEscalationOptions,
+): SoloDispatchResult {
+    const name = select_solo_member(routing, members, {
+        auth_cache: opts.auth_cache,
+        probe: opts.probe,
+        now: opts.now ?? null,
+        env: opts.env ?? null,
+    });
+    if (name === null) {
+        return new SoloDispatchResult({
+            verdict: opts.run_full(),
+            escalated: true,
+            escalation_reason: 'no_solo_member',
+            solo_member: null,
+            solo_response: null,
+            solo_confidence: null,
+        });
+    }
+    const solo = opts.run_solo(name);
+    const decision: EscalationDecision = should_escalate(solo, opts.confidence_floor);
+    if (decision.escalate) {
+        return new SoloDispatchResult({
+            verdict: opts.run_full(),
+            escalated: true,
+            escalation_reason: decision.reason,
+            solo_member: name,
+            solo_response: solo,
+            solo_confidence: decision.confidence,
+        });
+    }
+    return new SoloDispatchResult({
+        verdict: solo,
+        escalated: false,
+        escalation_reason: 'ok',
+        solo_member: name,
+        solo_response: solo,
+        solo_confidence: decision.confidence,
+    });
+}
+
+/** Mirror Python `time.monotonic()` — monotonic seconds. */
+function _monotonic(): number {
+    return performance.now() / 1000;
+}
+
+// Python: __all__ exposes AUTH_CACHE_TTL_SECONDS (the public alias of the
+// private _AUTH_CACHE_TTL_SECONDS, assigned after __all__ in the source).
+export const AUTH_CACHE_TTL_SECONDS = _AUTH_CACHE_TTL_SECONDS;

package/src/scripts/analysis_freshness.ts

@@ -0,0 +1,343 @@
+#!/usr/bin/env tsx
+/**
+ * Project-analysis freshness loop — a cheap *heuristic* staleness signal.
+ *
+ * TypeScript twin of `src/scripts/analysis_freshness.py` (ADR-200,
+ * Python→TypeScript migration). The CLI contract is mirrored EXACTLY — the
+ * required mutually-exclusive group (`--stamp FILE | --stamp-all | --check FILE
+ * | --check-all`), the argparse usage banner + error text (missing required
+ * group → exit 2, conflicting args → exit 2, missing value → exit 2,
+ * `-h`/`--help` → exit 0), the git probe (`git -C REPO_ROOT … check=False`,
+ * stdout stripped), the freshness-header regex + path-token regex, the
+ * staleness bands, `sorted(ANALYSIS_DIR.glob("*.md"))`, and byte-identical
+ * stdout. snake_case kept.
+ *
+ * `project-analyzer` output under ``agents/evidence/analysis/*.md`` is rich but
+ * has no signal for *"is this still current?"*. This script adds a one-line
+ * freshness header and a probe that tells the agent whether a high-tier
+ * re-analysis is likely worth it. File-first, no runtime.
+ *
+ * Header shape (top of each analysis file):
+ *
+ *     <!-- analyzed: 2026-06-15 | commit: 57588489 | files: 4 -->
+ *
+ * Usage:
+ *   python3 src/scripts/analysis_freshness.py --stamp agents/evidence/analysis/foo.md
+ *   python3 src/scripts/analysis_freshness.py --stamp-all
+ *   python3 src/scripts/analysis_freshness.py --check agents/evidence/analysis/foo.md
+ *   python3 src/scripts/analysis_freshness.py --check-all
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+// _HERE = Path(__file__).resolve().parent ; REPO_ROOT = _HERE.parent.parent
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+// Mutable binding so tests can sandbox the scan target (mirrors the pytest
+// monkeypatch.setattr seam used by sibling lint twins).
+let ANALYSIS_DIR = path.join(REPO_ROOT, 'agents', 'evidence', 'analysis');
+
+function _setAnalysisDirForTest(p: string): void {
+    ANALYSIS_DIR = p;
+}
+
+// _HEADER_RE = re.compile(
+//   r"<!--\s*analyzed:\s*(?P<date>[\d-]+)\s*\|\s*commit:\s*(?P<commit>[0-9a-f]+)"
+//   r"\s*\|\s*files:\s*(?P<files>\d+)\s*-->")
+const _HEADER_RE =
+    /<!--[\s]*analyzed:[\s]*(?<date>[\d-]+)[\s]*\|[\s]*commit:[\s]*(?<commit>[0-9a-f]+)[\s]*\|[\s]*files:[\s]*(?<files>\d+)[\s]*-->/;
+// _PATH_RE = re.compile(r"`(?P<p>(?:src|docs|agents|scripts|tests)/[\w./-]+)`")
+const _PATH_RE = /`(?<p>(?:src|docs|agents|scripts|tests)\/[\w./-]+)`/g;
+
+// Heuristic staleness bands by count of changed files over the analyzed paths.
+const _AGING = 1;
+const _STALE = 8;
+
+/**
+ * subprocess.run(["git", "-C", REPO_ROOT, *args], capture_output=True,
+ * text=True, check=False).stdout.strip()
+ *
+ * Python `str.strip()` removes leading + trailing whitespace; `text=True`
+ * decodes stdout as UTF-8. On a non-zero exit, stdout is still returned
+ * (check=False), and a failure to spawn yields "" (mirrors empty stdout).
+ */
+function _git(...args: string[]): string {
+    const res = spawnSync('git', ['-C', REPO_ROOT, ...args], { encoding: 'utf8' });
+    const out = res.stdout ?? '';
+    return _pyStrip(out);
+}
+
+/** Python str.strip() — strips the ASCII + Unicode whitespace set Python uses. */
+function _pyStrip(s: string): string {
+    // Python str.strip() default whitespace: spaces, \t \n \r \v \f and a set
+    // of Unicode whitespace. For git output the ASCII set is sufficient; mirror
+    // \s plus the explicit C0 set Python treats as whitespace.
+    return s.replace(/^[\s… ]+/, '').replace(/[\s… ]+$/, '');
+}
+
+function _head_short(): string {
+    return _git('rev-parse', '--short', 'HEAD') || 'unknown';
+}
+
+/** Best-effort: repo paths the doc cites (deduped, existing only). */
+function _referenced_paths(text: string): string[] {
+    const seen: string[] = [];
+    _PATH_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = _PATH_RE.exec(text)) !== null) {
+        const p = m.groups?.p as string;
+        if (!seen.includes(p) && _exists(path.join(REPO_ROOT, p))) {
+            seen.push(p);
+        }
+    }
+    return seen;
+}
+
+function _exists(p: string): boolean {
+    try {
+        fs.statSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function cmd_stamp(p: string): number {
+    const text = fs.readFileSync(p, 'utf-8');
+    const paths = _referenced_paths(text);
+    // Backfill the analyzed date from the file's own last commit (honest for
+    // retro-stamps); go-forward stamps land on today via a fresh re-stamp.
+    const date = _git('log', '-1', '--format=%cs', '--', p) || _git('log', '-1', '--format=%cs');
+    const header = `<!-- analyzed: ${date} | commit: ${_head_short()} | files: ${paths.length} -->`;
+    const body = _HEADER_RE.test(text)
+        ? _lstripNewlines(_subFirst(_HEADER_RE, text, ''))
+        : text;
+    fs.writeFileSync(p, header + '\n' + body, 'utf-8');
+    process.stdout.write(`  stamped ${_relToRoot(p)} → ${header}\n`);
+    return 0;
+}
+
+/** re.sub(pattern, "", text, count=1) — replace first match only. */
+function _subFirst(re: RegExp, text: string, repl: string): string {
+    const m = re.exec(text);
+    if (!m) {
+        return text;
+    }
+    return text.slice(0, m.index) + repl + text.slice(m.index + m[0].length);
+}
+
+/** str.lstrip("\n") — strip leading newlines only. */
+function _lstripNewlines(s: string): string {
+    return s.replace(/^\n+/, '');
+}
+
+function _relToRoot(p: string): string {
+    return path.relative(REPO_ROOT, p).split(path.sep).join('/');
+}
+
+function cmd_check(p: string): number {
+    const text = fs.readFileSync(p, 'utf-8');
+    const m = _HEADER_RE.exec(text);
+    if (!m) {
+        process.stdout.write(`  ⚠️  ${_relToRoot(p)} — no freshness header (run --stamp)\n`);
+        return 0;
+    }
+    const commit = m.groups?.commit as string;
+    const paths = _referenced_paths(text);
+    const scope = paths.length ? paths : ['.'];
+    let changed = _git('diff', '--name-only', `${commit}..HEAD`, '--', ...scope).split('\n');
+    changed = changed.filter((c) => _pyStrip(c) !== '');
+    const n = changed.length;
+    const band =
+        n === 0 ? 'fresh' : n < _STALE ? 'aging' : 'STALE — re-analysis likely worth it';
+    let verdict: string;
+    if (n >= _AGING) {
+        verdict = n >= _STALE ? `⚠️  ${band}` : `·  ${band}`;
+    } else {
+        verdict = '✅  fresh';
+    }
+    process.stdout.write(
+        `  ${verdict} — ${_relToRoot(p)}: ${n} changed file(s) ` +
+            `over ${scope.length} analyzed path(s) since ${commit}\n`,
+    );
+    return 0;
+}
+
+/** sorted(ANALYSIS_DIR.glob("*.md")). */
+function _iter_analysis(): string[] {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(ANALYSIS_DIR, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    const out: string[] = [];
+    for (const ent of entries) {
+        // glob("*.md") matches files + dirs ending in .md, non-recursively.
+        if (ent.name.endsWith('.md')) {
+            out.push(path.join(ANALYSIS_DIR, ent.name));
+        }
+    }
+    out.sort();
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// argparse-faithful CLI
+// ---------------------------------------------------------------------------
+
+const _PROG = 'analysis_freshness.py';
+const _USAGE =
+    `usage: ${_PROG} [-h]\n` +
+    `                             (--stamp FILE | --stamp-all | --check FILE | --check-all)\n`;
+
+interface Args {
+    stamp: string | null;
+    stamp_all: boolean;
+    check: string | null;
+    check_all: boolean;
+}
+
+class ArgError {
+    constructor(public readonly code: number) {}
+}
+
+function _argError(msg: string): never {
+    process.stderr.write(_USAGE + `${_PROG}: error: ${msg}\n`);
+    throw new ArgError(2);
+}
+
+function _parseArgs(argv: readonly string[]): Args {
+    // Mirror argparse's parse_args precedence for this parser:
+    //   1. -h/--help  → print + exit 0 (fires immediately on encounter).
+    //   2. missing value (--stamp / --check with no following token) → exit 2.
+    //   3. mutex conflict (two group members) → exit 2 (during parse).
+    //   4. required-group-not-satisfied → exit 2 (end of parse_known_args).
+    //   5. unrecognized extras → exit 2 (after parse_known_args returns,
+    //      only when 4 passed). Extras are collected, then reported together.
+    let stamp: string | null = null;
+    let stamp_all = false;
+    let check: string | null = null;
+    let check_all = false;
+    let firstSeen: string | null = null;
+    const extras: string[] = [];
+
+    const conflict = (current: string): void => {
+        if (firstSeen !== null && firstSeen !== current) {
+            _argError(`argument ${current}: not allowed with argument ${firstSeen}`);
+        }
+        if (firstSeen === null) {
+            firstSeen = current;
+        }
+    };
+
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i] as string;
+        if (a === '-h' || a === '--help') {
+            // argparse prints full help (usage + description + options) and
+            // exits 0. Tests do NOT byte-compare help prose; print the usage
+            // banner (deterministic head) and exit 0.
+            process.stdout.write(_USAGE);
+            throw new ArgError(0);
+        }
+        if (a === '--stamp') {
+            const v = argv[i + 1];
+            if (v === undefined) {
+                _argError('argument --stamp: expected one argument');
+            }
+            conflict('--stamp');
+            stamp = v as string;
+            i += 2;
+            continue;
+        }
+        if (a === '--check') {
+            const v = argv[i + 1];
+            if (v === undefined) {
+                _argError('argument --check: expected one argument');
+            }
+            conflict('--check');
+            check = v as string;
+            i += 2;
+            continue;
+        }
+        if (a === '--stamp-all') {
+            conflict('--stamp-all');
+            stamp_all = true;
+            i += 1;
+            continue;
+        }
+        if (a === '--check-all') {
+            conflict('--check-all');
+            check_all = true;
+            i += 1;
+            continue;
+        }
+        // Unknown token: collect, defer error to after the required-group check.
+        extras.push(a);
+        i += 1;
+    }
+
+    // 4. Required mutex group must be satisfied (fires before the extras check).
+    if (firstSeen === null) {
+        _argError('one of the arguments --stamp --stamp-all --check --check-all is required');
+    }
+
+    // 5. Now report any unrecognized extras (group was satisfied).
+    if (extras.length) {
+        _argError(`unrecognized arguments: ${extras.join(' ')}`);
+    }
+
+    return { stamp, stamp_all, check, check_all };
+}
+
+function main(argv?: readonly string[]): number {
+    let args: Args;
+    try {
+        args = _parseArgs(argv ?? process.argv.slice(2));
+    } catch (exc) {
+        if (exc instanceof ArgError) {
+            return exc.code;
+        }
+        throw exc;
+    }
+
+    if (args.stamp !== null) {
+        return cmd_stamp(args.stamp);
+    }
+    if (args.check !== null) {
+        return cmd_check(args.check);
+    }
+    if (args.stamp_all) {
+        for (const p of _iter_analysis()) {
+            cmd_stamp(p);
+        }
+        return 0;
+    }
+    if (args.check_all) {
+        for (const p of _iter_analysis()) {
+            cmd_check(p);
+        }
+        return 0;
+    }
+    return 0;
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    process.exitCode = main();
+}
+
+export {
+    REPO_ROOT,
+    ANALYSIS_DIR,
+    _setAnalysisDirForTest,
+    cmd_stamp,
+    cmd_check,
+    main,
+};