@event4u/agent-config 16.5.0 → 17.1.0

package/src/scripts/ai_council/route_chooser.ts

@@ -0,0 +1,161 @@
+/**
+ * Which route serves one rung-0.5 call. Replaces "the first configured member":
+ * list order says nothing about cost, content ceiling, quota or liveness.
+ *
+ * Order: an admissible unpaid route, else a paid fallback, else an honest ∅.
+ * Head-only work (plan, decide, chair, final review, anything that writes) is
+ * refused here before any candidate is looked at, and an untyped ask may only
+ * use a paid route: a free hand is defined by its typed, schema-checked return.
+ */
+
+import type { ExternalAIClient } from './clients.js';
+import { EXPOSURE_SHARE_CAP } from './exposure_ledger.js';
+import { admitsContent, classifyContentClass, DEFAULT_SEAT_CEILING, type ContentClass } from './content_ceiling.js';
+import {
+    isHeadOnlyKind,
+    isUnpaid,
+    ROUTE_BILLINGS,
+    type HandKind,
+    type HeadOnlyKind,
+    type RouteBilling,
+} from '../_lib/hand_kinds.js';
+
+export { isUnpaid, ROUTE_BILLINGS, type RouteBilling };
+
+/** The route shape the chooser reads; built from a council member by {@link routeCandidateFromMember}. */
+export interface RouteCandidate {
+    readonly name: string;
+    readonly billing: RouteBilling;
+    readonly ceiling: ContentClass;
+    /** Calls left in the current quota window; null when unknown or unmetered. */
+    readonly remainingQuota: number | null;
+    readonly live: boolean;
+}
+
+export type RouteRefusalReason =
+    | 'not-live'
+    | 'quota-exhausted'
+    | 'content-ceiling'
+    | 'untyped-call'
+    | 'kind-not-flipped'
+    | 'exposure-cap'
+    | 'exposure-unknown';
+
+export interface RouteRefusal {
+    readonly name: string;
+    readonly reason: RouteRefusalReason;
+}
+
+export interface ChooseInput {
+    readonly kind: HandKind | HeadOnlyKind | null;
+    readonly contentClass: ContentClass;
+    readonly candidates: readonly RouteCandidate[];
+    /**
+     * Each route's share of tracked files after this call; null when the share
+     * cannot be computed. Absent means exposure is not tracked for this call.
+     */
+    readonly exposureShare?: (route: string) => number | null;
+    /** Default {@link EXPOSURE_SHARE_CAP}. */
+    readonly exposureCap?: number;
+    /**
+     * False when the kind has not cleared the shadow bars (free-hands 6.3):
+     * every unpaid route is then refused. Absent keeps the chooser's own order.
+     */
+    readonly unpaidAllowed?: boolean;
+}
+
+export type RouteChoice =
+    | { readonly route: RouteCandidate; readonly reason: 'unpaid-route' | 'paid-fallback'; readonly refused: RouteRefusal[] }
+    | { readonly route: null; readonly reason: 'head-only' | 'no-admissible-route'; readonly refused: RouteRefusal[] };
+
+function refusalOf(c: RouteCandidate, input: ChooseInput): RouteRefusalReason | null {
+    if (!c.live) return 'not-live';
+    if (c.remainingQuota !== null && c.remainingQuota <= 0) return 'quota-exhausted';
+    if (!admitsContent(c.ceiling, input.contentClass).admitted) return 'content-ceiling';
+    if (isUnpaid(c.billing) && input.kind === null) return 'untyped-call';
+    if (isUnpaid(c.billing) && input.unpaidAllowed === false) return 'kind-not-flipped';
+    if (input.exposureShare !== undefined) {
+        const share = input.exposureShare(c.name);
+        // Unknown exposure fails closed for an unpaid route only; a paid route
+        // stays usable so an untracked project still has a fallback.
+        if (share === null) return isUnpaid(c.billing) ? 'exposure-unknown' : null;
+        if (share > (input.exposureCap ?? EXPOSURE_SHARE_CAP)) return 'exposure-cap';
+    }
+    return null;
+}
+
+/** A known positive quota before an unknown one, more before less; list order breaks ties. */
+function byQuota(a: RouteCandidate, b: RouteCandidate): number {
+    if (a.remainingQuota === b.remainingQuota) return 0;
+    if (a.remainingQuota === null) return 1;
+    if (b.remainingQuota === null) return -1;
+    return b.remainingQuota - a.remainingQuota;
+}
+
+export interface RouteChain {
+    /** Every admissible route, in the order a failed call walks them. */
+    readonly chain: RouteCandidate[];
+    readonly headOnly: boolean;
+    readonly refused: RouteRefusal[];
+}
+
+export function chooseRouteChain(input: ChooseInput): RouteChain {
+    const refused: RouteRefusal[] = [];
+    if (isHeadOnlyKind(input.kind)) return { chain: [], headOnly: true, refused };
+    const admissible: RouteCandidate[] = [];
+    for (const c of input.candidates) {
+        const why = refusalOf(c, input);
+        if (why === null) admissible.push(c);
+        else refused.push({ name: c.name, reason: why });
+    }
+    const share = (c: RouteCandidate): number => input.exposureShare?.(c.name) ?? 0;
+    const order = (a: RouteCandidate, b: RouteCandidate): number => share(a) - share(b) || byQuota(a, b);
+    const unpaid = admissible.filter((c) => isUnpaid(c.billing)).sort(order);
+    const paid = admissible.filter((c) => !isUnpaid(c.billing)).sort(order);
+    return { chain: [...unpaid, ...paid], headOnly: false, refused };
+}
+
+export function chooseRoute(input: ChooseInput): RouteChoice {
+    const { chain, headOnly, refused } = chooseRouteChain(input);
+    if (headOnly) return { route: null, reason: 'head-only', refused };
+    const first = chain[0];
+    if (first === undefined) return { route: null, reason: 'no-admissible-route', refused };
+    return { route: first, reason: isUnpaid(first.billing) ? 'unpaid-route' : 'paid-fallback', refused };
+}
+
+const _BILLINGS: ReadonlySet<string> = new Set<string>(ROUTE_BILLINGS);
+
+/**
+ * A council member as a route. Members built today carry none of the route
+ * fields, so they map to a paid, project-content, live route — exactly the seat
+ * they were. A member whose billing is `free-quota` is pinned to
+ * `public-artifact` whatever ceiling it declares: every free route stays there.
+ * A `self-hosted` member that declares no ceiling gets `public-artifact` too;
+ * only a declared, probed `content_ceiling` raises it.
+ */
+export function routeCandidateFromMember(member: ExternalAIClient): RouteCandidate {
+    const m = member as unknown as Record<string, unknown>;
+    const name = (typeof m['name'] === 'string' && m['name']) || (typeof m['provider'] === 'string' && m['provider']) || 'unknown';
+    // A base_url route member names its class `billing`; other members may say `billing_class`.
+    const declared = m['billing_class'] ?? m['billing'];
+    const billing: RouteBilling =
+        typeof declared === 'string' && _BILLINGS.has(declared)
+            ? (declared as RouteBilling)
+            : m['billable'] === false
+              ? 'subscription'
+              : 'per-token';
+    // An unpaid route that names no ceiling gets the narrow one; only a member
+    // that predates route fields keeps the default seat ceiling.
+    const ceiling: ContentClass =
+        billing === 'free-quota'
+            ? 'public-artifact'
+            : classifyContentClass(m['content_ceiling'], isUnpaid(billing) || typeof m['base_url'] === 'string' ? 'public-artifact' : DEFAULT_SEAT_CEILING);
+    const quota = m['remaining_quota'];
+    return {
+        name,
+        billing,
+        ceiling,
+        remainingQuota: typeof quota === 'number' && Number.isFinite(quota) ? quota : null,
+        live: m['live'] !== false,
+    };
+}

