@event4u/agent-config 14.8.0 → 14.9.0

package/src/scripts/ai_council/fallback_config.ts

@@ -10,6 +10,8 @@
  * here; the rest is there rather than duplicated.
  */
 
+import type { ApiOnQuota } from './transport_resolver.js';
+
 /**
  * `fallback.*` — the mid-flight cli→api retry's one configurable knob.
  *
@@ -24,8 +26,13 @@ export interface FallbackConfig {
      * May an exhausted CLI quota retry on the metered api rung? Default
      * `false`. The no-double-charge classes are always eligible and never
      * consult this; `timeout` / 5xx are never eligible under any value.
+     *
+     * Three values, not two. `'ask'` defers the answer out of configuration
+     * time and into the round that would cross the cliff: the seat is PARKED
+     * unless a run-scoped billing grant says a human already agreed for this
+     * run. See `transport_resolver.ts` § `ApiOnQuota` and `_lib/billing_grant`.
      */
-    readonly api_on_quota: boolean;
+    readonly api_on_quota: ApiOnQuota;
 }
 
 /**
@@ -67,12 +74,17 @@ export function buildFallback(raw: unknown, d: FallbackBuilderDeps): FallbackCon
     if (!d.isDict(raw)) return { api_on_quota: false };
     const v = raw['api_on_quota'];
     if (v === undefined) return { api_on_quota: false };
-    if (!d.isBool(v)) {
-        throw d.error(
-            `\`fallback.api_on_quota\`=${d.repr(v)} must be a boolean (got ${d.typeName(v)}).`,
-        );
-    }
-    return { api_on_quota: v };
+    if (d.isBool(v)) return { api_on_quota: v };
+    // `'ask'` is the ONLY string this accepts, and the narrowness is the
+    // point: the paragraph above refuses `"yes"` because an operator writing
+    // it is trying to authorise spend, and widening to "any truthy-looking
+    // string" to let `ask` through would readmit exactly that. A third named
+    // value is not a lenient parse.
+    if (d.isStr(v) && v === 'ask') return { api_on_quota: 'ask' };
+    throw d.error(
+        `\`fallback.api_on_quota\`=${d.repr(v)} must be \`false\`, \`true\` or \`'ask'\` ` +
+            `(got ${d.typeName(v)}).`,
+    );
 }
 
 /**

package/src/scripts/ai_council/mid_flight_fallback.ts

@@ -19,19 +19,28 @@
 import type { ExternalAIClient, CouncilResponse } from './clients.js';
 import {
     classifyCliFailure,
+    effectiveApiOnQuota,
     isFallbackEligibleUnder,
+    type ApiOnQuota,
     type FallbackPolicy,
     type MidFlightFallback,
 } from './transport_resolver.js';
 
-/** One escalation's outcome, for the event sink. */
-export type FallbackOutcome = 'retried' | 'no_twin' | 'cost_budget';
+/**
+ * One escalation's outcome, for the event sink.
+ *
+ * `awaiting_grant` is the posture `'ask'` adds and it is neither of the two
+ * that existed: the seat was NOT switched to metered billing and it was NOT
+ * lost. It is held, and the round closes with a question instead of a silent
+ * charge or a silent absence.
+ */
+export type FallbackOutcome = 'retried' | 'no_twin' | 'cost_budget' | 'awaiting_grant';
 
 export interface FallbackEvent {
     readonly provider: string;
     readonly failure: string;
     readonly outcome: FallbackOutcome;
-    readonly api_on_quota: boolean;
+    readonly api_on_quota: ApiOnQuota;
 }
 
 export interface CliFallbackOptions {
@@ -42,7 +51,21 @@ export interface CliFallbackOptions {
      */
     readonly construct: (provider: string) => ExternalAIClient | null;
     /** `ai_council.fallback.api_on_quota` — see `FallbackPolicy.apiOnQuota`. */
-    readonly api_on_quota: boolean;
+    readonly api_on_quota: ApiOnQuota;
+    /**
+     * True when a run-scoped billing grant is in force for THIS run. Read only
+     * under `api_on_quota: 'ask'`; absence means park, never proceed.
+     */
+    readonly billing_grant?: boolean;
+    /**
+     * Providers parked under `'ask'`, appended during the round.
+     *
+     * It lives on the options object rather than in the CLI because the CLI
+     * has nothing to do with it: the factory that decides a seat is parked is
+     * the only thing that can populate it, and a caller threading an array
+     * down to that factory and back is plumbing with no reader in between.
+     */
+    readonly parked?: string[];
     /**
      * Called once per ESTABLISHING escalation, never per substituted call.
      *
@@ -60,6 +83,42 @@ export interface EstablishedTwin {
     readonly original_error: string;
 }
 
+/**
+ * A seat held back because the policy is `'ask'` and no grant is in force.
+ *
+ * The third state the boolean could not express. Before `'ask'` existed a
+ * quota-hit seat had exactly two futures — a twin (metered, silent) or `null`
+ * (lost for the round). Neither is answerable afterwards: by the time a human
+ * reads the output, the spend has happened or the seat is gone. A parked seat
+ * is still in the round's seat map, so the question the round closes with is
+ * about work that can still be done.
+ */
+export interface ParkedSeat {
+    readonly parked: true;
+    readonly provider: string;
+    readonly reason: string;
+    readonly original_error: string;
+}
+
+/** `establishTwin`'s three outcomes: a twin, a parked seat, or nothing. */
+export type EstablishOutcome = EstablishedTwin | ParkedSeat | null;
+
+/**
+ * Narrow an `EstablishOutcome` to the twin branch.
+ *
+ * Every caller must use this rather than a truthiness test: a `ParkedSeat` is
+ * an object, so `if (twin)` retries the parked marker as though it were a
+ * client — the one bug the park branch exists to make impossible.
+ */
+export function isEstablishedTwin(o: EstablishOutcome): o is EstablishedTwin {
+    return o !== null && !('parked' in o);
+}
+
+/** Narrow an `EstablishOutcome` to the parked branch. */
+export function isParkedSeat(o: EstablishOutcome): o is ParkedSeat {
+    return o !== null && 'parked' in o;
+}
+
 /**
  * Why the twin map exists alongside the ledger.
  *
@@ -99,10 +158,32 @@ export interface EstablishInput {
  * budget then refused. An ineligible class emits nothing at all: there was no
  * escalation to report.
  */
-export function establishTwin(input: EstablishInput): EstablishedTwin | null {
+export function establishTwin(input: EstablishInput): EstablishOutcome {
     const { member, error, fallback, ledger } = input;
     const failure = classifyCliFailure(error);
-    const policy: FallbackPolicy = { apiOnQuota: fallback.api_on_quota };
+    const policy: FallbackPolicy = {
+        apiOnQuota: fallback.api_on_quota,
+        billingGrant: fallback.billing_grant === true,
+    };
+    // The park branch runs BEFORE the eligibility test, and the order is the
+    // whole mechanism. `effectiveApiOnQuota` collapses an ungranted `'ask'`
+    // to `false`, so an eligibility-first reading would return `null` here —
+    // the seat lost, exactly as under `api_on_quota: false`, and the operator
+    // never asked. The ledger is deliberately NOT consulted: parking spends no
+    // fallback attempt, so the seat is still escalatable on the grant.
+    if (
+        fallback.api_on_quota === 'ask' &&
+        failure === 'quota_exhausted' &&
+        !effectiveApiOnQuota(policy)
+    ) {
+        fallback.on_event?.({
+            provider: member.name,
+            failure,
+            outcome: 'awaiting_grant',
+            api_on_quota: fallback.api_on_quota,
+        });
+        return { parked: true, provider: member.name, reason: failure, original_error: error };
+    }
     if (!isFallbackEligibleUnder(failure, policy)) return null;
     if (ledger.attempt(member.name, failure, policy) !== 'api') return null;
 
@@ -241,7 +322,7 @@ export function escalateUnmetered(
         fallback,
         ledger,
     });
-    if (twin === null) return null;
+    if (!isEstablishedTwin(twin)) return null;
     // NOTHING is emitted here, and the previous comment justifying an emit at
     // establishment is deleted rather than reworded because it stopped being
     // true. It read: "on this path the twin goes through the round's ORDINARY

package/src/scripts/ai_council/orchestrator.ts

@@ -75,7 +75,7 @@ import {
     emitOutcome,
     escalateUnmetered,
     refuseUnmeteredEscalation,
-    establishTwin,
+    establishTwin, isEstablishedTwin,
     isFailedCliCall,
     runGatedRetry,
     stampFallback,
@@ -764,7 +764,7 @@ function _run_round(
                 fallback,
                 ledger,
             });
-            if (twin !== null) {
+            if (isEstablishedTwin(twin)) {
                 const out = runGatedRetry(response, member, twin, fallback, {
                     gate: (client) =>
                         table === null ||

package/src/scripts/ai_council/py_format.ts

@@ -0,0 +1,124 @@
+/**
+ * Python-format helpers, extracted from `config.ts`.
+ *
+ * Every error string this package emits is byte-faithful to the Python original
+ * it replaced, which is why `repr()`, `type().__name__` and `oct()` are
+ * reimplemented here instead of being approximated with template literals.
+ *
+ * Pure and self-contained: these functions call only each other, which is what
+ * made the section safe to move out whole. Extracted because config.ts is
+ * hundreds of lines above the 1500-line source ceiling and a change adding to it
+ * has to pay for the lines somewhere.
+ */
+/** Python `repr()` for a string scalar (single-quoted, escaped). */
+export function _pyReprStr(s: string): string {
+    const hasSingle = s.includes("'");
+    const hasDouble = s.includes('"');
+    const quote = hasSingle && !hasDouble ? '"' : "'";
+    let body = s
+        .replace(/\\/g, '\\\\')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+    if (quote === "'") {
+        body = body.replace(/'/g, "\\'");
+    } else {
+        body = body.replace(/"/g, '\\"');
+    }
+    return `${quote}${body}${quote}`;
+}
+
+/** Python `repr()` for a float value (shortest round-trip, `N.0` for ints). */
+export function _pyReprFloat(value: number): string {
+    if (Number.isInteger(value) && Number.isFinite(value)) {
+        return `${value}.0`;
+    }
+    if (value === Infinity) {
+        return 'inf';
+    }
+    if (value === -Infinity) {
+        return '-inf';
+    }
+    if (Number.isNaN(value)) {
+        return 'nan';
+    }
+    return String(value);
+}
+
+/**
+ * Python `repr()` for an arbitrary parsed value. Floats are tracked via
+ * `_FLOAT` so int-valued floats render `N.0`; bare numbers render as
+ * Python ints (no decimal). Mirrors `{value!r}` formatting.
+ */
+export function _pyRepr(value: unknown): string {
+    if (value instanceof _Float) {
+        return _pyReprFloat(value.value);
+    }
+    if (value === null || value === undefined) {
+        return 'None';
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'True' : 'False';
+    }
+    if (typeof value === 'string') {
+        return _pyReprStr(value);
+    }
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => _pyRepr(v)).join(', ')}]`;
+    }
+    if (typeof value === 'object') {
+        const parts: string[] = [];
+        for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+            parts.push(`${_pyReprStr(k)}: ${_pyRepr(v)}`);
+        }
+        return `{${parts.join(', ')}}`;
+    }
+    return String(value);
+}
+
+/** Wrapper marking a number that should `repr()` as a Python float. */
+export class _Float {
+    constructor(readonly value: number) {}
+}
+
+/** Mark `n` so `_pyRepr` renders it with a Python float repr (`N.0`). */
+export function _f(n: number): _Float {
+    return new _Float(n);
+}
+
+/** Python `type(value).__name__`. */
+export function _pyTypeName(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'NoneType';
+    }
+    if (typeof value === 'boolean') {
+        return 'bool';
+    }
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'int' : 'float';
+    }
+    if (typeof value === 'string') {
+        return 'str';
+    }
+    if (Array.isArray(value)) {
+        return 'list';
+    }
+    if (typeof value === 'object') {
+        return 'dict';
+    }
+    return typeof value;
+}
+
+/** Python `sorted(set_of_strings)` rendered as a list repr `['a', 'b']`. */
+export function _sortedListRepr(items: Iterable<string>): string {
+    const sorted = [...items].sort();
+    return `[${sorted.map((s) => _pyReprStr(s)).join(', ')}]`;
+}
+
+/** Python `oct(mode)` → `0o600`-shaped string. */
+export function _pyOct(mode: number): string {
+    return `0o${mode.toString(8)}`;
+}

package/src/scripts/ai_council/transport_resolver.ts

@@ -403,13 +403,76 @@ const FALLBACK_ELIGIBLE: ReadonlySet<CliFailureClass> = new Set([
  * `auto` may infer — the USD spend itself remains guarded by the ordinary
  * `cost_budget` gates the orchestrator runs on the retry.
  */
+/**
+ * The three postures of `ai_council.fallback.api_on_quota`.
+ *
+ * `false` and `true` mean what they always meant. `'ask'` is the third: the
+ * billing-class decision is deferred out of configuration time and into the
+ * round that would actually cross the cliff, where the remaining scope is
+ * known. Under `'ask'` the seat is eligible only when a run-scoped billing
+ * grant is present — a human said yes for THIS run — and is parked otherwise.
+ */
+export type ApiOnQuota = boolean | 'ask';
+
 export interface FallbackPolicy {
-    readonly apiOnQuota: boolean;
+    readonly apiOnQuota: ApiOnQuota;
+    /**
+     * True when a run-scoped billing grant is in force. Only consulted under
+     * `apiOnQuota: 'ask'`; absent is never read as granted, which is why this
+     * is optional rather than defaulted anywhere.
+     */
+    readonly billingGrant?: boolean;
 }
 
 /** The base policy: exactly the three-plus-one no-double-charge classes. */
 export const DEFAULT_FALLBACK_POLICY: FallbackPolicy = { apiOnQuota: false };
 
+/**
+ * Collapse the tri-state plus the grant into the boolean the eligibility rule
+ * needs. `'ask'` without a grant is `false` — never `true` by omission, which
+ * is the one direction that would turn a configured question into silent
+ * metered spend.
+ */
+export function effectiveApiOnQuota(policy: FallbackPolicy): boolean {
+    if (policy.apiOnQuota === 'ask') return policy.billingGrant === true;
+    return policy.apiOnQuota === true;
+}
+
+/**
+ * Parse a config value into the tri-state, or throw.
+ *
+ * Rejecting is the point. A parser that mapped an unknown value onto a truthy
+ * default would turn a configured `off` into metered spend — the exact failure
+ * the `'ask'` posture exists to prevent, introduced by the code that adds it.
+ * Accepts the Python-ish spellings the council config has always allowed on
+ * the boolean side, plus `ask` on the new one.
+ */
+export function apiOnQuotaView(raw: unknown): ApiOnQuota {
+    // Lenient by design, unlike `parseApiOnQuota`: this feeds a DISPLAY
+    // surface, where throwing on a malformed file would blank the wizard
+    // instead of showing the operator the setting they need to fix. Reading
+    // by value rather than by truthiness is the half that still matters —
+    // `=== true` alone renders `'ask'` as `false`, and the next save
+    // downgrades a configured question to a configured no.
+    return raw === 'ask' ? 'ask' : raw === true;
+}
+
+export function parseApiOnQuota(raw: unknown): ApiOnQuota {
+    if (typeof raw === 'boolean') return raw;
+    if (raw === undefined || raw === null) return false;
+    if (typeof raw === 'string') {
+        const s = raw.trim().toLowerCase();
+        if (s === 'ask') return 'ask';
+        if (s === 'true' || s === 'yes' || s === 'on' || s === '1') return true;
+        if (s === '' || s === 'false' || s === 'no' || s === 'off' || s === '0') {
+            return false;
+        }
+    }
+    throw new Error(
+        `ai_council.fallback.api_on_quota: expected false | true | 'ask', got ${JSON.stringify(raw)}`,
+    );
+}
+
 /** Normalise a raw client error / skip reason into a `CliFailureClass`. */
 export function classifyCliFailure(raw: string): CliFailureClass {
     const s = raw.trim().toLowerCase();
@@ -464,7 +527,7 @@ export function isFallbackEligibleUnder(
     policy: FallbackPolicy,
 ): boolean {
     if (FALLBACK_ELIGIBLE.has(failure)) return true;
-    return policy.apiOnQuota && failure === 'quota_exhausted';
+    return effectiveApiOnQuota(policy) && failure === 'quota_exhausted';
 }
 
 /**

package/src/scripts/audit_adr_coverage.ts

@@ -28,7 +28,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { readAdrFrontmatterScalars } from './_lib/adr_frontmatter.js';
+import { readAdrAxisCells, readAdrFrontmatterScalars } from './_lib/adr_frontmatter.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -279,8 +279,13 @@ export function scan_area(area: string): [AdrEntry[], string[]] {
             errs.push(`${area}/${base}: filename does not match NNNN-<slug>.md`);
             continue;
         }
-        const fm = read_adr_meta(fs.readFileSync(p, 'utf-8'));
-        adrs.push({ num: m[1] as string, slug: m[2] as string, path: base, ...fm });
+        const text = fs.readFileSync(p, 'utf-8');
+        const fm = read_adr_meta(text);
+        // Read apart from `fm`, for the same reason the index does: the two
+        // axes are nested, so the scalar reader keeps them out of its map and
+        // spreading it could never produce these cells.
+        const axes = readAdrAxisCells(text);
+        adrs.push({ num: m[1] as string, slug: m[2] as string, path: base, ...fm, ...axes });
     }
     // Gap check.
     const nums = adrs.map((a) => parseInt(a.num, 10));
@@ -322,7 +327,11 @@ export function render_area_readme(area: string, meta: AreaMeta, adrs: AdrEntry[
     } else {
         lines.push(`Contract: _not yet published_ (\`${repoRel}\`).`);
     }
-    lines.push('', '| # | Title | Status | Date | Supersedes |', '|---|---|---|---|---|');
+    lines.push(
+        '',
+        '| # | Title | Status | Date | Provenance | Evidence | Supersedes |',
+        '|---|---|---|---|---|---|---|',
+    );
     for (const a of adrs) {
         // a.get("decision", a["slug"]).replace("-", " ").title()
         const decision = a['decision'] !== undefined ? a['decision'] : a.slug;
@@ -330,11 +339,12 @@ export function render_area_readme(area: string, meta: AreaMeta, adrs: AdrEntry[
         lines.push(
             `| [${a.num}](${a.path}) | ${title} | ` +
                 `${a['status'] ?? '—'} | ${a['date'] ?? '—'} | ` +
+                `${a['provenance_kind'] ?? '—'} | ${a['evidence_grade'] ?? '—'} | ` +
                 `${a['supersedes'] ?? '—'} |`,
         );
     }
     if (adrs.length === 0) {
-        lines.push('| _none yet_ | — | — | — | — |');
+        lines.push('| _none yet_ | — | — | — | — | — | — |');
     }
     return lines.join('\n') + '\n';
 }
@@ -411,9 +421,26 @@ export function cmd_check(): number {
             process.stderr.write(`❌ ${e}\n`);
             hard += 1;
         }
-        if (adrs.length > 0 && !_exists(path.join(ADR_ROOT, area, 'README.md'))) {
+        const readmePath = path.join(ADR_ROOT, area, 'README.md');
+        if (adrs.length > 0 && !_exists(readmePath)) {
             process.stderr.write(`❌ ${area}/: README.md missing\n`);
             hard += 1;
+        } else if (_exists(readmePath)) {
+            // Existence was the whole check until 2026-08-22, and the six
+            // committed READMEs proved what that costs: every one of them had
+            // been generated before the shared frontmatter reader landed, so
+            // they rendered `—` for `status` and `date` on ADRs that carry
+            // both — stale for months against a gate reporting zero failures.
+            // A generated file with no freshness gate is a file nobody
+            // regenerates.
+            const rendered = render_area_readme(area, meta, adrs);
+            if (fs.readFileSync(readmePath, 'utf-8') !== rendered) {
+                process.stderr.write(
+                    `❌ ${area}/README.md is stale — regenerate with ` +
+                        `\`audit_adr_coverage --regen-area-readme ${area}\`\n`,
+                );
+                hard += 1;
+            }
         }
         if (adrs.length === 0) {
             process.stderr.write(`⚠️  ${area}/: no bootstrap ADR yet (contract: ${meta.contract})\n`);