@event4u/agent-config 16.5.0 → 17.1.0

package/src/scripts/ai_council/modification_review.ts

@@ -24,6 +24,12 @@
  */
 
 import { parse_stance_line } from './stance_tally.js';
+import {
+    SEAT_NO_FINAL_VERDICT,
+    deriveRatificationHeader,
+    type RatificationVerdict,
+    type SeatVerdict,
+} from '../_lib/ratification_artifact.js';
 
 /**
  * The closed vocabulary a seat may close on. Open it and a grep for a passing
@@ -66,7 +72,9 @@ export function seatConclusion(text: string): ModificationVerdictLabel | null {
 export function readSeatConclusions(
     replies: Readonly<Record<string, string>>,
 ): Record<string, ModificationVerdictLabel | null> {
-    const out: Record<string, ModificationVerdictLabel | null> = {};
+    // Prototype-free: on a plain object, assigning a seat named `__proto__`
+    // replaces the prototype and the seat silently disappears.
+    const out = Object.create(null) as Record<string, ModificationVerdictLabel | null>;
     for (const [seat, text] of Object.entries(replies)) {
         out[seat] = seatConclusion(text);
     }
@@ -74,7 +82,54 @@ export function readSeatConclusions(
 }
 
 /**
- * Derive the record's verdict. ONE rule, and the ORDER is the rule:
+ * A threshold that is not a positive integer is refused, never coerced. At zero
+ * or below, an empty council would satisfy it; a fraction or a non-finite value
+ * has no count of providers it could mean.
+ */
+function assertRequiredProviders(requiredProviders: number): void {
+    if (!Number.isInteger(requiredProviders) || requiredProviders < 1) {
+        throw new RangeError(
+            `requiredProviders must be a positive integer, got ${String(requiredProviders)}`,
+        );
+    }
+}
+
+/**
+ * Every seat value is checked at run time, because the declared type is erased
+ * and a seat map often arrives as parsed JSON. A value outside the closed
+ * vocabulary or `null` throws: counted, it would add a provider to the quorum
+ * and could fall through to acceptance.
+ */
+function concludedSeats(
+    seats: Readonly<Record<string, ModificationVerdictLabel | null>>,
+): [string, ModificationVerdictLabel][] {
+    const out: [string, ModificationVerdictLabel][] = [];
+    for (const [seat, value] of Object.entries(seats) as [string, unknown][]) {
+        if (value === null) continue;
+        if (
+            typeof value !== 'string' ||
+            !(MODIFICATION_VERDICT_LABELS as readonly string[]).includes(value)
+        ) {
+            throw new TypeError(
+                `seat ${JSON.stringify(seat)} carries ${JSON.stringify(value)}, not a modification verdict label or null`,
+            );
+        }
+        out.push([seat, value as ModificationVerdictLabel]);
+    }
+    return out;
+}
+
+/**
+ * Derive the review's DISPOSITION rule — what the run does next. It is not the
+ * artifact's `verdict` field: for one seat `ratified` and another without a
+ * final verdict this returns `non-convergent`, while the reader's
+ * `deriveRatificationHeader` returns `ratified` with one provider, and the
+ * reader refuses a record carrying this answer as `header-not-derived`.
+ * {@link deriveModificationOutcome} returns both answers under different names;
+ * this function stays exported, so that is a clearer interface, not an enforced
+ * one.
+ *
+ * ONE rule, and the ORDER is the rule:
  *
  *   1. any concluding seat on `refused`  → `refused`
  *   2. concluding providers < required   → `non-convergent`
@@ -90,11 +145,49 @@ export function deriveModificationVerdict(
     seats: Readonly<Record<string, ModificationVerdictLabel | null>>,
     requiredProviders: number,
 ): ModificationVerdict {
-    const concluded = Object.values(seats).filter(
-        (v): v is ModificationVerdictLabel => v !== null,
-    );
+    assertRequiredProviders(requiredProviders);
+    const concluded = concludedSeats(seats).map(([, v]) => v);
     if (concluded.includes('refused')) return 'refused';
     if (concluded.length < requiredProviders) return 'non-convergent';
     if (concluded.includes('ratified')) return 'ratified';
     return 'confirmed-non-expanding';
 }
+
+/**
+ * What a run does next. Never written into the artifact. A refusal and a short
+ * quorum stay apart because only the second is cured by asking again.
+ */
+export type ModificationDisposition = 'accepted' | 'refused' | 'quorum-short';
+
+export interface ModificationOutcome {
+    /** The header the record carries, from the one canonical derivation. */
+    header: { providers: string[]; verdict: RatificationVerdict };
+    /** Whether enough distinct providers concluded. */
+    quorumSatisfied: boolean;
+    disposition: ModificationDisposition;
+}
+
+/**
+ * The record's header and the run's disposition from one call, under different
+ * names. Throws a `RangeError` when `requiredProviders` is not a positive
+ * integer and a `TypeError` when a seat carries a value outside the vocabulary.
+ */
+export function deriveModificationOutcome(
+    seats: Readonly<Record<string, ModificationVerdictLabel | null>>,
+    requiredProviders: number,
+): ModificationOutcome {
+    assertRequiredProviders(requiredProviders);
+    const concluded = new Map(concludedSeats(seats));
+    const asSeatVerdicts = new Map<string, SeatVerdict>();
+    for (const seat of Object.keys(seats)) {
+        asSeatVerdicts.set(seat, concluded.get(seat) ?? SEAT_NO_FINAL_VERDICT);
+    }
+    const header = deriveRatificationHeader(asSeatVerdicts);
+    const quorumSatisfied = new Set(header.providers).size >= requiredProviders;
+    const verdict = deriveModificationVerdict(seats, requiredProviders);
+    let disposition: ModificationDisposition;
+    if (verdict === 'refused') disposition = 'refused';
+    else if (!quorumSatisfied || verdict === 'non-convergent') disposition = 'quorum-short';
+    else disposition = 'accepted';
+    return { header, quorumSatisfied, disposition };
+}