package/src/scripts/ai_council/route_liveness.ts

@@ -0,0 +1,152 @@
+/**
+ * Liveness of a `base_url` route, per route and model: streaks, not last
+ * outcomes (gateway M9).
+ *
+ * The outcome names are the closed failure vocabulary of
+ * road-to-seats-that-know-why-they-failed — `rate_limited`,
+ * `quota_exhausted`, `model_unservable`, `server_error`, `billing` — read here
+ * from the route's own HTTP answer by a small local classifier, so the two
+ * converge when that roadmap's shared table lands instead of meeting a second
+ * vocabulary.
+ *
+ * Only `model_unservable` speaks about the model: a throttle, an empty quota or
+ * a server fault says the route is busy or down for this pass, never that the
+ * model is gone, so they never count against liveness and never break a streak.
+ * An answered call resets it. Three consecutive unservable answers retire the
+ * model from the discovered roster until a later discovery serves it again.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readRouteRoster, retireRouteModel } from './free_route_catalog.js';
+import type { CliFailureClass } from './transport_resolver.js';
+
+export const ROUTE_OUTCOMES = [
+    'ok',
+    'rate_limited',
+    'quota_exhausted',
+    'model_unservable',
+    'server_error',
+    'billing',
+    'other',
+] as const;
+export type RouteOutcome = (typeof ROUTE_OUTCOMES)[number];
+
+export const RETIRE_STREAK = 3;
+
+/** Runtime state beside `council-route-models.json`; gitignored, never committed. */
+export const ROUTE_LIVENESS_RELPATH = path.join('agents', 'runtime', 'state', 'council-route-liveness.json');
+
+const _QUOTA_TEXT = /insufficient_quota|quota exceeded|exceeded your current quota|usage limit/i;
+
+/** The route's answer as one vocabulary name; `null` / empty means it answered. */
+export function classifyRouteOutcome(error: string | null | undefined): RouteOutcome {
+    if (error === null || error === undefined || error.trim() === '') return 'ok';
+    const s = error.trim();
+    if (s.startsWith('policy_unproven_cost')) return 'billing';
+    const m = /^HTTP (\d{3})\b:?\s*([\s\S]*)$/.exec(s);
+    if (m === null) return 'other';
+    const status = Number(m[1]);
+    const body = m[2] ?? '';
+    if (status === 402) return 'billing';
+    if (status === 429) return _QUOTA_TEXT.test(body) ? 'quota_exhausted' : 'rate_limited';
+    if (status === 410) return 'model_unservable';
+    if (status === 404) return /\bmodel\b/i.test(body) ? 'model_unservable' : 'other';
+    // 501 and 505 say the route cannot do this at all; retrying is pointless.
+    if (status >= 500 && status <= 599 && status !== 501 && status !== 505) return 'server_error';
+    return 'other';
+}
+
+/** Absent for this pass only: busy or down, never evidence about the model. */
+export function isAbsentForPass(outcome: RouteOutcome): boolean {
+    return outcome === 'rate_limited' || outcome === 'quota_exhausted' || outcome === 'server_error';
+}
+
+/** The outcome as the class `MidFlightFallback` gates on. */
+export function routeFailureClass(outcome: RouteOutcome): CliFailureClass {
+    switch (outcome) {
+        case 'rate_limited':
+        case 'quota_exhausted':
+            return 'quota_exhausted';
+        case 'model_unservable':
+            return 'model_unservable';
+        case 'server_error':
+            return 'server_error';
+        default:
+            return 'other';
+    }
+}
+
+interface LivenessEntry {
+    readonly streak: number;
+    readonly last: RouteOutcome;
+    readonly observed_at: string;
+    readonly retired_at?: string;
+}
+
+type Store = Record<string, Record<string, LivenessEntry>>;
+
+function _storePath(repoRoot: string): string {
+    return path.join(repoRoot, ROUTE_LIVENESS_RELPATH);
+}
+
+function _readStore(repoRoot: string): Store {
+    try {
+        const raw = JSON.parse(fs.readFileSync(_storePath(repoRoot), 'utf8')) as unknown;
+        return raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Store) : {};
+    } catch {
+        return {};
+    }
+}
+
+function _writeStore(repoRoot: string, store: Store): void {
+    const target = _storePath(repoRoot);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+    fs.renameSync(tmp, target);
+}
+
+/** A retirement stands until the roster is re-discovered after it. */
+function _retirementStands(repoRoot: string, routeKey: string, entry: LivenessEntry | undefined): boolean {
+    if (entry?.retired_at === undefined) return false;
+    const roster = readRouteRoster(repoRoot, routeKey);
+    return roster.status !== 'known' || roster.observed_at <= entry.retired_at;
+}
+
+export function isRouteModelLive(repoRoot: string, routeKey: string, model: string): boolean {
+    return !_retirementStands(repoRoot, routeKey, _readStore(repoRoot)[routeKey]?.[model]);
+}
+
+export interface RecordedOutcome {
+    readonly streak: number;
+    readonly retired: boolean;
+    readonly absentForPass: boolean;
+}
+
+export function recordRouteOutcome(
+    repoRoot: string,
+    routeKey: string,
+    model: string,
+    outcome: RouteOutcome,
+    now: Date = new Date(),
+): RecordedOutcome {
+    const store = _readStore(repoRoot);
+    const route = store[routeKey] ?? {};
+    let prev = route[model];
+    if (prev?.retired_at !== undefined && !_retirementStands(repoRoot, routeKey, prev)) prev = undefined;
+    const before = prev?.streak ?? 0;
+    const streak = outcome === 'ok' ? 0 : outcome === 'model_unservable' ? before + 1 : before;
+    const observed_at = now.toISOString();
+    let retiredAt = prev?.retired_at;
+    if (retiredAt === undefined && streak >= RETIRE_STREAK) {
+        retiredAt = observed_at;
+        retireRouteModel(repoRoot, routeKey, model);
+    }
+    route[model] = { streak, last: outcome, observed_at, ...(retiredAt !== undefined ? { retired_at: retiredAt } : {}) };
+    store[routeKey] = route;
+    _writeStore(repoRoot, store);
+    return { streak, retired: retiredAt !== undefined, absentForPass: isAbsentForPass(outcome) };
+}
+

