@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/ai_council/recouncil_guard.ts

@@ -0,0 +1,293 @@
+/**
+ * The re-council guard — warn before paying twice for one deliberation.
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence` Phase 1A. The
+ * phase's own framing is the design constraint: *"the cheapest quality
+ * improvement is not paying twice for the same deliberation"*, and it sits
+ * before any sophisticated routing on purpose.
+ *
+ * FOUR CONSTRAINTS FROM THE STEPS, EACH LOAD-BEARING:
+ *
+ *   1A.1 Reuse the EXISTING question hash. `_sha256_hex` is imported from
+ *        `blind_review.ts`, not reimplemented — two hashes of one question are
+ *        two answers to "is this the same question", and the second is the one
+ *        nobody updates.
+ *   1A.2 WARN, NEVER PROHIBIT. {@link RecouncilVerdict} carries no field a
+ *        caller could read as a block, which is stronger than a documented
+ *        promise not to block: there is nothing to misread.
+ *   1A.3 Near-duplicate detection on the ALREADY-IMPORTED similarity
+ *        mechanism — `trigrams` from `_lib/lexical_index.ts`, the BM25 core
+ *        ADR-061 already sanctions. No embeddings, no new infrastructure. The
+ *        threshold is PRE-REGISTERED below, before any tuning on the retained
+ *        corpus.
+ *   1A.4 Three states, distinguishable: exact + same config, exact + stale
+ *        config, near-duplicate.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { jaccardSimilarity, MERGE_THRESHOLD } from '../_lib/text_similarity.js';
+import { _sha256_hex } from './blind_review.js';
+
+/**
+ * The near-duplicate threshold — and it is REUSED, not chosen.
+ *
+ * Step 1A.3 asks for the threshold to be pre-registered before any tuning on
+ * the retained local corpus. `MERGE_THRESHOLD` in `_lib/text_similarity.ts` is
+ * already that: fixed by an AI-council verdict of 2026-07-05 as the point at
+ * which two texts are treated as duplicates, long before this guard existed and
+ * with no knowledge of the council-question corpus it is now applied to. A
+ * number nobody could have tuned against this corpus is the strongest form of
+ * pre-registration available, and re-declaring `0.8` here would fork it — the
+ * same defect 1A.1 forbids for the hash.
+ *
+ * `revisit-if`: the retained corpus produces a false positive at this value
+ * (two questions a human calls different, scored at or above it), or a
+ * one-sentence rewrite of a real question scores below it. Either falsifies the
+ * number, and the fix then belongs in `text_similarity.ts` where its other
+ * consumers can see it move.
+ */
+export const NEAR_DUPLICATE_THRESHOLD = MERGE_THRESHOLD;
+
+/** The three states step 1A.4 requires the warning to distinguish. */
+export type RepeatState =
+    /** Same question text, and the configuration that would run it is unchanged. */
+    | 'exact-same-config'
+    /** Same question text, but the members or round count have moved since. */
+    | 'exact-stale-config'
+    /** Not the same text, but above the pre-registered similarity threshold. */
+    | 'near-duplicate';
+
+/** One prior run, as read from a retained response artefact. */
+export interface PriorRun {
+    /** Path of the retained artefact. */
+    readonly artifactPath: string;
+    /** The question file it ran over, as the artefact recorded it. */
+    readonly questionPath: string;
+    /** ISO date of the artefact, for the warning's "prior run date". */
+    readonly ranAt: string;
+    /** Sorted member ids + round count — the "relevant configuration". */
+    readonly configFingerprint: string;
+    /** `_sha256_hex` of the question text, when the question file still exists. */
+    readonly questionHash: string | null;
+    /** The question text, for the near-duplicate pass. `null` when the file is gone. */
+    readonly questionText: string | null;
+}
+
+/**
+ * A finding. There is DELIBERATELY no `block`, `refuse` or `severity` field:
+ * step 1A.2 requires that no code path can turn this into an unconditional
+ * block, and a type that cannot express one is the strongest available form of
+ * that guarantee.
+ */
+export interface RecouncilVerdict {
+    readonly state: RepeatState;
+    readonly prior: PriorRun;
+    /** Token Jaccard against the prior question, 0..1. Exactly 1 on an exact repeat. */
+    readonly similarity: number;
+}
+
+/** Sorted members plus rounds — what 1A.4 calls the relevant configuration. */
+export function configFingerprint(members: readonly string[], rounds: number): string {
+    return `${[...members].sort().join(',')}|rounds=${String(rounds)}`;
+}
+
+/**
+ * Read the retained response artefacts into prior runs.
+ *
+ * Tolerant of every read failure by design: a malformed or half-written
+ * artefact must not break a council run. The guard is an advisory, and an
+ * advisory that can throw is worse than one that stays quiet.
+ */
+export function readPriorRuns(responsesDir: string, repoRoot: string): PriorRun[] {
+    let names: string[];
+    try {
+        names = fs.readdirSync(responsesDir).filter((f) => f.endsWith('.md'));
+    } catch {
+        return [];
+    }
+    const out: PriorRun[] = [];
+    for (const name of names) {
+        const abs = path.join(responsesDir, name);
+        let head: Record<string, unknown>;
+        let stat: fs.Stats;
+        try {
+            stat = fs.statSync(abs);
+            const text = fs.readFileSync(abs, 'utf8');
+            const json = _leadingJson(text);
+            // A file with no leading object is not a council artefact at all —
+            // skipped rather than admitted as a prior run with empty fields,
+            // which would put noise in a warning whose whole value is that it
+            // is rare enough to read.
+            if (json === null) continue;
+            head = JSON.parse(json) as Record<string, unknown>;
+        } catch {
+            continue;
+        }
+        const questionPath = typeof head['artefact'] === 'string' ? head['artefact'] : '';
+        const members = Array.isArray(head['members']) ? (head['members'] as string[]) : [];
+        const rounds = typeof head['rounds'] === 'number' ? head['rounds'] : 0;
+        let questionHash: string | null = null;
+        let questionText: string | null = null;
+        if (questionPath !== '') {
+            try {
+                const q = fs.readFileSync(path.join(repoRoot, questionPath), 'utf8');
+                questionHash = _sha256_hex(q);
+                questionText = q;
+            } catch {
+                // The question file was moved or pruned. The run is still a
+                // prior run; it simply cannot be compared by text, and saying
+                // that is better than dropping the record.
+            }
+        }
+        out.push({
+            artifactPath: abs,
+            questionPath,
+            ranAt: stat.mtime.toISOString().slice(0, 10),
+            configFingerprint: configFingerprint(members, rounds),
+            questionHash,
+            questionText,
+        });
+    }
+    return out;
+}
+
+/** The leading `{...}` object of an artefact, brace-balanced, or `null`. */
+function _leadingJson(text: string): string | null {
+    const start = text.indexOf('{');
+    if (start === -1) return null;
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < text.length; i++) {
+        const c = text[i] as string;
+        if (inStr) {
+            if (esc) esc = false;
+            else if (c === '\\') esc = true;
+            else if (c === '"') inStr = false;
+            continue;
+        }
+        if (c === '"') inStr = true;
+        else if (c === '{') depth += 1;
+        else if (c === '}') {
+            depth -= 1;
+            if (depth === 0) return text.slice(start, i + 1);
+        }
+    }
+    return null;
+}
+
+/**
+ * Is this question already deliberated?
+ *
+ * Returns the STRONGEST finding, or `null`. Exact beats near-duplicate, and a
+ * stale-config exact beats a near-duplicate: a caller shown two findings reads
+ * neither, and the exact one carries more information.
+ */
+export function checkRecouncil(
+    questionText: string,
+    currentConfig: string,
+    priors: readonly PriorRun[],
+    threshold: number = NEAR_DUPLICATE_THRESHOLD,
+): RecouncilVerdict | null {
+    const hash = _sha256_hex(questionText);
+
+    for (const p of priors) {
+        if (p.questionHash === hash) {
+            return {
+                state: p.configFingerprint === currentConfig ? 'exact-same-config' : 'exact-stale-config',
+                prior: p,
+                similarity: 1,
+            };
+        }
+    }
+    let best: RecouncilVerdict | null = null;
+    for (const p of priors) {
+        if (p.questionText === null) continue;
+        const s = jaccardSimilarity(questionText, p.questionText);
+        if (s >= threshold && (best === null || s > best.similarity)) {
+            best = { state: 'near-duplicate', prior: p, similarity: s };
+        }
+    }
+    return best;
+}
+
+/**
+ * The warning text.
+ *
+ * Every line step 1A.2 names is present — prior run date, prior artifact path,
+ * the fact that the question appears already deliberated, and the path to
+ * re-run — and 1A.3 requires the SCORE to be printed, so it is, on every state
+ * rather than only the near-duplicate one. A score of 1.00 on an exact repeat
+ * tells the reader which comparison fired.
+ */
+export function renderRecouncilWarning(v: RecouncilVerdict): string {
+    const what: Record<RepeatState, string> = {
+        'exact-same-config':
+            'this exact question has already been deliberated, and the configuration that would run it is unchanged',
+        'exact-stale-config':
+            'this exact question has already been deliberated, but the members or round count have moved since — the prior verdict may rest on evidence this configuration would not produce',
+        'near-duplicate':
+            'a question above the pre-registered similarity threshold has already been deliberated',
+    };
+    return [
+        `⚠️  council:re-council — ${what[v.state]}.`,
+        `    prior run    ${v.prior.ranAt}`,
+        `    prior answer ${v.prior.artifactPath}`,
+        `    question     ${v.prior.questionPath || '(not recorded)'}`,
+        `    similarity   ${v.similarity.toFixed(2)} (threshold ${String(NEAR_DUPLICATE_THRESHOLD)}, pre-registered)`,
+        '    This is a WARNING, never a refusal. Re-run with --confirm to deliberate again.',
+        '',
+    ].join('\n');
+}
+
+/**
+ * The whole call site, in one function.
+ *
+ * Lives here rather than in `council_cli.ts` for a reason the source-size
+ * ratchet made concrete: that file is already 2,525 lines over the 1,500-line
+ * ceiling, so every line added to it is a line the ratchet counts, and a
+ * twenty-line comment explaining a guard belongs beside the guard anyway.
+ *
+ * IT CANNOT REFUSE, and the signature is where that is guaranteed: it returns
+ * `void`. Step 1A.2 requires that no code path turn the warning into an
+ * unconditional block, and a function with nothing to return gives a caller
+ * nothing to branch on.
+ *
+ * Every read is wrapped: an advisory that throws is worse than one that stays
+ * quiet, because the guard exists to save a duplicate run and never to prevent
+ * a legitimate one.
+ *
+ * `questionFile` is the RAW question file, not the built prompt. Measured on
+ * the first live run: the built prompt hashes differently from the file the
+ * prior artefact recorded, so the exact-repeat states were unreachable in
+ * production and every true repeat reported as a near-duplicate at similarity
+ * 1.00. `fallbackText` covers a question that arrived on stdin and has no file.
+ */
+export function warnIfRecounciled(
+    repoRoot: string,
+    questionFile: string,
+    fallbackText: string,
+    members: readonly { name: string; model: string }[],
+    rounds: number,
+    write: (s: string) => void,
+): void {
+    try {
+        let text = fallbackText;
+        try {
+            text = fs.readFileSync(path.resolve(repoRoot, questionFile), 'utf8');
+        } catch {
+            // No file behind this question; the built prompt is the best text
+            // available, and a near-duplicate finding is still useful.
+        }
+        const v = checkRecouncil(
+            text,
+            // `name/model` — the SAME shape the artefact writer records.
+            configFingerprint(members.map((m) => `${m.name}/${m.model}`), rounds),
+            readPriorRuns(path.join(repoRoot, 'agents/runtime/council/responses'), repoRoot),
+        );
+        if (v !== null) write(renderRecouncilWarning(v));
+    } catch {
+        // See the docstring: quiet beats loud-and-broken for an advisory.
+    }
+}