package/src/scripts/ai_council/necessity.ts

@@ -235,6 +235,7 @@ export function classify_necessity(
     prompt: string,
     lens = 'analysis',
     _invocation: Invocation = 'agent',
+    opts: { readonly ratePressure?: boolean } = {},
 ): ClassificationResult {
     const text = _pyStrip(prompt || '');
     if (!text) {
@@ -299,6 +300,12 @@ export function classify_necessity(
         rationale =
             `Lens \`${lens}\` is strict (expensive deliberation); ` +
             `borderline with zero \`necessary\` markers → unnecessary.`;
+    } else if (opts.ratePressure === true && verdict === 'borderline' && n_hits === 0) {
+        // Inside a host rate window every lens applies the strict bar.
+        verdict = 'unnecessary';
+        rationale =
+            'A recent host rate marker applies the strict bar; ' +
+            `borderline with zero \`necessary\` markers → unnecessary.`;
     }
 
     return new ClassificationResult({

package/src/scripts/ai_council/orchestrator.ts

@@ -30,12 +30,11 @@ export type { RunConsensusScoringOptions, RunPeerReviewOptions } from './orchest
 // existing importer of `run_consensus_scoring` is untouched.
 export { run_consensus_scoring } from './consensus_round.js';
 import {
-    record_spend as _record_daily_spend,
     today_spend_usd as _today_spend_usd,
     would_exceed as _would_exceed_daily,
 } from './budget_guard.js';
 import type {
-    ExternalAIClient} from './clients.js';
+    CliClient, ExternalAIClient} from './clients.js';
 import {
     DEFAULT_MAX_TOKENS,
     CouncilResponse
@@ -99,10 +98,12 @@ import {
     CostBudget,
     OverrunEvent,
     _breach,
+    breachErrorTag,
     _total_usd,
     type Spent,
 } from './spend_gate.js';
 import { callMember, renderResponseMeta } from './response_render.js';
+import { RoundReservations } from './round_reservations.js';
 import {
     _excTag,
     _metaGet,
@@ -498,16 +499,16 @@ export function consult(
             // health and structural validity are INDEPENDENT failure modes,
             // so refusing the retry would discard salvageable work for an
             // unrelated reason. Bounded by the retry's own spend gate.
-            const rr = _run_round([member], repairQ, resolvedBudget, spent, {
-                table,
-                on_overrun,
-                project,
-                original_ask,
-                advisor_plans,
-                cli_fallback,
-                fallback_ledger,
-                fallback_twins,
-            });
+            // Non-blind: the seat is asked about its own reply, so it continues the session that wrote it.
+            const seat = member as Partial<Pick<CliClient, 'lastSession' | 'resumeNext'>>;
+            if (seat.lastSession !== undefined) seat.resumeNext = seat.lastSession;
+            let rr: CouncilResponse[];
+            try {
+                const round = { table, on_overrun, project, original_ask, advisor_plans, cli_fallback, fallback_ledger, fallback_twins };
+                rr = _run_round([member], repairQ, resolvedBudget, spent, round);
+            } finally {
+                if (seat.resumeNext !== undefined) seat.resumeNext = null; // a quota gate or refusal returns before the seat clears it
+            }
             const rep = rr[0];
             if (rep !== undefined) {
                 opts.on_stance_repair_result?.(rep);
@@ -589,6 +590,7 @@ function _run_round(
     };
 
     const results: CouncilResponse[] = [];
+    const reservations = new RoundReservations(budget);
     const estimates: CostEstimate[] | null =
         table !== null
             ? estimate(question, members, table, {
@@ -661,13 +663,10 @@ function _run_round(
                 : estimates
                   ? (estimates[idx] as CostEstimate)
                   : null;
-        const breach = _breach(est, spent, budget);
+        const breach = _breach(est, spent, budget) ?? reservations.reserve(est, member);
         if (breach !== null) {
             const breach_kind = breach;
-            const error_tag =
-                breach_kind === 'daily'
-                    ? 'daily_budget_exceeded'
-                    : 'cost_budget_exceeded';
+            const error_tag = breachErrorTag(breach_kind);
             // A seat that arrived here by escalating from an UNMETERED cli
             // call degrades to its own original failure — never to an abort,
             // and never to the round-wide short-circuit below. The reasoning,
@@ -717,7 +716,7 @@ function _run_round(
                 for (const left of members.slice(idx)) {
                     results.push(_aborted(left, error_tag));
                 }
-                return results;
+                return reservations.finish(results);
             }
         }
 
@@ -804,18 +803,13 @@ function _run_round(
             spent.usd += _total_usd(actual);
             // Ledger every billable response, bounded or not (ADR-279): a cap
             // decides whether the total is compared, never whether it is kept.
-            if (!response.error) {
-                _record_daily_spend(_total_usd(actual), effective.name, effective.model, {
-                    cache_read_input_tokens: response.cache_read_input_tokens,
-                    cache_creation_input_tokens: response.cache_creation_input_tokens,
-                    cache_ttl: '5m',
-                });
-            }
+            // With a daily ceiling set the seat's reservation is reconciled instead.
+            reservations.settle(response, effective, actual);
         }
         _stamp_transport_metadata(response, effective, actual_usd);
     }
 
-    return results;
+    return reservations.finish(results);
 }
 
 function _aborted(member: ExternalAIClient, reason: string): CouncilResponse {
@@ -855,6 +849,9 @@ function _stamp_transport_metadata(
     if (cost_usd !== null) {
         meta['cost_usd'] = Number(cost_usd);
     }
+    // A size-fit downgrade (`council_cli._size_fit_gate`) leaves the configured
+    // model and the reason on the member; they ride into the response here.
+    Object.assign(meta, _getattr(member, 'size_fit', null));
     response.metadata = meta;
 }
 

package/src/scripts/ai_council/pricing.ts

@@ -116,6 +116,12 @@ export interface CostEstimate {
     output_tokens: number;
     input_usd: number;
     output_usd: number;
+    /**
+     * False when `lookup` found no row. The two amounts are then zero so
+     * arithmetic callers keep working, but zero is not the price: a ceiling
+     * that compared against it would let an unknown model through as free.
+     */
+    priced: boolean;
 }
 
 export function estimate_cost(
@@ -134,6 +140,7 @@ export function estimate_cost(
             output_tokens: maxOutputTokens,
             input_usd: 0.0,
             output_usd: 0.0,
+            priced: false,
         };
     }
     const inputUsd = (inputTokens / 1_000_000) * price.input_per_1m_usd;
@@ -145,6 +152,7 @@ export function estimate_cost(
         output_tokens: maxOutputTokens,
         input_usd: inputUsd,
         output_usd: outputUsd,
+        priced: true,
     };
 }
 
@@ -357,6 +365,7 @@ export function reprice_with_cache(
             output_tokens: tokens.output_tokens,
             input_usd: 0.0,
             output_usd: 0.0,
+            priced: false,
         };
     }
     const writeMult = ttl === '1h' ? CACHE_WRITE_MULTIPLIER_1H : CACHE_WRITE_MULTIPLIER_5M;
@@ -372,6 +381,7 @@ export function reprice_with_cache(
         output_tokens: tokens.output_tokens,
         input_usd: inputUsd,
         output_usd: outputUsd,
+        priced: true,
     };
 }
 

package/src/scripts/ai_council/redact_low_impact_entry.ts

@@ -43,6 +43,7 @@
  * module guarantees its callers.
  */
 
+import { API_KEY_ASSIGNMENT_KEYWORD } from '../_lib/egress_prefixes.js';
 import { _RAW_KEY_PREFIXES } from './config.js';
 
 /**
@@ -189,9 +190,11 @@ const _MONEY_RE = new RegExp(
     'gu',
 );
 
-// Python: (?i)\bapi[_-]?key\b\s*[:=]\s*[A-Za-z0-9+/=_\-]{12,}
+// The keyword is the rule table's, read through its bundled projection (this
+// module rides in the dispatch bundle); the Unicode word boundary and the
+// 12-character value are this redactor's threshold.
 const _API_KEY_RE = new RegExp(
-    `${_UNB_BEFORE}api[_-]?key${_UNB_AFTER}\\s*[:=]\\s*[A-Za-z0-9+/=_\\-]{12,}`,
+    `${_UNB_BEFORE}${API_KEY_ASSIGNMENT_KEYWORD}${_UNB_AFTER}\\s*[:=]\\s*[A-Za-z0-9+/=_\\-]{12,}`,
     'giu',
 );
 

package/src/scripts/ai_council/response_render.ts

@@ -9,6 +9,7 @@
  */
 
 import { CouncilResponse, type ExternalAIClient } from './clients.js';
+import { councilEgress } from './council_egress.js';
 import { _metaGet } from './py_parity.js';
 
 /**
@@ -62,14 +63,25 @@ export function renderResponseMeta(r: CouncilResponse, deps: MetaRenderDeps): st
                 : `transport: api (fell back from ${fallback_from}${why})`,
         );
     }
+    // Same reasoning for a size-fit downgrade: the model that answered is not
+    // the one configured, and only the artefact outlives the stdout line.
+    const configured = _metaGet(meta_dict, 'configured_model', null);
+    if (typeof configured === 'string' && configured !== '' && configured !== r.model) {
+        const reason = _metaGet(meta_dict, 'size_fit_reason', null);
+        const why = typeof reason === 'string' && reason !== '' ? `: ${reason}` : '';
+        parts.push(`model: ${r.model} (downgraded from ${configured}${why})`);
+    }
     return `*${parts.join(' · ')}*`;
 }
 
 
-/** Error-tagged member call — the split/ask branch is one shape, not three. */
 /**
  * One member call, error-tagged rather than throwing — the split/ask branch
- * appeared three times before this and is one shape, not three.
+ * appeared three times before this and is one shape, not three. It is also the
+ * council channel's final egress check: immediately before the request is
+ * written, the whole body is rescanned for every value this run replaced and
+ * every high-confidence finding, and a hit refuses the send — the member is
+ * never called and the response carries only the reason.
  */
 export function callMember(
     client: ExternalAIClient,
@@ -79,14 +91,25 @@ export function callMember(
     excTag: (e: unknown) => string,
 ): CouncilResponse {
     try {
+        const system = systemFor(client);
+        const body = opts.split ? `${system}\n${opts.split.stable}${opts.split.suffix}` : `${system}\n${question.user_prompt}`;
+        const refusal = councilEgress().check(body);
+        if (refusal !== null) {
+            return new CouncilResponse({
+                provider: client.name,
+                model: client.model,
+                text: '',
+                error: `egress refused: ${refusal.reason} (${refusal.what}); nothing was sent`,
+            });
+        }
         return opts.split
             ? client.ask_split(
-                  systemFor(client),
+                  system,
                   opts.split.stable,
                   opts.split.suffix,
                   question.max_tokens,
               )
-            : client.ask(systemFor(client), question.user_prompt, question.max_tokens);
+            : client.ask(system, question.user_prompt, question.max_tokens);
     } catch (exc) {
         return new CouncilResponse({
             provider: client.name,

package/src/scripts/ai_council/round_reservations.ts

@@ -0,0 +1,119 @@
+/**
+ * round_reservations — reserve-then-reconcile for one council round
+ * (road-to-unknowns-that-say-so Phase 3).
+ *
+ * Extracted rather than written into `orchestrator.ts`, which sits over the
+ * source-size ceiling; the orchestrator calls three methods and nothing else.
+ *
+ * Inert unless a daily ceiling is set: `reserve` returns `null` without
+ * touching the ledger, and `settle` records exactly what the orchestrator
+ * recorded before this existed, so with every ceiling at zero the ledger is
+ * byte-identical (ADR-279).
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import {
+    close_reservation,
+    record_spend,
+    reserve_spend,
+} from './budget_guard.js';
+import { DEFAULT_CLI_TIMEOUT_SECONDS, type CouncilResponse, type ExternalAIClient } from './clients.js';
+import { type CostEstimate } from './pricing.js';
+import { _total_usd, type CostBudget } from './spend_gate.js';
+
+/** One hour past the call's own timeout (D8). */
+const HOLD_PAST_TIMEOUT_MS = 3_600_000;
+
+/**
+ * An error whose outcome nobody knows: the provider may have generated and
+ * billed before the connection died. Anything else that fails with no tokens
+ * failed before the provider accepted the request — auth, a missing key, a
+ * refused connection — and releases its reservation. `parse_failed` is an
+ * answer that arrived unreadable, so it was billed. A 5xx counts only where it
+ * is named as a status, so `line 500` or `500 ms` in a message is not one.
+ */
+const UNKNOWN_OUTCOME =
+    /time[sd]?\s*out|timeout|deadline exceeded|ETIMEDOUT|ECONNRESET|socket hang up|server[_ ]error|overloaded|parse_failed|(?:\bHTTP\s*|\bstatus(?:\s+code)?\s*:?\s*|\bexit_|\berror\s+)5\d\d\b/iu;
+
+export function outcomeIsUnknown(error: string): boolean {
+    return UNKNOWN_OUTCOME.test(error);
+}
+
+export class RoundReservations {
+    readonly run_id = randomUUID();
+    private current: string | null = null;
+    private readonly unknown: string[] = [];
+
+    constructor(
+        private readonly budget: CostBudget,
+        private readonly ledgerPath: string | null = null,
+    ) {}
+
+    /**
+     * Claim the seat's estimate under the ledger lock. Returns `'daily'` when
+     * the ceiling cannot hold it (or the lock cannot be taken — an unchecked
+     * ceiling is not that ceiling), `null` when the call may go ahead.
+     */
+    reserve(est: CostEstimate | null, member: ExternalAIClient): 'daily' | null {
+        this.current = null;
+        if (this.budget.daily_limit_usd <= 0 || est === null || !est.priced) {
+            return null;
+        }
+        const timeout = (member as { timeout_seconds?: number }).timeout_seconds ?? DEFAULT_CLI_TIMEOUT_SECONDS;
+        const res = reserve_spend(this.budget.daily_limit_usd, _total_usd(est), member.name, member.model, {
+            path: this.ledgerPath,
+            run_id: this.run_id,
+            hold_ms: timeout * 1000 + HOLD_PAST_TIMEOUT_MS,
+        });
+        if (!res.ok) return 'daily';
+        this.current = res.id;
+        return null;
+    }
+
+    /**
+     * Reconcile the seat's call. Without a reservation this is the ledger write
+     * the orchestrator always made. With one: `completed` at the actual amount
+     * when tokens came back or no error was raised; `released` when it failed
+     * before the provider accepted it; an unknown outcome waits for `finish`.
+     */
+    settle(response: CouncilResponse, effective: ExternalAIClient, actual: CostEstimate): void {
+        const id = this.current;
+        this.current = null;
+        if (id === null) {
+            if (!response.error) {
+                record_spend(_total_usd(actual), effective.name, effective.model, {
+                    path: this.ledgerPath,
+                    cache_read_input_tokens: response.cache_read_input_tokens,
+                    cache_creation_input_tokens: response.cache_creation_input_tokens,
+                    cache_ttl: '5m',
+                    ...(actual.priced ? {} : { unpriced: true, input_tokens: actual.input_tokens, output_tokens: actual.output_tokens }),
+                });
+            }
+            return;
+        }
+        const tokens = response.input_tokens + response.output_tokens;
+        if (!response.error || tokens > 0) {
+            close_reservation(id, 'completed', {
+                path: this.ledgerPath,
+                usd: _total_usd(actual),
+                provider: effective.name,
+                model: effective.model,
+            });
+        } else if (outcomeIsUnknown(String(response.error))) {
+            this.unknown.push(id);
+        } else {
+            close_reservation(id, 'released', { path: this.ledgerPath });
+        }
+    }
+
+    /** Run end: every reservation still waiting on an outcome closes at its estimate, never zero. */
+    finish<T>(passthrough: T): T {
+        if (this.current !== null) this.unknown.push(this.current);
+        this.current = null;
+        for (const id of this.unknown.splice(0)) {
+            close_reservation(id, 'unreconciled', { path: this.ledgerPath });
+        }
+        return passthrough;
+    }
+}