package/src/scripts/ai_council/route_member.ts

@@ -0,0 +1,114 @@
+/**
+ * Construct a `base_url` route member for a council pass, or say why it is
+ * absent. Lives apart from `council_cli.ts`, which is far past the source
+ * ceiling, and apart from `free_route.ts`, which `config.ts` imports and which
+ * therefore must not import the loader back.
+ */
+
+import { resolve_project_root } from '../_lib/agent_settings.js';
+import { PROVIDER_TABLE } from '../_lib/environment_detector.js';
+import { resolve_api_key } from './config.js';
+import { classifyContentClass, DEFAULT_SEAT_CEILING, type ContentClass } from './content_ceiling.js';
+import type { ExternalAIClient } from './clients.js';
+import { FreeRouteClient } from './free_route_client.js';
+import { readRouteRoster, ROUTE_CATALOG } from './free_route_catalog.js';
+import {
+    parseRouteFields,
+    resolveRouteTransport,
+    routeCeiling,
+    type SelfHostedProbeResult,
+    type RouteBilling,
+    type SelfHostedProbe,
+} from './free_route.js';
+import { SELF_HOSTED_PROBE, type ProbeRoute } from './self_hosted_probe.js';
+import { keyResolves } from './status_surface.js';
+
+export type RouteMemberResult =
+    | { readonly client: FreeRouteClient }
+    | { readonly absent: { member: string; reason: string; detail: string } };
+
+/** `null` for a provider member; otherwise the constructed client or its absence. */
+export function routeMemberFor(
+    name: string,
+    cfg: Record<string, unknown>,
+    contentClass: ContentClass,
+    modelOverride?: string,
+    probe: SelfHostedProbe = SELF_HOSTED_PROBE,
+    stateRoot?: string,
+    now: Date = new Date(),
+): RouteMemberResult | null {
+    const parsed = parseRouteFields(name, cfg, Object.hasOwn(PROVIDER_TABLE, name));
+    if ('error' in parsed) return { absent: { member: name, reason: 'policy_unknown', detail: parsed.error } };
+    const route = parsed.route;
+    if (route === null) return null;
+    const model = modelOverride || (typeof cfg['model'] === 'string' ? cfg['model'] : '');
+    // The root discovery writes under, so a run from a subdirectory reads the same roster.
+    const gate = firstPartyGate(route.base_url, model, stateRoot ?? resolve_project_root(null)[0], now);
+    if (gate !== null) return { absent: { member: name, reason: 'policy_model_mismatch', detail: gate } };
+    const ref = typeof cfg['api_key_ref'] === 'string' ? cfg['api_key_ref'] : null;
+    // A keyed loopback route can only be proven with its key on the probe call.
+    let probed: SelfHostedProbeResult | undefined;
+    const keyedProbe: SelfHostedProbe = (r, m) => {
+        const withKey: ProbeRoute = { ...r, api_key_ref: ref };
+        return (probed = probe(withKey, m));
+    };
+    const t = resolveRouteTransport({ name, route, model, contentClass, keyPresent: keyResolves(ref), probe: keyedProbe });
+    if (!t.available) {
+        return { absent: { member: name, reason: t.absentReason ?? 'unavailable', detail: t.reason ?? 'route unavailable' } };
+    }
+    return {
+        client: new FreeRouteClient({
+            name,
+            model,
+            base_url: route.base_url,
+            api_key: ref === null ? null : resolve_api_key(ref, `ai_council.members.${name}`),
+            billing: t.billing as RouteBilling,
+            content_ceiling: routeCeiling(route, probed),
+        }),
+    };
+}
+
+/** A built seat carries the ceiling its config declares; a route client keeps its own. */
+export function stampSeatCeilings(members: readonly ExternalAIClient[], membersCfg: Record<string, unknown>): void {
+    for (const m of members) {
+        const seat = m as unknown as Record<string, unknown>;
+        if (m instanceof FreeRouteClient || seat['content_ceiling'] !== undefined) continue;
+        const cfg = membersCfg[m.name];
+        const declared = typeof cfg === 'object' && cfg !== null ? (cfg as Record<string, unknown>)['content_ceiling'] : undefined;
+        seat['content_ceiling'] = classifyContentClass(declared, DEFAULT_SEAT_CEILING);
+    }
+}
+
+/** A first-party roster older than this no longer says which models are first-party. */
+export const FIRST_PARTY_ROSTER_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * On a catalogued route whose attestation covers first-party models only, the
+ * model must be in a fresh discovered first-party roster; anything else is a
+ * reason to be absent, so an unknown provenance never reaches the route.
+ */
+function firstPartyGate(baseUrl: string, model: string, stateRoot: string, now: Date): string | null {
+    const key = routeIdentity(baseUrl);
+    const row = ROUTE_CATALOG.find((r) => r.first_party_list !== undefined && routeIdentity(r.base_url) === key);
+    if (row === undefined) return null;
+    const roster = readRouteRoster(stateRoot, row.id);
+    if (roster.status !== 'known') return `${row.id}: no discovered first-party roster (${roster.reason})`;
+    if (now.getTime() - Date.parse(roster.observed_at) > FIRST_PARTY_ROSTER_MAX_AGE_MS) {
+        return `${row.id}: first-party roster from ${roster.observed_at} is older than a day`;
+    }
+    if (!roster.models.includes(model)) return `${row.id}: ${model} is not in the route's first-party roster`;
+    return null;
+}
+
+/**
+ * Host and path, scheme dropped: an `http` or mixed-case spelling of a
+ * catalogued route is the same route to the gate, so it cannot step around it.
+ */
+export function routeIdentity(url: string): string {
+    try {
+        const u = new URL(url);
+        return `${u.host}${u.pathname.replace(/\/+$/, '')}`;
+    } catch {
+        return url.trim().toLowerCase().replace(/\/+$/, '');
+    }
+}

