@event4u/agent-config 16.5.0 → 17.1.0

package/src/scripts/ai_council/self_hosted_probe.ts

@@ -0,0 +1,327 @@
+// egress-content: fixed-corpus — the only body sent is the fixed "Reply with OK." probe, and only to a loopback base_url
+/**
+ * The production `SelfHostedProbe`: what a loopback route must show before it
+ * may carry its declared ceiling. Both halves, or the answer stays unproven.
+ *
+ * 1. Local weights — the runtime names the file holding the model's weights
+ *    (Ollama `POST /api/show` modelfile `FROM`, llama-server `GET /props`
+ *    `model_path`, LM Studio `GET /api/v0/models` `path`), and that file exists
+ *    here with a size weights could have. A cloud model, or a path absent from
+ *    this machine, is `remote`; a runtime that names no path is `unknown`.
+ * 2. No outbound during one call — the PIDs listening on the route's port are
+ *    sampled with `lsof` while a one-line completion runs. Any ESTABLISHED
+ *    connection to a non-loopback address is outbound. Without `lsof`, a
+ *    listener, or a completed call, it is unmeasured (`null`).
+ *
+ * Limits a reader should not mistake for coverage: `outbound: false` is
+ * evidence, not proof. Sampling cannot see a connection opened and closed
+ * between two `lsof` rounds, and only the listening PIDs are watched — a child
+ * process the server spawns is not.
+ *
+ * A route that carries a resolvable `api_key_ref` sends the key as a header
+ * read from a file in a private temp directory, never on a command line.
+ * Results are memoised only when definite, and only for
+ * `SELF_HOSTED_PROBE_TTL_MS`, so a swapped proxy is re-probed.
+ *
+ * Kept out of `free_route.ts`, which sits in the hook bundle: only callers
+ * outside the bundle pass this probe. Every command goes through the injected
+ * runner and argument arrays; nothing here throws.
+ */
+
+import { spawn, spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { resolve_api_key } from './config.js';
+import type { RouteSpec, SelfHostedProbe, SelfHostedProbeResult } from './free_route.js';
+
+/** A route as the probe reads it; `api_key_ref` is optional and only read for the call. */
+export type ProbeRoute = RouteSpec & { readonly api_key_ref?: string | null };
+
+export interface ProbeRunResult {
+    readonly status: number;
+    readonly stdout: string;
+}
+
+export interface SelfHostedProbeDeps {
+    /** `null` when the command could not be executed at all (missing binary, timeout). */
+    run(cmd: string, args: readonly string[], timeoutMs: number): ProbeRunResult | null;
+    /** Start a command without waiting; its PID, or `null`. */
+    start(cmd: string, args: readonly string[]): number | null;
+    fileSize(path: string): number | null;
+    readText(path: string): string | null;
+    writeText(path: string, text: string): void;
+    /** Removes a file or a directory tree; never throws on absence. */
+    remove(path: string): void;
+    /** A freshly created, empty, owner-only directory. */
+    tmpDir(): string;
+    /** The key an `api_key_ref` names, or `null` when it does not resolve. */
+    resolveKey(ref: string): string | null;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly home: string;
+    now(): number;
+    sleep(ms: number): void;
+}
+
+const UNPROVEN: SelfHostedProbeResult = { weights: 'unknown', outbound: null };
+const MIN_WEIGHTS_BYTES = 50 * 1024 * 1024;
+const QUERY_TIMEOUT_S = 5;
+const CALL_TIMEOUT_S = 60;
+/** How long a definite probe answer is reused before the route is probed again. */
+export const SELF_HOSTED_PROBE_TTL_MS = 10 * 60 * 1000;
+
+type Weights = SelfHostedProbeResult['weights'];
+
+function _json(deps: SelfHostedProbeDeps, args: readonly string[]): Record<string, unknown> | null {
+    const r = deps.run('curl', ['-s', '-f', '--max-time', String(QUERY_TIMEOUT_S), ...args], (QUERY_TIMEOUT_S + 1) * 1000);
+    if (r === null || r.status !== 0 || r.stdout.trim() === '') return null;
+    try {
+        const v: unknown = JSON.parse(r.stdout);
+        return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+    } catch {
+        return null;
+    }
+}
+
+function _isCloudModel(model: string): boolean {
+    return /(?:^|[:\-])cloud$/i.test(model.trim());
+}
+
+function _weightsAt(deps: SelfHostedProbeDeps, file: string): Weights {
+    const size = deps.fileSize(file);
+    return size !== null && size > MIN_WEIGHTS_BYTES ? 'local' : 'remote';
+}
+
+function _expandHome(deps: SelfHostedProbeDeps, p: string): string {
+    return p.startsWith('~/') ? path.join(deps.home, p.slice(2)) : p;
+}
+
+function _ollamaModelsDir(deps: SelfHostedProbeDeps): string {
+    const override = (deps.env['OLLAMA_MODELS'] ?? '').trim();
+    return override !== '' ? _expandHome(deps, override) : path.join(deps.home, '.ollama', 'models');
+}
+
+function _ollamaWeights(deps: SelfHostedProbeDeps, origin: string, model: string): Weights | null {
+    const show = _json(deps, ['-X', 'POST', '-H', 'content-type: application/json', '-d', JSON.stringify({ model }), `${origin}/api/show`]);
+    if (show === null) return null;
+    if (show['remote_host'] !== undefined || show['remote_model'] !== undefined) return 'remote';
+    const modelfile = typeof show['modelfile'] === 'string' ? show['modelfile'] : '';
+    for (const line of modelfile.split('\n')) {
+        const m = /^FROM\s+(\S+)/.exec(line.trim());
+        if (m === null) continue;
+        const ref = m[1] as string;
+        const digest = /^sha256[:-]([0-9a-f]+)$/i.exec(ref);
+        if (digest !== null) return _weightsAt(deps, path.join(_ollamaModelsDir(deps), 'blobs', `sha256-${digest[1]}`));
+        if (ref.startsWith('/') || ref.startsWith('~/')) return _weightsAt(deps, _expandHome(deps, ref));
+    }
+    return 'unknown';
+}
+
+function _llamaServerWeights(deps: SelfHostedProbeDeps, origin: string): Weights | null {
+    const props = _json(deps, [`${origin}/props`]);
+    if (props === null) return null;
+    const p = props['model_path'];
+    return typeof p === 'string' && p !== '' ? _weightsAt(deps, _expandHome(deps, p)) : 'unknown';
+}
+
+function _lmStudioWeights(deps: SelfHostedProbeDeps, origin: string, model: string): Weights | null {
+    const list = _json(deps, [`${origin}/api/v0/models`]);
+    if (list === null) return null;
+    const data = Array.isArray(list['data']) ? (list['data'] as Record<string, unknown>[]) : [];
+    const entry = data.find((d) => d !== null && typeof d === 'object' && d['id'] === model);
+    const p = entry?.['path'];
+    if (typeof p !== 'string' || p === '') return 'unknown';
+    if (p.startsWith('/') || p.startsWith('~/')) return _weightsAt(deps, _expandHome(deps, p));
+    for (const dir of [path.join(deps.home, '.lmstudio', 'models'), path.join(deps.home, '.cache', 'lm-studio', 'models')]) {
+        if (_weightsAt(deps, path.join(dir, p)) === 'local') return 'local';
+    }
+    return 'remote';
+}
+
+function _weights(deps: SelfHostedProbeDeps, origin: string, model: string): Weights {
+    if (_isCloudModel(model)) return 'remote';
+    return _ollamaWeights(deps, origin, model) ?? _llamaServerWeights(deps, origin) ?? _lmStudioWeights(deps, origin, model) ?? 'unknown';
+}
+
+function _isLoopbackHost(host: string): boolean {
+    const h = host.replace(/^\[|\]$/g, '').toLowerCase();
+    if (h === '::1' || h === 'localhost') return true;
+    return /^(?:::ffff:)?127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+}
+
+/** The remote host of each `local->remote` pair in `lsof` NAME output. */
+function _remoteHosts(stdout: string): string[] {
+    const hosts: string[] = [];
+    for (const line of stdout.split('\n')) {
+        const m = /->(\S+)/.exec(line);
+        if (m === null) continue;
+        const remote = m[1] as string;
+        hosts.push(remote.startsWith('[') ? remote.slice(0, remote.indexOf(']') + 1) : remote.slice(0, remote.lastIndexOf(':')));
+    }
+    return hosts;
+}
+
+/** `true` on any non-loopback peer, `false` on none, `null` when lsof could not answer. */
+function _sample(deps: SelfHostedProbeDeps, pids: string): boolean | null {
+    const r = deps.run('lsof', ['-nP', '-a', '-p', pids, '-iTCP', '-sTCP:ESTABLISHED'], 5000);
+    if (r === null || (r.status !== 0 && r.stdout.trim() !== '') || r.status > 1) return null;
+    return _remoteHosts(r.stdout).some((h) => !_isLoopbackHost(h));
+}
+
+function _running(deps: SelfHostedProbeDeps, pid: number): boolean {
+    const r = deps.run('ps', ['-o', 'stat=', '-p', String(pid)], 2000);
+    if (r === null) return true;
+    const stat = r.stdout.trim();
+    return r.status === 0 && stat !== '' && !stat.startsWith('Z');
+}
+
+function _completed(text: string | null): boolean {
+    if (text === null || text.trim() === '') return false;
+    try {
+        const v = JSON.parse(text) as Record<string, unknown> | null;
+        return v !== null && Array.isArray(v['choices']) && v['choices'].length > 0;
+    } catch {
+        return false;
+    }
+}
+
+function _authHeaderArgs(deps: SelfHostedProbeDeps, route: ProbeRoute, dir: string): string[] {
+    const ref = route.api_key_ref;
+    if (typeof ref !== 'string' || ref === '') return [];
+    const key = deps.resolveKey(ref);
+    if (key === null || key === '') return [];
+    const file = path.join(dir, 'auth.header');
+    deps.writeText(file, `Authorization: Bearer ${key}\n`);
+    return ['-H', `@${file}`];
+}
+
+function _outbound(deps: SelfHostedProbeDeps, route: ProbeRoute, url: URL, model: string): boolean | null {
+    const port = url.port !== '' ? url.port : url.protocol === 'https:' ? '443' : '80';
+    const listen = deps.run('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], 5000);
+    if (listen === null) return null;
+    const pids = [...new Set(listen.stdout.split('\n').map((s) => s.trim()).filter((s) => /^\d+$/.test(s)))];
+    if (pids.length === 0) return null;
+    const pidList = pids.join(',');
+    let seen = _sample(deps, pidList);
+    if (seen === null) return null;
+    const dir = deps.tmpDir();
+    try {
+        const out = path.join(dir, 'out.json');
+        const body = JSON.stringify({ model, max_tokens: 8, messages: [{ role: 'user', content: 'Reply with OK.' }] });
+        const pid = deps.start('curl', [
+            '-s', '--max-time', String(CALL_TIMEOUT_S), '-o', out,
+            '-H', 'content-type: application/json', ..._authHeaderArgs(deps, route, dir),
+            '-d', body, `${route.base_url}/chat/completions`,
+        ]);
+        if (pid === null) return null;
+        const deadline = deps.now() + (CALL_TIMEOUT_S + 5) * 1000;
+        while (_running(deps, pid)) {
+            const s = _sample(deps, pidList);
+            if (s === null) return null;
+            seen = seen || s;
+            if (deps.now() > deadline) {
+                deps.run('kill', [String(pid)], 2000);
+                return null;
+            }
+            deps.sleep(50);
+        }
+        const last = _sample(deps, pidList);
+        if (last === null) return null;
+        seen = seen || last;
+        return _completed(deps.readText(out)) ? seen : null;
+    } finally {
+        deps.remove(dir);
+    }
+}
+
+export function makeSelfHostedProbe(deps: SelfHostedProbeDeps): SelfHostedProbe {
+    return (route, model) => {
+        if (!route.loopback || model === '') return UNPROVEN;
+        try {
+            const url = new URL(route.base_url);
+            const weights = _weights(deps, url.origin, model);
+            if (weights !== 'local') return { weights, outbound: null };
+            return { weights, outbound: _outbound(deps, route as ProbeRoute, url, model) };
+        } catch {
+            return UNPROVEN;
+        }
+    };
+}
+
+const _sleeper = new Int32Array(new SharedArrayBuffer(4));
+
+export const NODE_PROBE_DEPS: SelfHostedProbeDeps = {
+    run(cmd, args, timeoutMs) {
+        const r = spawnSync(cmd, args, { encoding: 'utf-8', timeout: timeoutMs, stdio: ['ignore', 'pipe', 'ignore'] });
+        if (r.error !== undefined || r.status === null) return null;
+        return { status: r.status, stdout: r.stdout ?? '' };
+    },
+    start(cmd, args) {
+        try {
+            const child = spawn(cmd, args, { stdio: 'ignore' });
+            child.on('error', () => undefined);
+            child.unref();
+            return child.pid ?? null;
+        } catch {
+            return null;
+        }
+    },
+    fileSize(p) {
+        try {
+            const st = fs.statSync(p);
+            return st.isFile() ? st.size : null;
+        } catch {
+            return null;
+        }
+    },
+    readText(p) {
+        try {
+            return fs.readFileSync(p, 'utf-8');
+        } catch {
+            return null;
+        }
+    },
+    writeText(p, text) {
+        fs.writeFileSync(p, text, { encoding: 'utf-8', mode: 0o600, flag: 'wx' });
+    },
+    remove(p) {
+        fs.rmSync(p, { force: true, recursive: true });
+    },
+    tmpDir: () => fs.mkdtempSync(path.join(os.tmpdir(), 'self-hosted-probe-')),
+    resolveKey(ref) {
+        try {
+            return resolve_api_key(ref);
+        } catch {
+            return null;
+        }
+    },
+    env: process.env,
+    home: os.homedir(),
+    now: () => Date.now(),
+    sleep: (ms) => {
+        Atomics.wait(_sleeper, 0, 0, ms);
+    },
+};
+
+/** A definite answer: remote weights, or local weights with outbound measured. */
+function _definite(r: SelfHostedProbeResult): boolean {
+    return r.weights === 'remote' || (r.weights === 'local' && r.outbound !== null);
+}
+
+/** Memoise definite answers per route and model for `ttlMs`; anything unmeasured is probed again. */
+export function makeMemoisedProbe(probe: SelfHostedProbe, now: () => number, ttlMs = SELF_HOSTED_PROBE_TTL_MS): SelfHostedProbe {
+    const memo = new Map<string, { readonly result: SelfHostedProbeResult; readonly until: number }>();
+    return (route, model) => {
+        const key = `${route.base_url}\0${model}`;
+        const hit = memo.get(key);
+        if (hit !== undefined && now() < hit.until) return hit.result;
+        memo.delete(key);
+        const result = probe(route, model);
+        if (_definite(result)) memo.set(key, { result, until: now() + ttlMs });
+        return result;
+    };
+}
+
+/** The production probe. */
+export const SELF_HOSTED_PROBE: SelfHostedProbe = makeMemoisedProbe(makeSelfHostedProbe(NODE_PROBE_DEPS), () => Date.now());

package/src/scripts/ai_council/shadow_dispatch.ts

@@ -18,7 +18,9 @@
 import * as fs from 'node:fs';
 
 import type { PyRandom } from '../_lib/py_random.js';
+import { parseTokens } from '../_lib/egress_token.js';
 import { redact } from './bundler.js';
+import { CouncilEgress } from './council_egress.js';
 import { createHash } from 'node:crypto';
 
 export const SHADOW_LOG_PATH = 'agents/runtime/council/shadow-log.jsonl';
@@ -67,8 +69,14 @@ const _defaultRandom: RandomLike = {
     },
 };
 
+// Shadow rows are this module's own record, not a council request: a scope of
+// their own keeps them out of the run's final-check state.
+function _redact(query: string): string {
+    return redact(query, new CouncilEgress());
+}
+
 function _hashQuery(query: string): string {
-    const redacted = redact(query);
+    const redacted = _redact(query);
     return createHash('sha256').update(Buffer.from(redacted, 'utf-8')).digest('hex').slice(0, 16);
 }
 
@@ -77,7 +85,9 @@ function _privacyDropped(redacted: string): boolean {
     if (!stripped) {
         return true;
     }
-    return stripped.startsWith('[redacted');
+    // Any replaced value drops the row: a placeholder in a shadow query means the
+    // query carried something the bundler would not send.
+    return parseTokens(redacted).length > 0;
 }
 
 export interface RecordShadowDecisionOptions {
@@ -106,7 +116,7 @@ export function record_shadow_decision(
     const escalated = opts.escalated ?? false;
     const escalationReason = opts.escalationReason ?? 'ok';
 
-    const redactedQ = redact(query);
+    const redactedQ = _redact(query);
     if (_privacyDropped(redactedQ)) {
         return null;
     }

package/src/scripts/ai_council/spend_gate.ts

@@ -58,7 +58,7 @@ export class OverrunEvent {
     projected_total_usd: number; // spent_usd + next_estimate.total_usd
     daily_spent_usd: number; // rolling 24h spend BEFORE this member (D3)
     daily_limit_usd: number; // the configured daily cap (0 = disabled)
-    breach_kind: string; // "session" | "daily" | "tokens"
+    breach_kind: string; // "session" | "daily" | "tokens" | "unpriced"
 
     constructor(args: {
         member_index: number;
@@ -91,12 +91,25 @@ export function _total_usd(e: CostEstimate): number {
     return e.input_usd + e.output_usd;
 }
 
-export type BreachKind = 'tokens' | 'daily' | 'session' | null;
+export type BreachKind = 'tokens' | 'unpriced' | 'daily' | 'session' | null;
+
+/** The error a refused seat carries. `unpriced` is named apart so the report says why. */
+export function breachErrorTag(kind: Exclude<BreachKind, null>): string {
+    if (kind === 'daily') return 'daily_budget_exceeded';
+    if (kind === 'unpriced') return 'cost_budget_unpriced';
+    return 'cost_budget_exceeded';
+}
 
 /**
  * The projected-spend verdict. One implementation because the round head and
  * the fallback's metered retry must gate on the SAME rules — two copies of
  * four comparisons is how they drift.
+ *
+ * Both callers reach it only for a BILLABLE seat (a non-billable one skips the
+ * gate in `orchestrator.ts`), which is what makes `unpriced` a refusal: under a
+ * USD ceiling a person set, an estimate with no price row is not $0, it is
+ * unknown, and a ceiling an unknown passes is not that ceiling (D2). With no
+ * USD ceiling set nothing here changes (ADR-279).
  */
 export function _breach(
     est: CostEstimate | null,
@@ -118,6 +131,9 @@ export function _breach(
     ) {
         return 'tokens';
     }
+    if (est && !est.priced && (budget.daily_limit_usd > 0 || budget.max_total_usd > 0)) {
+        return 'unpriced';
+    }
     if (budget.daily_limit_usd > 0 && _would_exceed_daily(budget.daily_limit_usd, usd)) {
         return 'daily';
     }

package/src/scripts/ai_council/status_surface.ts

@@ -16,7 +16,10 @@
 import type { EnvironmentReport } from '../_lib/environment_detector.js';
 import { detectEnvironment } from '../_lib/environment_detector.js';
 import { DEFAULT_SEAT_CEILING, type ContentClass } from './content_ceiling.js';
+import { resolve_api_key } from './config.js';
+import { resolveRouteTransport, type RouteSpec } from './free_route.js';
 import type { PolicyExclusion } from './seat_policy.js';
+import { SELF_HOSTED_PROBE } from './self_hosted_probe.js';
 import { resolveMemberTransport } from './transport_resolver.js';
 
 interface SeatLike {
@@ -24,6 +27,8 @@ interface SeatLike {
     readonly api_key_ref: string | null;
     readonly policy_exclusion?: PolicyExclusion | null;
     readonly content_ceiling?: ContentClass;
+    readonly route?: RouteSpec | null;
+    readonly model?: string;
 }
 
 interface ConfigLike {
@@ -46,6 +51,17 @@ export function resolvedTransportFor(
     report?: EnvironmentReport,
     contentClass?: ContentClass | null,
 ): ReturnType<typeof resolveMemberTransport> {
+    if (member.route !== undefined && member.route !== null) {
+        const resolved = resolveRouteTransport({
+            name,
+            route: member.route,
+            model: member.model ?? '',
+            contentClass: contentClass ?? null,
+            keyPresent: keyResolves(member.api_key_ref),
+            probe: SELF_HOSTED_PROBE,
+        });
+        return { ...resolved, configuredMode: 'api' };
+    }
     return resolveMemberTransport({
         provider: name,
         report: report ?? detectEnvironment(),
@@ -77,3 +93,26 @@ export function disabledSeats(cfg: ConfigLike | null): Record<string, string> {
     );
 }
 
+
+/** True when `ref` resolves to a non-empty key right now. */
+export function keyResolves(ref: string | null): boolean {
+    if (ref === null) return false;
+    try {
+        return resolve_api_key(ref) !== '';
+    } catch {
+        return false;
+    }
+}
+
+/** One `route` line per route member: where it points and how it bills. */
+export function routeStatusLines(
+    members: readonly (readonly [string, SeatLike])[],
+    report?: EnvironmentReport,
+): string[] {
+    return members
+        .filter(([, m]) => m.route !== undefined && m.route !== null)
+        .map(([n, m]) => {
+            const t = resolvedTransportFor(n, m, report, 'public-artifact');
+            return `  route            ${n}: ${m.route?.base_url ?? ''} · ${t.billing}`;
+        });
+}

package/src/scripts/ai_council/transport_resolver.ts

@@ -51,6 +51,7 @@ import {
 import { resolve_mode } from './modes.js';
 import {
     admitsContent,
+    DEFAULT_CONTENT_CLASS,
     DEFAULT_SEAT_CEILING,
     type ContentClass,
 } from './content_ceiling.js';
@@ -134,10 +135,7 @@ export interface ResolveTransportOptions {
     readonly policyExclusion?: PolicyExclusion | null;
     /** The seat's content ceiling (2.2). Defaults to `project-content`. */
     readonly seatCeiling?: ContentClass | null;
-    /**
-     * The class of what this pass would send. Omitted → no content check runs,
-     * which is what keeps every existing caller's behaviour identical.
-     */
+    /** The class of what this pass would send. Omitted → `project-content`. */
     readonly contentClass?: ContentClass | null;
 }
 
@@ -197,19 +195,17 @@ export function resolveTransport(opts: ResolveTransportOptions): ResolvedTranspo
     if (exclusion !== null) {
         return unavailable(provider, billing, policyExclusionReason(exclusion, provider), exclusion);
     }
-    // Content ceiling (2.2). Only runs when the caller declared what it would
-    // send; an undeclared pass is unchanged, not silently refused.
-    const contentClass = opts.contentClass ?? null;
-    if (contentClass !== null) {
-        const verdict = admitsContent(opts.seatCeiling ?? DEFAULT_SEAT_CEILING, contentClass);
-        if (!verdict.admitted) {
-            return unavailable(
-                provider,
-                billing,
-                `${provider}: ${verdict.reason ?? 'content ceiling refused the payload'}`,
-                'policy_content_ceiling',
-            );
-        }
+    // Content ceiling (2.2). An undeclared payload is project-content: a seat
+    // cleared only for public artefacts refuses it, and a default seat is unchanged.
+    const contentClass = opts.contentClass ?? DEFAULT_CONTENT_CLASS;
+    const verdict = admitsContent(opts.seatCeiling ?? DEFAULT_SEAT_CEILING, contentClass);
+    if (!verdict.admitted) {
+        return unavailable(
+            provider,
+            billing,
+            `${provider}: ${verdict.reason ?? 'content ceiling refused the payload'}`,
+            'policy_content_ceiling',
+        );
     }
 
     if (mode === 'manual') {
@@ -538,7 +534,8 @@ export function classifyCliFailure(raw: string): CliFailureClass {
     if (s === 'auth_expired' || s === 'auth_rejected' || s === 'unauthorized') {
         return 'auth_rejected';
     }
-    if (s === 'cli_unsupported' || s === 'unsupported' || s === 'parse_failed') {
+    // `parse_failed` is NOT here: answered-unreadably, so a replay pays twice.
+    if (s === 'cli_unsupported' || s === 'unsupported') {
         return 'cli_unsupported';
     }
     // Prefix match, not equality: the detail carries the operator-facing reason