@event4u/agent-config 16.5.0 → 17.1.0

package/src/scripts/ai_council/free_route.ts

@@ -0,0 +1,216 @@
+/**
+ * A council member reached over an OpenAI-compatible `base_url` — a route the
+ * package does not pay for by default.
+ *
+ * Kept out of `config.ts` and `clients.ts`, which both sit far past the source
+ * ceiling. Imports no client code: `config.ts` loads this and is itself in the
+ * hook bundle. The client is `free_route_client.ts`.
+ *
+ * The rules, each failing toward the metered or restricted side:
+ *
+ * - billing is `free-quota` only with a dated proof (keyless endpoint or a
+ *   documented free tier); without one the route is `per-token` and stays
+ *   inside the USD gate;
+ * - an HTTP 402 is `policy_unproven_cost` — the route asked for money, so its
+ *   free claim is void for the pass, and no other route is tried in its place;
+ * - every route sits at the `public-artifact` ceiling; only a loopback route
+ *   whose per-model probe shows local weights and no outbound connection may
+ *   carry its declared ceiling (`self-hosted`). Loopback alone proves nothing:
+ *   a local proxy forwards upstream;
+ * - identity is derived from the served id, and a route serving another model
+ *   than the one requested is absent with `policy_model_mismatch`;
+ * - random or auto routers are refused at config time: their family is unknown
+ *   until after the call.
+ */
+
+import { admitsContent, classifyContentClass, DEFAULT_CONTENT_CLASS, type ContentClass } from './content_ceiling.js';
+import type { BillingClass } from '../_lib/environment_detector.js';
+import type { ResolvedTransport } from './transport_resolver.js';
+
+export type RouteBilling = Extract<BillingClass, 'free-quota' | 'per-token' | 'self-hosted'>;
+
+export const BILLING_PROOF_KINDS = ['keyless', 'free-tier'] as const;
+export type BillingProofKind = (typeof BILLING_PROOF_KINDS)[number];
+
+export interface BillingProof {
+    readonly kind: BillingProofKind;
+    readonly url: string;
+    /** `YYYY-MM-DD` — the day someone read the documented free terms. */
+    readonly checked: string;
+}
+
+export interface RouteSpec {
+    readonly base_url: string;
+    readonly keyless: boolean;
+    readonly proof: BillingProof | null;
+    readonly loopback: boolean;
+    /** The configured ceiling; effective only for a probed self-hosted route. */
+    readonly declared_ceiling: ContentClass;
+}
+
+/** What a self-hosted probe observed for one model. */
+export interface SelfHostedProbeResult {
+    readonly weights: 'local' | 'remote' | 'unknown';
+    /** True when an outbound connection was seen during the probe call; null when unmeasured. */
+    readonly outbound: boolean | null;
+}
+
+export type SelfHostedProbe = (route: RouteSpec, model: string) => SelfHostedProbeResult;
+
+/** Nothing measured, nothing proven: the default, so production never raises a ceiling by omission. */
+export const UNPROVEN_PROBE: SelfHostedProbe = () => ({ weights: 'unknown', outbound: null });
+
+const _ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+export function isRealDate(s: unknown): s is string {
+    if (typeof s !== 'string' || !_ISO_DATE.test(s)) return false;
+    const [y, m, d] = s.split('-').map(Number) as [number, number, number];
+    const probe = new Date(Date.UTC(y, m - 1, d));
+    return probe.getUTCFullYear() === y && probe.getUTCMonth() + 1 === m && probe.getUTCDate() === d;
+}
+
+/** `localhost`, `127.0.0.0/8` and `::1`. A name that merely resolves locally does not count. */
+export function isLoopbackUrl(raw: string): boolean {
+    let host: string;
+    try {
+        host = new URL(raw).hostname.toLowerCase();
+    } catch {
+        return false;
+    }
+    if (host === 'localhost' || host === '[::1]' || host === '::1') return true;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+
+/** A model id that asks the route to pick for us (K2). */
+export function isRandomRouter(model: string): boolean {
+    return /^(?:.*\/)?(?:auto|random|free|router)(?::.*)?$/i.test(model.trim());
+}
+
+function _parseProof(name: string, raw: unknown, keyless: boolean): BillingProof | { error: string } | null {
+    if (raw === undefined || raw === null) return null;
+    const where = `members.${name}.billing_proof`;
+    if (typeof raw !== 'object' || Array.isArray(raw)) return { error: `${where} must be a mapping with kind, url and checked.` };
+    const p = raw as Record<string, unknown>;
+    if (!BILLING_PROOF_KINDS.includes(p['kind'] as BillingProofKind)) {
+        return { error: `${where}.kind must be one of ${BILLING_PROOF_KINDS.join(', ')}.` };
+    }
+    if (typeof p['url'] !== 'string' || !/^https:\/\/\S+$/.test(p['url'])) {
+        return { error: `${where}.url must be the https URL documenting the free terms.` };
+    }
+    // An unquoted YAML date is a Date object and may have rolled an impossible value over.
+    if (!isRealDate(p['checked'])) {
+        return { error: `${where}.checked must be a quoted 'YYYY-MM-DD' date — an undated proof proves nothing.` };
+    }
+    if (p['kind'] === 'keyless' && !keyless) {
+        return { error: `${where}.kind is 'keyless' but the member carries an api_key_ref.` };
+    }
+    return { kind: p['kind'] as BillingProofKind, url: p['url'], checked: p['checked'] };
+}
+
+/**
+ * The route half of a member's config. `{ route: null }` for a member without
+ * `base_url`; an error message (the loader raises it) for a malformed one.
+ */
+export function parseRouteFields(
+    name: string,
+    raw: Record<string, unknown>,
+    knownProvider: boolean,
+): { route: RouteSpec | null } | { error: string } {
+    const base = raw['base_url'];
+    if (base === undefined || base === null) {
+        return raw['billing_proof'] === undefined ? { route: null } : { error: `members.${name}.billing_proof needs base_url.` };
+    }
+    if (knownProvider) {
+        return { error: `members.${name}: base_url names a route, so the member needs its own name, not a provider's.` };
+    }
+    let url: URL;
+    try {
+        url = new URL(String(base));
+    } catch {
+        return { error: `members.${name}.base_url is not a URL (got ${JSON.stringify(base)}).` };
+    }
+    const loopback = isLoopbackUrl(url.href);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+        return { error: `members.${name}.base_url must use https unless it is a loopback address.` };
+    }
+    const model = raw['model'];
+    if (typeof model === 'string' && isRandomRouter(model)) {
+        return { error: `members.${name}.model ${JSON.stringify(model)} is a random/auto router; its identity is unknown before the call.` };
+    }
+    const ref = raw['api_key_ref'];
+    const keyless = ref === undefined || ref === null || ref === '';
+    const proof = _parseProof(name, raw['billing_proof'], keyless);
+    if (proof !== null && 'error' in proof) return proof;
+    return {
+        route: {
+            base_url: String(base).replace(/\/+$/, ''),
+            keyless,
+            proof,
+            loopback,
+            declared_ceiling: classifyContentClass(raw['content_ceiling']),
+        },
+    };
+}
+
+function _provenLocal(route: RouteSpec, probe: SelfHostedProbeResult): boolean {
+    return route.loopback && probe.weights === 'local' && probe.outbound === false;
+}
+
+export function routeBilling(route: RouteSpec, probe: SelfHostedProbeResult = UNPROVEN_PROBE(route, '')): RouteBilling {
+    if (_provenLocal(route, probe)) return 'self-hosted';
+    return route.proof === null ? 'per-token' : 'free-quota';
+}
+
+/** `public-artifact` for every route, except a proven self-hosted one. */
+export function routeCeiling(route: RouteSpec, probe: SelfHostedProbeResult = UNPROVEN_PROBE(route, '')): ContentClass {
+    return _provenLocal(route, probe) ? route.declared_ceiling : 'public-artifact';
+}
+
+export interface ResolveRouteOptions {
+    readonly name: string;
+    readonly route: RouteSpec;
+    readonly model: string;
+    readonly contentClass?: ContentClass | null;
+    /** Whether the member's `api_key_ref` resolves; ignored for a keyless route. */
+    readonly keyPresent?: boolean;
+    readonly probe?: SelfHostedProbe;
+}
+
+export function resolveRouteTransport(opts: ResolveRouteOptions): ResolvedTransport {
+    const result = (opts.probe ?? UNPROVEN_PROBE)(opts.route, opts.model);
+    const billing = routeBilling(opts.route, result);
+    const absent = (reason: string, absentReason: ResolvedTransport['absentReason']): ResolvedTransport => ({
+        available: false, transport: null, billing, authSource: null, makesProviderCall: false, reason, absentReason,
+    });
+    const verdict = admitsContent(routeCeiling(opts.route, result), opts.contentClass ?? DEFAULT_CONTENT_CLASS);
+    if (!verdict.admitted) {
+        return absent(`${opts.name}: ${verdict.reason ?? 'content ceiling refused the payload'}`, 'policy_content_ceiling');
+    }
+    if (!opts.route.keyless && opts.keyPresent !== true) {
+        return absent(`${opts.name}: the route's api_key_ref does not resolve`, 'no_auth');
+    }
+    return {
+        available: true,
+        transport: 'api',
+        billing,
+        authSource: opts.route.keyless ? null : 'env-key',
+        makesProviderCall: true,
+        reason: null,
+        absentReason: null,
+    };
+}
+
+/** The family a served id belongs to: the leading word of its last path segment. */
+export function familyOf(servedId: string): string {
+    const last = servedId.trim().split('/').pop() ?? '';
+    return (last.split(/[^a-zA-Z]+/).find((t) => t !== '') ?? '').toLowerCase();
+}
+
+/** Same model, allowing only a vendor prefix and a dated or variant suffix of the requested id. */
+export function servedMatches(requested: string, served: string): boolean {
+    const norm = (s: string): string => (s.trim().split('/').pop() ?? '').toLowerCase();
+    const r = norm(requested);
+    const s = norm(served);
+    if (r === '' || s === '') return false;
+    return s === r || (s.startsWith(`${r}-`) && familyOf(s) === familyOf(r));
+}