package/src/scripts/ai_council/seat_policy.ts

@@ -135,3 +135,50 @@ export function parseSeatFields(
         },
     };
 }
+
+/**
+ * Council roles, and the three a route this package does not pay for may never
+ * hold (ADR-257: an unpaid route may propose and score, never decide). Kept
+ * apart from `PolicyExclusion`: that union makes a seat ABSENT for the whole
+ * run, while a role refusal leaves the seat free to propose or judge.
+ */
+export const COUNCIL_ROLES = ['proposer', 'juror', 'chair', 'synthesis', 'verdict'] as const;
+export type CouncilRole = (typeof COUNCIL_ROLES)[number];
+export const HEAD_ROLES: ReadonlySet<CouncilRole> = new Set<CouncilRole>(['chair', 'synthesis', 'verdict']);
+
+const _PAID_BILLING: ReadonlySet<string> = new Set(['subscription', 'per-token']);
+/** The classes positively known to cost the package nothing per call. */
+export const UNPAID_BILLING_CLASSES: readonly string[] = ['free-quota', 'self-hosted'];
+
+/**
+ * True unless the billing class is a paid one. Absent means a seat configured
+ * before billing classes existed, all of them paid; any other unrecognised
+ * value fails closed, so a typo cannot hand a free route the chair.
+ */
+export function isUnpaidBilling(billing: string | null | undefined): boolean {
+    return billing !== undefined && billing !== null && !_PAID_BILLING.has(billing);
+}
+
+export interface RoleRefusal {
+    readonly reason: 'unpaid_head_role' | 'route_head_role';
+    readonly message: string;
+}
+
+export function seatRoleRefusal(
+    role: CouncilRole,
+    billing: string | null | undefined,
+    seat = 'this seat',
+    route = false,
+): RoleRefusal | null {
+    if (HEAD_ROLES.has(role) && route) {
+        return {
+            reason: 'route_head_role',
+            message: `${seat} is a base_url route and may not hold the ${role} role, whatever billing it reports (ADR-257)`,
+        };
+    }
+    if (!HEAD_ROLES.has(role) || !isUnpaidBilling(billing)) return null;
+    return {
+        reason: 'unpaid_head_role',
+        message: `${seat} (billing ${String(billing)}) may not hold the ${role} role: an unpaid route proposes and scores, never decides (ADR-257)`,
+    };
+}