package/src/scripts/ai_council/response_record.ts

@@ -0,0 +1,50 @@
+/**
+ * How a `CouncilResponse` is shaped for the persisted session record.
+ *
+ * Extracted from `council_cli.ts` on 2026-08-30. It belongs here on its own
+ * merits — it is a pure data-shaping function over a type this directory owns,
+ * with no CLI concern in it — and it pays for the lines the same change spent
+ * in files that are thousands past `check_source_size_budget`'s ceiling. That
+ * gate's own convention is that the total falls through extraction and never
+ * rises through a baseline edit.
+ *
+ * `metadata` values are stringified deliberately, and two consumers depend on
+ * it: `ai_council/pricing.ts` coerces them back, and `billable_cost.test.ts`
+ * pins the behavior.
+ *
+ * Side-effect-free, no CLI entry, no `process.exit`.
+ */
+import type { CouncilResponse } from './clients.js';
+
+type Dict = Record<string, unknown>;
+
+export function serializeResponses(responses: CouncilResponse[]): Dict[] {
+    const out: Dict[] = [];
+    for (const r of responses) {
+        const metadata: Dict = {};
+        for (const [k, v] of Object.entries(r.metadata || {})) {
+            metadata[k] = String(v);
+        }
+        out.push({
+            provider: r.provider,
+            model: r.model,
+            text: r.text,
+            // Present ONLY when something rewrote `text` in place — today that
+            // is the inline-findings harvest, whose emitted marker promises
+            // exactly this retention. Omitted otherwise rather than written as
+            // a copy of `text`, so an unmodified reply does not carry a
+            // duplicate of itself into every session record. The full account
+            // of why the field exists is at its single write site in
+            // `inline_findings.ts`.
+            ...(r.raw_text === null ? {} : { raw_text: r.raw_text }),
+            input_tokens: r.input_tokens,
+            output_tokens: r.output_tokens,
+            cache_creation_input_tokens: r.cache_creation_input_tokens,
+            cache_read_input_tokens: r.cache_read_input_tokens,
+            latency_ms: r.latency_ms,
+            error: r.error,
+            metadata,
+        });
+    }
+    return out;
+}