@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/ai_council/budget_guard.ts

@@ -18,7 +18,11 @@
  *   "usd": float, "provider": str, "model": str}`, optionally followed by
  *   `"cache_read_input_tokens": int, "cache_creation_input_tokens": int,
  *   "cache_ttl": "5m"|"1h"` when the caller reports cache activity — absent
- *   on every entry recorded before this extension shipped.
+ *   on every entry recorded before this extension shipped. A billable call
+ *   with no price row is written as `"usd": null, …, "unpriced": true,
+ *   "input_tokens": int, "output_tokens": int` (TS-only; reads as 0 in the sum).
+ *   With a daily ceiling set, rows also carry `"state"`, `"reservation_id"`,
+ *   `"run_id"` (and `"expires_at"` on `reserved`); see `reserve_spend`.
  * - `today_spend_usd()` sums entries within the last 24h from "now".
  * - `would_exceed(limit_usd, next_call_usd)` returns true iff the next call
  *   would push the rolling window past the limit.
@@ -38,6 +42,7 @@
  *   tz-aware comparison.
  */
 
+import { randomUUID } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
@@ -85,8 +90,29 @@ export interface SpendEntry {
     cache_creation_input_tokens?: number;
     /** Write-multiplier TTL tier in effect when this entry was recorded. */
     cache_ttl?: '5m' | '1h';
+    /** A billable call with no price row: `usd` reads as 0, the row says it is unknown. */
+    unpriced?: true;
+    input_tokens?: number;
+    output_tokens?: number;
+    /**
+     * Reservation rows (road-to-unknowns-that-say-so Phase 3), written only
+     * while a daily ceiling is set. Absent on every plain spend row.
+     */
+    state?: SpendState;
+    reservation_id?: string;
+    run_id?: string;
+    /** Epoch ms after which an open `reserved` row closes as `unreconciled`. */
+    expires_at?: number;
 }
 
+/**
+ * `reserved` → one of the three terminal states, never back. `unreconciled`
+ * is a reservation whose outcome nobody learned — it keeps its estimate,
+ * because an unknown is never a zero.
+ */
+export type SpendState = 'reserved' | 'completed' | 'released' | 'unreconciled';
+export type TerminalSpendState = Exclude<SpendState, 'reserved'>;
+
 function _nowUtcMs(): number {
     return Date.now();
 }
@@ -278,16 +304,18 @@ function _pyJsonString(s: string): string {
  */
 function _dumpEntry(
     ts: string,
-    usd: number,
+    usd: number | null,
     provider: string,
     model: string,
     cacheRead?: number,
     cacheWrite?: number,
     cacheTtl?: '5m' | '1h',
+    unpricedTokens?: { input: number; output: number },
+    reservation?: { state: SpendState; id: string; run_id: string; expires_at?: number },
 ): string {
     let body =
         `${_pyJsonString('ts')}: ${_pyJsonString(ts)}, ` +
-        `${_pyJsonString('usd')}: ${pyFloatRepr(usd)}, ` +
+        `${_pyJsonString('usd')}: ${usd === null ? 'null' : pyFloatRepr(usd)}, ` +
         `${_pyJsonString('provider')}: ${_pyJsonString(provider)}, ` +
         `${_pyJsonString('model')}: ${_pyJsonString(model)}`;
     if (cacheRead !== undefined) {
@@ -299,6 +327,21 @@ function _dumpEntry(
     if (cacheTtl !== undefined) {
         body += `, ${_pyJsonString('cache_ttl')}: ${_pyJsonString(cacheTtl)}`;
     }
+    if (unpricedTokens !== undefined) {
+        body +=
+            `, ${_pyJsonString('unpriced')}: true` +
+            `, ${_pyJsonString('input_tokens')}: ${Math.trunc(unpricedTokens.input)}` +
+            `, ${_pyJsonString('output_tokens')}: ${Math.trunc(unpricedTokens.output)}`;
+    }
+    if (reservation !== undefined) {
+        body +=
+            `, ${_pyJsonString('state')}: ${_pyJsonString(reservation.state)}` +
+            `, ${_pyJsonString('reservation_id')}: ${_pyJsonString(reservation.id)}` +
+            `, ${_pyJsonString('run_id')}: ${_pyJsonString(reservation.run_id)}`;
+        if (reservation.expires_at !== undefined) {
+            body += `, ${_pyJsonString('expires_at')}: ${_pyJsonString(nowUtcIso(reservation.expires_at))}`;
+        }
+    }
     return `{${body}}`;
 }
 
@@ -420,6 +463,21 @@ export function read_entries(p: string | null = null): SpendEntry[] {
         if (cacheTtl !== undefined) {
             entry.cache_ttl = cacheTtl;
         }
+        if (record.unpriced === true) {
+            entry.unpriced = true;
+            const inTok = _toOptionalNonNegInt(record.input_tokens);
+            if (inTok !== undefined) entry.input_tokens = inTok;
+            const outTok = _toOptionalNonNegInt(record.output_tokens);
+            if (outTok !== undefined) entry.output_tokens = outTok;
+        }
+        const state = _toSpendState(record.state);
+        if (state !== undefined && typeof record.reservation_id === 'string') {
+            entry.state = state;
+            entry.reservation_id = record.reservation_id;
+            entry.run_id = _toStr(record.run_id, '');
+            const expires = parseIso(_rawStr(record.expires_at));
+            if (expires !== null) entry.expires_at = expires;
+        }
         out.push(entry);
     }
     return out;
@@ -434,6 +492,12 @@ function _toOptionalNonNegInt(v: unknown): number | undefined {
     return n === null || n < 0 ? undefined : n;
 }
 
+function _toSpendState(v: unknown): SpendState | undefined {
+    return v === 'reserved' || v === 'completed' || v === 'released' || v === 'unreconciled'
+        ? v
+        : undefined;
+}
+
 /** `'5m' | '1h'`, or `undefined` for anything else (including absent). */
 function _toOptionalTtl(v: unknown): '5m' | '1h' | undefined {
     return v === '5m' || v === '1h' ? v : undefined;
@@ -447,21 +511,37 @@ function _rawStr(v: unknown): string {
     return _toStr(v, '');
 }
 
-/** Sum of USD spent in the last `windowHours` (rolling window). */
-export function today_spend_usd(
+/**
+ * The rolling window's priced sum, with the count of unpriced billable calls
+ * beside it. The sum alone would let an unknown read as nothing spent.
+ */
+export function today_spend_summary(
     options: { path?: string | null; now?: number | null; windowHours?: number } = {},
-): number {
+): { usd: number; unpriced_calls: number } {
     const path_ = options.path ?? null;
     const nowMs = options.now ?? _nowUtcMs();
     const windowHours = options.windowHours ?? ROLLING_WINDOW_HOURS;
     const cutoff = nowMs - windowHours * 3600 * 1000;
     let total = 0;
-    for (const e of read_entries(path_)) {
-        if (e.ts >= cutoff) {
+    let unpriced = 0;
+    const entries = read_entries(path_);
+    const closed = _terminalIds(entries);
+    for (const e of entries) {
+        // An open reservation counts at its estimate; once a terminal row
+        // exists that row carries the amount, so the reservation drops out.
+        if (e.ts >= cutoff && !(e.state === 'reserved' && closed.has(e.reservation_id ?? ''))) {
             total += e.usd;
+            if (e.unpriced) unpriced += 1;
         }
     }
-    return total;
+    return { usd: total, unpriced_calls: unpriced };
+}
+
+/** Sum of USD spent in the last `windowHours` (rolling window). */
+export function today_spend_usd(
+    options: { path?: string | null; now?: number | null; windowHours?: number } = {},
+): number {
+    return today_spend_summary(options).usd;
 }
 
 /**
@@ -495,9 +575,17 @@ export function record_spend(
         cache_read_input_tokens?: number;
         cache_creation_input_tokens?: number;
         cache_ttl?: '5m' | '1h';
+        // A BILLABLE call whose model has no price row (road-to-unknowns-that-
+        // say-so 2.3). Its `usd` is not zero, it is unknown, so it is written
+        // as `usd: null, unpriced: true` with the tokens it used — never
+        // dropped beside the subscription calls the early return below skips.
+        unpriced?: boolean;
+        input_tokens?: number;
+        output_tokens?: number;
     } = {},
 ): boolean {
-    if (usd <= 0) {
+    const unpriced = options.unpriced === true;
+    if (usd <= 0 && !unpriced) {
         return true; // zero-cost calls (manual mode) skip the ledger
     }
     const p = options.path ?? LEDGER_PATH;
@@ -508,12 +596,13 @@ export function record_spend(
     const ts = nowUtcIso(nowMs);
     const entry = `${_dumpEntry(
         ts,
-        _pyRound6(usd),
+        unpriced ? null : _pyRound6(usd),
         provider,
         model,
         options.cache_read_input_tokens,
         options.cache_creation_input_tokens,
         options.cache_ttl,
+        unpriced ? { input: options.input_tokens ?? 0, output: options.output_tokens ?? 0 } : undefined,
     )}\n`;
     try {
         fs.appendFileSync(p, entry, { encoding: 'utf-8' });
@@ -526,6 +615,206 @@ export function record_spend(
     return true;
 }
 
+/** Reservation ids that already have a terminal row. */
+function _terminalIds(entries: readonly SpendEntry[]): Set<string> {
+    const out = new Set<string>();
+    for (const e of entries) {
+        if (e.state !== undefined && e.state !== 'reserved' && e.reservation_id !== undefined) {
+            out.add(e.reservation_id);
+        }
+    }
+    return out;
+}
+
+/** How long a reservation lock is waited for, and when a held lock counts as crashed. */
+export const RESERVATION_LOCK_WAIT_MS = 3000;
+const RESERVATION_LOCK_STALE_MS = 10_000;
+
+function _sleepMs(ms: number): void {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Run `fn` holding `<ledger>.lock`, created `O_EXCL`. Unlike the counter lock
+ * in `cli_call_budget.ts`, a wait that runs out returns `null` instead of
+ * proceeding unlocked: a ceiling checked without the lock is the race this
+ * exists to close, so the caller refuses rather than guesses.
+ */
+function _withLedgerLock<T>(p: string, waitMs: number, fn: () => T): T | null {
+    if (!_ensureLedgerDir(p)) {
+        return null;
+    }
+    const lockPath = `${p}.lock`;
+    const started = Date.now();
+    let fd: number | null = null;
+    while (fd === null) {
+        try {
+            fd = fs.openSync(lockPath, 'wx', 0o600);
+            break;
+        } catch {
+            try {
+                if (Date.now() - fs.statSync(lockPath).mtimeMs > RESERVATION_LOCK_STALE_MS) {
+                    fs.unlinkSync(lockPath);
+                }
+            } catch {
+                // Released between the failed create and the stat — retry.
+            }
+        }
+        if (Date.now() - started >= waitMs) {
+            return null;
+        }
+        _sleepMs(15);
+    }
+    try {
+        return fn();
+    } finally {
+        fs.closeSync(fd);
+        try {
+            fs.unlinkSync(lockPath);
+        } catch {
+            // Already gone is the end state wanted.
+        }
+    }
+}
+
+function _appendLine(p: string, line: string): boolean {
+    try {
+        fs.appendFileSync(p, `${line}\n`, { encoding: 'utf-8' });
+    } catch (exc) {
+        process.stderr.write(`[council:budget_guard] write failed: ${_errStr(exc)}\n`);
+        return false;
+    }
+    _ensureLedgerFileMode(p);
+    return true;
+}
+
+/**
+ * Close every open reservation whose hold ran out as `unreconciled` at its
+ * estimate (D8). Caller holds the lock. A killed run never reaches its own
+ * close, so without this its reservation would hold budget forever.
+ */
+function _expireStale(p: string, entries: readonly SpendEntry[], nowMs: number): void {
+    const closed = _terminalIds(entries);
+    for (const e of entries) {
+        if (
+            e.state === 'reserved' &&
+            e.reservation_id !== undefined &&
+            !closed.has(e.reservation_id) &&
+            e.expires_at !== undefined &&
+            e.expires_at <= nowMs
+        ) {
+            closed.add(e.reservation_id);
+            _appendLine(
+                p,
+                _dumpEntry(nowUtcIso(nowMs), _pyRound6(e.usd), e.provider, e.model,
+                    undefined, undefined, undefined, undefined,
+                    { state: 'unreconciled', id: e.reservation_id, run_id: e.run_id ?? '' }),
+            );
+        }
+    }
+}
+
+/**
+ * The effective state of every reservation in the ledger. An open one past
+ * its hold reads `unreconciled` here even before a locked writer persists it.
+ */
+export function reservation_states(
+    options: { path?: string | null; now?: number | null } = {},
+): Map<string, SpendState> {
+    const nowMs = options.now ?? _nowUtcMs();
+    const out = new Map<string, SpendState>();
+    for (const e of read_entries(options.path ?? null)) {
+        if (e.state === undefined || e.reservation_id === undefined) continue;
+        if (e.state !== 'reserved') {
+            out.set(e.reservation_id, e.state);
+        } else if (!out.has(e.reservation_id)) {
+            const stale = e.expires_at !== undefined && e.expires_at <= nowMs;
+            out.set(e.reservation_id, stale ? 'unreconciled' : 'reserved');
+        }
+    }
+    return out;
+}
+
+export type ReserveResult = { ok: true; id: string } | { ok: false; reason: 'daily' | 'lock' };
+
+/**
+ * Check a daily ceiling and claim the estimate in ONE locked step.
+ *
+ * `would_exceed` reads the ledger and compares; two councils started together
+ * both read the same remainder and both pass. Here the read, the comparison and
+ * the `reserved` row happen under the ledger lock, and every later read counts
+ * the open reservation at its estimate, so the second council sees the first.
+ * Only meaningful with a ceiling set — the orchestrator never calls it otherwise.
+ */
+export function reserve_spend(
+    limitUsd: number,
+    estimateUsd: number,
+    provider: string,
+    model: string,
+    options: {
+        path?: string | null;
+        now?: number | null;
+        run_id: string;
+        hold_ms: number;
+        windowHours?: number;
+        lock_wait_ms?: number;
+    },
+): ReserveResult {
+    const p = options.path ?? LEDGER_PATH;
+    const nowMs = options.now ?? _nowUtcMs();
+    const verdict = _withLedgerLock(p, options.lock_wait_ms ?? RESERVATION_LOCK_WAIT_MS, (): ReserveResult => {
+        _expireStale(p, read_entries(p), nowMs);
+        const window = options.windowHours ?? ROLLING_WINDOW_HOURS;
+        const spent = today_spend_usd({ path: p, now: nowMs, windowHours: window });
+        if (limitUsd > 0 && spent + estimateUsd > limitUsd) {
+            return { ok: false, reason: 'daily' };
+        }
+        const id = randomUUID();
+        const line = _dumpEntry(nowUtcIso(nowMs), _pyRound6(estimateUsd), provider, model,
+            undefined, undefined, undefined, undefined,
+            { state: 'reserved', id, run_id: options.run_id, expires_at: nowMs + options.hold_ms });
+        return _appendLine(p, line) ? { ok: true, id } : { ok: false, reason: 'lock' };
+    });
+    return verdict ?? { ok: false, reason: 'lock' };
+}
+
+/**
+ * Append the terminal row for a reservation. `completed` carries the actual
+ * amount, `released` zero, `unreconciled` the reservation's own estimate.
+ * Returns false — and writes nothing — when the reservation is unknown or
+ * already terminal: a terminal state never reopens.
+ */
+export function close_reservation(
+    id: string,
+    state: TerminalSpendState,
+    options: {
+        path?: string | null;
+        now?: number | null;
+        usd?: number;
+        provider?: string;
+        model?: string;
+        lock_wait_ms?: number;
+    } = {},
+): boolean {
+    const p = options.path ?? LEDGER_PATH;
+    const nowMs = options.now ?? _nowUtcMs();
+    const done = _withLedgerLock(p, options.lock_wait_ms ?? RESERVATION_LOCK_WAIT_MS, (): boolean => {
+        _expireStale(p, read_entries(p), nowMs);
+        const entries = read_entries(p);
+        if (_terminalIds(entries).has(id)) return false;
+        const reserved = entries.find((e) => e.state === 'reserved' && e.reservation_id === id);
+        if (reserved === undefined) return false;
+        const usd = state === 'completed' ? (options.usd ?? 0) : state === 'released' ? 0 : reserved.usd;
+        return _appendLine(
+            p,
+            _dumpEntry(nowUtcIso(nowMs), _pyRound6(usd), options.provider ?? reserved.provider,
+                options.model ?? reserved.model, undefined, undefined, undefined, undefined,
+                { state, id, run_id: reserved.run_id ?? '' }),
+        );
+    });
+    return done === true;
+}
+
 /**
  * `round(usd, 6)` with Python's round-half-to-even on the exact IEEE-754
  * value. Implemented via the 17-significant-digit decimal expansion so the

package/src/scripts/ai_council/bundler.ts

@@ -10,8 +10,9 @@
  * included.
  *
  * Hard rules:
- * - Redaction is fail-closed. If a redaction pattern fires, the line is
- *   scrubbed *before* the bundle is built.
+ * - Redaction is fail-closed. Every detected value is replaced by its
+ *   placeholder *before* the bundle is built, and the member call refuses a
+ *   body that still carries one.
  * - Size guard is fail-loud. > MAX_BUNDLE_BYTES → raises BundleTooLarge,
  *   never silently truncates (would mislead council members).
  */
@@ -20,6 +21,8 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { councilEgress, type CouncilEgress } from './council_egress.js';
+
 export const MAX_BUNDLE_BYTES = 50 * 1024; // 50 KB hard ceiling; user must narrow scope on hit.
 
 /** Raised when the assembled bundle exceeds MAX_BUNDLE_BYTES. */
@@ -74,33 +77,18 @@ function _splitlines(s: string): string[] {
     return lines;
 }
 
-// ── redaction patterns ───────────────────────────────────────────────────
-// Each pattern is matched line-wise; matching lines are replaced with the
-// placeholder. Order matters — the most specific pattern goes first.
-
-const _REDACTION_LINE_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
-    [/~?\/?\.event4u\/agent-config\/[^/\s]+\.key/u, '[redacted: agent-config key path]'],
-    [/~?\/?\.config\/agent-config\/[^/\s]+\.key/u, '[redacted: agent-config key path]'],
-    [/^\s*Authorization:\s/iu, '[redacted: Authorization header]'],
-    [/(api[_-]?key|secret|token|password)\s*[:=]/iu, '[redacted: secret-like assignment]'],
-    [/sk-ant-[A-Za-z0-9_\-]{8,}/u, '[redacted: anthropic-key-like token]'],
-    [/sk-[A-Za-z0-9_\-]{20,}/u, '[redacted: openai-key-like token]'],
-];
-
-/** Apply redaction patterns to a multi-line text buffer. */
-export function redact(text: string): string {
-    const out: string[] = [];
-    for (const line of _splitlines(text)) {
-        let replaced = line;
-        for (const [pattern, placeholder] of _REDACTION_LINE_PATTERNS) {
-            if (pattern.test(replaced)) {
-                replaced = placeholder;
-                break;
-            }
-        }
-        out.push(replaced);
-    }
-    return out.join('\n');
+// Every value the one rule table detects — its credential rows, the reviewer-
+// threshold assignment and Authorization rows, and the bundler's own looser
+// readings (council_egress.ts) — is replaced by a typed placeholder of the
+// grammar in docs/contracts/egress-placeholders-v1.md, span by span, so a
+// finding no longer costs the reviewer its whole line
+// (road-to-one-detector-and-the-senders-we-own 3.3). The run's scope remembers
+// what it replaced, and every member call checks its body against it before
+// the request is written (`callMember`).
+
+/** Replace every detected value with its placeholder. Line endings are normalised to `\n`. */
+export function redact(text: string, egress: CouncilEgress = councilEgress()): string {
+    return egress.replace(_splitlines(text).join('\n'));
 }
 
 function _enforceSize(text: string, mode: string): string {
@@ -159,6 +147,9 @@ export function bundle_diff(
     const proc = spawnSync('git', cmd, {
         cwd: cwd ?? undefined,
         encoding: 'utf-8',
+        // Above Node's 1 MiB default the spawn fails with an empty stderr; the
+        // size guard below has to see the diff to refuse it as BundleTooLarge.
+        maxBuffer: 64 * 1024 * 1024,
     });
     if (proc.error || proc.status !== 0) {
         const stderr = (proc.stderr ?? '').toString();

package/src/scripts/ai_council/chairman.ts

@@ -17,11 +17,15 @@
 // one-advisor-per-provider invariant), so every enabled member that did not
 // deliberate is provider-different from every deliberator by construction.
 
+import { seatRoleRefusal } from './seat_policy.js';
+
 export interface ChairmanCandidate {
     /** Member name (== provider key in this engine). */
     name: string;
     /** Optional capability rank from `members.<name>.tier`; higher = stronger. */
     tier: number | null;
+    /** The seat's billing class; an unpaid one never chairs (ADR-257). Absent = paid. */
+    billing?: string | null;
 }
 
 export interface ChairmanSelection {
@@ -56,6 +60,13 @@ export function select_chairman(
                 annotation: `Chairman: host (member ${_q(member)} unavailable — host fallback)`,
             };
         }
+        const refusal = seatRoleRefusal('synthesis', candidates.find((c) => c.name === member)?.billing, member);
+        if (refusal !== null) {
+            return {
+                member: null,
+                annotation: `Chairman: host (member ${_q(member)} refused: ${refusal.reason} — ${refusal.message})`,
+            };
+        }
         if (deliberated.has(member)) {
             // A member that argued in the debate cannot independently judge it.
             return {
@@ -67,13 +78,17 @@ export function select_chairman(
     }
     // mode === 'auto' — provider-family difference primary (non-deliberating ⇒
     // provider-different by construction here); tier tie-break; config-order final.
-    const pool = candidates.filter((c) => !deliberated.has(c.name));
-    if (pool.length === 0) {
+    const nonPanel = candidates.filter((c) => !deliberated.has(c.name));
+    if (nonPanel.length === 0) {
         return {
             member: null,
             annotation: 'Chairman: host (no non-panel member available)',
         };
     }
+    const pool = nonPanel.filter((c) => seatRoleRefusal('synthesis', c.billing) === null);
+    if (pool.length === 0) {
+        return { member: null, annotation: 'Chairman: host (no paid non-panel member available)' };
+    }
     let best = pool[0] as ChairmanCandidate;
     for (const c of pool.slice(1)) {
         const bestTier = best.tier ?? Number.NEGATIVE_INFINITY;