package/src/scripts/ai_council/seat_resume.ts

@@ -0,0 +1,40 @@
+/**
+ * Whether a council seat continues its CLI session — road-to-a-cold-start-paid-once 5.2.
+ *
+ * Only a non-blind follow-up to the same seat resumes, and only inside the
+ * window the provider's prompt cache lives for. A blind round never resumes:
+ * the session holds the reviewer's earlier position, and an anonymised round
+ * exists precisely so the reviewer cannot recognise it.
+ */
+
+export interface SeatSession {
+    readonly id: string;
+    readonly at_ms: number;
+}
+
+/** The prompt-cache lifetime a resume is worth paying for. */
+export const SEAT_RESUME_TTL_MS = 5 * 60_000;
+
+/** Extra argv for a resumed call; `[]` means a fresh session. */
+export function seatResumeArgs(
+    provider: string,
+    session: SeatSession | null,
+    ctx: { readonly blind: boolean; readonly now_ms: number; readonly ttl_ms?: number },
+): string[] {
+    if (ctx.blind || session === null || session.id === '') return [];
+    const age = ctx.now_ms - session.at_ms;
+    if (age < 0 || age >= (ctx.ttl_ms ?? SEAT_RESUME_TTL_MS)) return [];
+    if (provider === 'anthropic') return ['--resume', session.id];
+    if (provider === 'openai') return ['resume', session.id];
+    return [];
+}
+
+/**
+ * `codex exec resume` refuses `--sandbox` (measured on codex-cli 0.148.0), so a
+ * resumed seat carries the same bound as a config override instead of dropping it.
+ */
+export function resumeBound(bound: readonly string[]): string[] {
+    const i = bound.indexOf('--sandbox');
+    if (i < 0 || bound[i + 1] === undefined) return [...bound];
+    return [...bound.slice(0, i), '-c', `sandbox_mode="${bound[i + 1]}"`, ...bound.slice(i + 2)];
+}