package/src/scripts/ai_council/free_route_catalog.ts

@@ -0,0 +1,310 @@
+// egress-content: fixed-corpus — a GET of the route's /models listing with no request body, never session content
+/**
+ * What the package ships about `base_url` routes: endpoints and dated data-use
+ * attestations, never model ids. Catalogues lose and gain rows within weeks,
+ * so a committed id is stale by the time it is read; the ids a route serves
+ * are discovered from its own `/models` and kept in gitignored runtime state.
+ *
+ * An attestation records what someone read in the route's terms on a date. It
+ * enforces nothing — every free route stays at the `public-artifact` ceiling
+ * whatever it says. It decides one thing: whether a route may be offered to
+ * consumers by default. A row without an attestation, or without the
+ * EEA/Switzerland/UK client-distribution field, is for the maintainer's own
+ * runs only: some free tiers require paid service once a client distributed
+ * to users in those regions exists.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { resolve_project_root } from '../_lib/agent_settings.js';
+import { isRealDate } from './free_route.js';
+
+export interface RouteAttestation {
+    /** `YYYY-MM-DD` the terms were read. */
+    readonly checked: string;
+    readonly source_url: string;
+    readonly trains_on_prompts: boolean;
+    /** What the terms say about keeping prompts and outputs, in their words' substance. */
+    readonly retention?: string;
+    /**
+     * Whether the terms permit use inside a client distributed to users in the
+     * EEA, Switzerland and the UK. `unknown` records that the terms were read
+     * and say neither, which keeps the route maintainer-only like an absent field.
+     */
+    readonly client_distribution_eea_ch_uk?: 'permitted' | 'forbidden' | 'unknown';
+}
+
+export interface CatalogRoute {
+    readonly id: string;
+    readonly base_url: string;
+    readonly keyless: boolean;
+    /** `null` until someone reads the terms and dates what they say. */
+    readonly attestation: RouteAttestation | null;
+    /**
+     * The route's own model list marking each entry `community: true|false`.
+     * When set, discovery admits only first-party ids and fails closed when the
+     * list cannot be read, because the attestation speaks for first-party
+     * models only.
+     */
+    readonly first_party_list?: string;
+}
+
+/**
+ * Base URLs only. One row carries an attestation (council 2026-10-22,
+ * decision 2): its terms were read from the provider's published policy, and
+ * they settle neither way whether a distributed client may serve EEA, CH or UK
+ * users, so it stays maintainer-only.
+ */
+export const ROUTE_CATALOG: readonly CatalogRoute[] = [
+    {
+        id: 'pollinations',
+        base_url: 'https://text.pollinations.ai/openai',
+        keyless: true,
+        first_party_list: 'https://text.pollinations.ai/models',
+        attestation: {
+            checked: '2026-10-22',
+            source_url: 'https://pollinations.ai/privacy',
+            trains_on_prompts: false,
+            retention:
+                'prompts and outputs processed transiently, with short-lived response caches; the selected model\'s inference host sets its own retention',
+            client_distribution_eea_ch_uk: 'unknown',
+        },
+    },
+    { id: 'groq', base_url: 'https://api.groq.com/openai/v1', keyless: false, attestation: null },
+    { id: 'cerebras', base_url: 'https://api.cerebras.ai/v1', keyless: false, attestation: null },
+    { id: 'openrouter', base_url: 'https://openrouter.ai/api/v1', keyless: false, attestation: null },
+    { id: 'huggingface', base_url: 'https://router.huggingface.co/v1', keyless: false, attestation: null },
+    { id: 'nvidia', base_url: 'https://integrate.api.nvidia.com/v1', keyless: false, attestation: null },
+];
+
+/** Terms drift; an attestation older than this no longer speaks for the route. */
+export const ATTESTATION_MAX_AGE_DAYS = 90;
+
+export interface ConsumerDefaultVerdict {
+    readonly admissible: boolean;
+    readonly reason: string;
+}
+
+export function consumerDefaultVerdict(route: CatalogRoute, now: Date = new Date()): ConsumerDefaultVerdict {
+    const a = route.attestation;
+    if (a === null) return { admissible: false, reason: `${route.id}: unattested — maintainer runs only` };
+    if (!isRealDate(a.checked)) return { admissible: false, reason: `${route.id}: attestation is undated — maintainer runs only` };
+    const ageDays = (now.getTime() - Date.parse(`${a.checked}T00:00:00Z`)) / 86_400_000;
+    if (ageDays > ATTESTATION_MAX_AGE_DAYS) {
+        return { admissible: false, reason: `${route.id}: attestation from ${a.checked} is older than ${ATTESTATION_MAX_AGE_DAYS} days` };
+    }
+    if (a.client_distribution_eea_ch_uk === undefined || a.client_distribution_eea_ch_uk === 'unknown') {
+        return { admissible: false, reason: `${route.id}: attestation records no EEA/CH/UK distribution term — maintainer runs only` };
+    }
+    if (a.client_distribution_eea_ch_uk === 'forbidden') {
+        return { admissible: false, reason: `${route.id}: terms forbid use in a client distributed to EEA/CH/UK users` };
+    }
+    return { admissible: true, reason: `${route.id}: attested ${a.checked}` };
+}
+
+export function consumerDefaultRoutes(now: Date = new Date()): CatalogRoute[] {
+    return ROUTE_CATALOG.filter((r) => consumerDefaultVerdict(r, now).admissible);
+}
+
+/** Runtime state beside `council-probes.json`; gitignored, never committed. */
+export const ROUTE_MODELS_RELPATH = path.join('agents', 'runtime', 'state', 'council-route-models.json');
+
+export type RouteRoster =
+    | { readonly status: 'known'; readonly models: readonly string[]; readonly observed_at: string }
+    | { readonly status: 'unknown'; readonly reason: string };
+
+interface StoredRoster {
+    readonly base_url: string;
+    readonly models: readonly string[];
+    readonly observed_at: string;
+}
+
+function _storePath(repoRoot: string): string {
+    return path.join(repoRoot, ROUTE_MODELS_RELPATH);
+}
+
+/** Corrupt or missing state reads as "nothing observed". */
+function _readStore(repoRoot: string): Record<string, StoredRoster> {
+    try {
+        const raw = JSON.parse(fs.readFileSync(_storePath(repoRoot), 'utf8')) as unknown;
+        return raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, StoredRoster>) : {};
+    } catch {
+        return {};
+    }
+}
+
+function _writeStore(repoRoot: string, store: Record<string, StoredRoster>): 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);
+}
+
+export function readRouteRoster(repoRoot: string, routeKey: string): RouteRoster {
+    const row = _readStore(repoRoot)[routeKey];
+    if (row === undefined || !Array.isArray(row.models)) return { status: 'unknown', reason: 'never discovered' };
+    return { status: 'known', models: row.models, observed_at: row.observed_at };
+}
+
+/**
+ * Drop one model from a route's discovered roster; the next discovery that
+ * serves it brings it back. False when the roster does not list it.
+ */
+export function retireRouteModel(repoRoot: string, routeKey: string, model: string): boolean {
+    const store = _readStore(repoRoot);
+    const row = store[routeKey];
+    if (row === undefined || !Array.isArray(row.models) || !row.models.includes(model)) return false;
+    store[routeKey] = { ...row, models: row.models.filter((m) => m !== model) };
+    _writeStore(repoRoot, store);
+    return true;
+}
+
+export interface DiscoverOptions {
+    readonly repoRoot: string;
+    readonly apiKey?: string | null;
+    readonly fetchImpl?: typeof fetch;
+    readonly now?: Date;
+    readonly timeoutMs?: number;
+    /** A route's `first_party_list`; when set, only ids it marks `community: false` are kept. */
+    readonly firstPartyListUrl?: string;
+}
+
+/** First-party names and aliases, each mapped to the full alias set of its entry. */
+async function firstPartyIds(url: string, opts: DiscoverOptions): Promise<Map<string, ReadonlySet<string>>> {
+    const res = await (opts.fetchImpl ?? fetch)(url, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
+    });
+    if (!res.ok) throw new Error(`first-party list HTTP ${res.status}`);
+    const body = (await res.json()) as unknown;
+    if (!Array.isArray(body)) throw new Error('first-party list is not a list');
+    const ids = new Map<string, ReadonlySet<string>>();
+    for (const m of body) {
+        if (m === null || typeof m !== 'object') continue;
+        const e = m as Record<string, unknown>;
+        if (e['community'] !== false) continue;
+        const names = [e['name'], ...(Array.isArray(e['aliases']) ? e['aliases'] : [])].filter((n): n is string => typeof n === 'string');
+        const entry = new Set(names);
+        for (const n of names) ids.set(n, entry);
+    }
+    return ids;
+}
+
+/**
+ * The id a route answers under when asked for `model`, from one minimal call; '' when the call
+ * gives no answer. A route may list one id and serve under another, and the client keeps an
+ * answer only on an exact match, so the roster must hold the id the route actually serves.
+ */
+async function servedIdOf(baseUrl: string, model: string, opts: DiscoverOptions): Promise<string> {
+    try {
+        const headers: Record<string, string> = { 'content-type': 'application/json', accept: 'application/json' };
+        if (opts.apiKey) headers['authorization'] = `Bearer ${opts.apiKey}`;
+        const res = await (opts.fetchImpl ?? fetch)(`${baseUrl.replace(/\/+$/, '')}/chat/completions`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ model, max_tokens: 16, messages: [{ role: 'user', content: 'Reply with: ok' }] }),
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
+        });
+        if (!res.ok) return '';
+        const served = ((await res.json()) as { model?: unknown }).model;
+        return typeof served === 'string' ? served : '';
+    } catch {
+        return '';
+    }
+}
+
+/**
+ * One GET of `<base_url>/models`. A failure clears the stored entry, so an
+ * offline route reads `unknown` rather than the list it served last time.
+ */
+export async function discoverRouteModels(routeKey: string, baseUrl: string, opts: DiscoverOptions): Promise<RouteRoster> {
+    const store = _readStore(opts.repoRoot);
+    let models: string[];
+    try {
+        const headers: Record<string, string> = { accept: 'application/json' };
+        if (opts.apiKey) headers['authorization'] = `Bearer ${opts.apiKey}`;
+        const res = await (opts.fetchImpl ?? fetch)(`${baseUrl.replace(/\/+$/, '')}/models`, {
+            headers,
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
+        });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const body = (await res.json()) as { data?: unknown };
+        if (!Array.isArray(body.data)) throw new Error('no data array in the /models answer');
+        models = body.data
+            .map((m) => (m !== null && typeof m === 'object' ? (m as Record<string, unknown>)['id'] : undefined))
+            .filter((id): id is string => typeof id === 'string' && id !== '');
+        if (opts.firstPartyListUrl) {
+            const fp = await firstPartyIds(opts.firstPartyListUrl, opts);
+            const resolved: string[] = [];
+            for (const id of models.filter((m) => fp.has(m))) {
+                const aliases = fp.get(id) as ReadonlySet<string>;
+                const served = aliases.size > 1 ? await servedIdOf(baseUrl, id, opts) : '';
+                // No answer keeps the listed id; an id outside the entry's declared aliases is a substitution.
+                if (served === '' || served === id) resolved.push(id);
+                else if (aliases.has(served)) resolved.push(served);
+            }
+            models = [...new Set(resolved)];
+        }
+    } catch (exc) {
+        if (routeKey in store) {
+            delete store[routeKey];
+            _writeStore(opts.repoRoot, store);
+        }
+        return { status: 'unknown', reason: exc instanceof Error ? exc.message : String(exc) };
+    }
+    const observed_at = (opts.now ?? new Date()).toISOString();
+    store[routeKey] = { base_url: baseUrl, models, observed_at };
+    _writeStore(opts.repoRoot, store);
+    return { status: 'known', models, observed_at };
+}
+
+export interface CatalogMainDeps {
+    readonly fetchImpl?: typeof fetch;
+    readonly stdout?: (line: string) => void;
+    readonly now?: Date;
+}
+
+const USAGE = 'usage: free_route_catalog discover [--root <dir>]';
+
+/**
+ * `discover [--root <dir>]` — the production path that writes the first-party
+ * roster `route_member.ts` gates on. Every catalogued row with a
+ * `first_party_list` is discovered under its catalogue id, beneath the same
+ * repository root the gate resolves. Exit 1 when any roster stays unknown.
+ */
+export async function main(argv: readonly string[], deps: CatalogMainDeps = {}): Promise<number> {
+    const out = deps.stdout ?? ((line: string) => process.stdout.write(`${line}\n`));
+    const [cmd, ...rest] = argv;
+    const rootAt = rest.indexOf('--root');
+    const rootArg = rootAt === -1 ? null : (rest[rootAt + 1] ?? '');
+    if (cmd !== 'discover' || rootArg === '' || rest.length !== (rootAt === -1 ? 0 : 2)) {
+        out(USAGE);
+        return 2;
+    }
+    const [repoRoot] = resolve_project_root(rootArg);
+    let unknown = 0;
+    for (const row of ROUTE_CATALOG) {
+        if (row.first_party_list === undefined) continue;
+        const roster = await discoverRouteModels(row.id, row.base_url, {
+            repoRoot,
+            firstPartyListUrl: row.first_party_list,
+            ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
+            ...(deps.now ? { now: deps.now } : {}),
+        });
+        if (roster.status === 'known') {
+            out(`${row.id}: known (${roster.models.length} first-party models, observed ${roster.observed_at})`);
+        } else {
+            unknown += 1;
+            out(`${row.id}: unknown (${roster.reason})`);
+        }
+    }
+    out(`roster: ${path.join(repoRoot, ROUTE_MODELS_RELPATH)}`);
+    return unknown === 0 ? 0 : 1;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    void main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/src/scripts/ai_council/free_route_client.ts

@@ -0,0 +1,99 @@
+/**
+ * The `chat/completions` client for a `base_url` route. Separate from
+ * `free_route.ts` so the config loader, which sits in the hook bundle, does not
+ * pull the client layer in.
+ */
+
+import { curlJsonPost, type JsonPost } from './api_transport.js';
+import { CouncilResponse, ExternalAIClient } from './clients.js';
+import type { ContentClass } from './content_ceiling.js';
+import { familyOf, servedMatches, type RouteBilling } from './free_route.js';
+import { policyExclusionReason, type PolicyExclusion } from './seat_policy.js';
+
+export interface FreeRouteClientOptions {
+    readonly name: string;
+    readonly model: string;
+    readonly base_url: string;
+    readonly api_key: string | null;
+    readonly billing: RouteBilling;
+    readonly content_ceiling: ContentClass;
+    readonly post?: JsonPost;
+}
+
+/**
+ * `chat/completions` against a route. Distinct from `_OpenAICompatibleClient`
+ * because a keyless route must send no Authorization header at all, and
+ * because its answer is only kept when the served model is the requested one.
+ * Paid provider clients keep `model_served` as attribution only.
+ */
+export class FreeRouteClient extends ExternalAIClient {
+    readonly base_url: string;
+    readonly billing: RouteBilling;
+    readonly content_ceiling: ContentClass;
+    private readonly _apiKey: string | null;
+    private readonly _post: JsonPost;
+
+    constructor(opts: FreeRouteClientOptions) {
+        super();
+        this.name = opts.name;
+        this.model = opts.model;
+        this.base_url = opts.base_url.replace(/\/+$/, '');
+        this.billing = opts.billing;
+        this.content_ceiling = opts.content_ceiling;
+        this.billable = opts.billing === 'per-token';
+        this._apiKey = opts.api_key;
+        this._post = opts.post ?? curlJsonPost;
+    }
+
+    private _refused(exclusion: PolicyExclusion, detail: string, latency_ms: number, served = ''): CouncilResponse {
+        return new CouncilResponse({
+            provider: this.name,
+            model: this.model,
+            model_served: served,
+            text: '',
+            latency_ms,
+            error: `${exclusion}: ${policyExclusionReason(exclusion, this.name)} — ${detail}`,
+            metadata: { absent_reason: exclusion, billing: this.billing, route: this.base_url },
+        });
+    }
+
+    override ask(system_prompt: string, user_prompt: string, max_tokens = 2048): CouncilResponse {
+        const t0 = performance.now();
+        const headers = this._apiKey === null ? [] : [`authorization: Bearer ${this._apiKey}`];
+        let response: Record<string, unknown>;
+        try {
+            response = (this._post(`${this.base_url}/chat/completions`, headers, {
+                model: this.model,
+                max_tokens,
+                messages: [
+                    { role: 'system', content: system_prompt },
+                    { role: 'user', content: user_prompt },
+                ],
+            }) ?? {}) as Record<string, unknown>;
+        } catch (exc) {
+            const msg = exc instanceof Error ? exc.message : String(exc);
+            const ms = Math.trunc(performance.now() - t0);
+            if (/^HTTP 402\b/.test(msg)) return this._refused('policy_unproven_cost', 'the route answered 402; no paid fallback is tried', ms);
+            return new CouncilResponse({ provider: this.name, model: this.model, text: '', latency_ms: ms, error: msg });
+        }
+        const ms = Math.trunc(performance.now() - t0);
+        const served = typeof response['model'] === 'string' ? response['model'] : '';
+        if (!servedMatches(this.model, served)) {
+            return this._refused('policy_model_mismatch', `requested ${this.model}, served ${served || '(none reported)'}`, ms, served);
+        }
+        const choices = Array.isArray(response['choices']) ? (response['choices'] as Record<string, unknown>[]) : [];
+        const message = (choices[0]?.['message'] ?? {}) as Record<string, unknown>;
+        const usage = (response['usage'] ?? {}) as Record<string, unknown>;
+        const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+        return new CouncilResponse({
+            provider: this.name,
+            model: this.model,
+            model_served: served,
+            text: typeof message['content'] === 'string' ? message['content'] : '',
+            input_tokens: num(usage['prompt_tokens']),
+            output_tokens: num(usage['completion_tokens']),
+            latency_ms: ms,
+            metadata: { family: familyOf(served), billing: this.billing, route: this.base_url, billable: this.billable },
+        });
+    }
+}