@event4u/agent-config 14.19.0 → 14.21.0

package/src/scripts/ai_council/jury_aggregate.ts

@@ -0,0 +1,178 @@
+/**
+ * Jury aggregation — road-to-admissible-council-seats 3.2.
+ *
+ * BESIDE `consensus.ts`, not inside it, and the separation is the design.
+ * `consensus.ts` aggregates a COUNCIL, whose members carry verdicts.
+ * A jury does not: per ADR-257 a route this package did not pay for may propose
+ * and may score, never decide. Folding jury scoring into the consensus path
+ * would put a scorer on the code path that produces verdicts, which is the
+ * exact transition this roadmap's Risk 5 names — "scoring quietly becomes
+ * deciding".
+ *
+ * Two rules, and both are refusals.
+ *
+ * 1. **At least two model families, or the panel is ABSENT.** Not a warning, a
+ *    refusal: `docs/CLAIMS.md` records that a same-posture second vendor's
+ *    catches were a strict SUBSET of the first's. A same-family panel therefore
+ *    measures redundancy, and reporting redundancy as agreement is the failure
+ *    a diversity requirement exists to prevent.
+ * 2. **The aggregate is a trimmed statistic, never a vote count.** For the same
+ *    reason: counting agreeing voices rewards a panel for being correlated.
+ *
+ * What "trimmed" means here, exactly: with n >= 3 the single lowest and single highest score are dropped and the
+ * rest averaged — which at n = 3 IS the median, and is why one corrupted score
+ * in a three-judge panel cannot move the result the way it moves an arithmetic
+ * mean. With n = 2 there is nothing to trim; the mean is returned with
+ * `trimmed: 0` so a reader can see that no robustness was available rather than
+ * inferring it from a method name.
+ */
+
+import {
+    judgeBothOrders,
+    positionConsistency,
+    type JudgeConsistency,
+    type PairResolution,
+    type PairwiseJudge,
+    type SwapObservation,
+} from './judge_position_bias.js';
+
+/** One judge's score for one item. `family` is the MODEL family, not the seat. */
+export interface JuryScore {
+    readonly judge: string;
+    readonly family: string;
+    /** Any finite number. The aggregator does not impose a scale. */
+    readonly score: number;
+}
+
+/** Why a panel produced no aggregate. Each value is a REFUSAL, not an error. */
+export type JuryAbsentReason = 'no_scores' | 'single_family' | 'non_finite_score';
+
+export type JuryResult =
+    | {
+          readonly present: false;
+          readonly absentReason: JuryAbsentReason;
+          readonly reason: string;
+      }
+    | {
+          readonly present: true;
+          readonly aggregate: number;
+          readonly method: 'trimmed-mean';
+          /** How many scores the trim discarded. 0 when n < 3. */
+          readonly trimmed: number;
+          readonly judges: number;
+          readonly families: readonly string[];
+      };
+
+/**
+ * Aggregate one item's jury scores.
+ *
+ * Never throws on panel composition: a refused panel is a VERDICT the caller
+ * reads, the same shape the transport resolver uses for a refused seat. An
+ * exception would make "this panel does not qualify" indistinguishable from a
+ * bug at every call site.
+ */
+export function juryAggregate(scores: readonly JuryScore[]): JuryResult {
+    if (scores.length === 0) {
+        return { present: false, absentReason: 'no_scores', reason: 'no jury scores supplied' };
+    }
+    for (const s of scores) {
+        if (!Number.isFinite(s.score)) {
+            return {
+                present: false,
+                absentReason: 'non_finite_score',
+                reason: `judge ${s.judge} returned a non-finite score; the panel is refused rather than silently dropping it`,
+            };
+        }
+    }
+    const families = [...new Set(scores.map((s) => s.family))].sort();
+    if (families.length < 2) {
+        return {
+            present: false,
+            absentReason: 'single_family',
+            reason:
+                `panel spans ${families.length} model family (${families.join(', ') || 'none'}); ` +
+                'at least two are required — a same-family panel measures redundancy, not agreement',
+        };
+    }
+    const sorted = [...scores.map((s) => s.score)].sort((a, b) => a - b);
+    const trimmed = sorted.length >= 3 ? 2 : 0;
+    const kept = trimmed === 0 ? sorted : sorted.slice(1, sorted.length - 1);
+    const aggregate = kept.reduce((acc, v) => acc + v, 0) / kept.length;
+    return {
+        present: true,
+        aggregate,
+        method: 'trimmed-mean',
+        trimmed,
+        judges: scores.length,
+        families,
+    };
+}
+
+/** One judge's swapped observation plus the family it belongs to. */
+export interface JuryPairwiseJudge {
+    readonly judge: string;
+    readonly family: string;
+    readonly fn: PairwiseJudge;
+}
+
+export interface JuryPairwiseResult {
+    readonly present: boolean;
+    readonly absentReason: JuryAbsentReason | null;
+    readonly reason: string | null;
+    /** Panel resolution, or `null` when the panel is absent. */
+    readonly resolution: PairResolution | null;
+    readonly observations: readonly SwapObservation[];
+    readonly consistency: readonly JudgeConsistency[];
+}
+
+/**
+ * Run a pairwise jury with the position swap applied PER JUDGE.
+ *
+ * Reuses `judge_position_bias.ts` rather than re-implementing the swap: a
+ * second implementation of "show both orders and reconcile" is a second place
+ * for the reconciliation to be subtly wrong, and that module already resolves a
+ * verdict that does not survive the swap to `inconsistent` rather than to a
+ * winner.
+ *
+ * The panel resolution is the strict majority of the judges' own resolutions,
+ * and `inconsistent` judges are counted in the DENOMINATOR — a judge that
+ * flipped has an opinion about nothing, and dropping it from the denominator
+ * would let two stable judges out of five look unanimous.
+ */
+export function juryPairwise(
+    id: string,
+    a: string,
+    b: string,
+    judges: readonly JuryPairwiseJudge[],
+): JuryPairwiseResult {
+    const families = [...new Set(judges.map((j) => j.family))].sort();
+    if (judges.length === 0 || families.length < 2) {
+        return {
+            present: false,
+            absentReason: judges.length === 0 ? 'no_scores' : 'single_family',
+            reason:
+                judges.length === 0
+                    ? 'no judges supplied'
+                    : `panel spans ${families.length} model family; at least two are required`,
+            resolution: null,
+            observations: [],
+            consistency: [],
+        };
+    }
+    const observations: SwapObservation[] = [];
+    const consistency: JudgeConsistency[] = [];
+    const tally = new Map<PairResolution, number>();
+    for (const j of judges) {
+        const obs = judgeBothOrders(id, a, b, j.fn);
+        observations.push(obs);
+        consistency.push(positionConsistency(j.judge, [obs]));
+        tally.set(obs.resolution, (tally.get(obs.resolution) ?? 0) + 1);
+    }
+    let resolution: PairResolution = 'inconsistent';
+    for (const [k, v] of tally) {
+        if (v * 2 > judges.length) {
+            resolution = k;
+        }
+    }
+    return { present: true, absentReason: null, reason: null, resolution, observations, consistency };
+}

package/src/scripts/ai_council/seat_policy.ts

@@ -0,0 +1,137 @@
+import {
+    classifyContentClass as _classifyContentClass,
+    DEFAULT_SEAT_CEILING as _DEFAULT_SEAT_CEILING,
+    type ContentClass,
+} from './content_ceiling.js';
+
+/**
+ * Seat policy — the vocabulary for refusing a route that IS reachable.
+ *
+ * road-to-admissible-council-seats 2.1. `AbsentReason` was exactly four values
+ * — `no_binary | no_auth | timeout | quota` — and every one of them means "the
+ * route is not reachable". A route that is reachable and **must not be used**
+ * had no name at all, so the resolver could not fail closed on terms, privacy,
+ * unproven cost, or a served model that is not the requested one. The absence
+ * of a word was the absence of the refusal: `resolveTransport`'s `api`/`cli`
+ * branches return `available: true` unconditionally, so anything the four
+ * reachability reasons could not express resolved OPEN.
+ *
+ * Fail closed on the unknown, which is the whole point.
+ * `classifyPolicyExclusion` maps anything it does not recognise to
+ * `policy_unknown`, and `policy_unknown` is an ABSENT reason like every other
+ * member of this union. An unrecognised policy token is the case where the
+ * config is trying to say something the code cannot understand; resolving it
+ * to "available" would make a typo an authorisation. This is the roadmap's own
+ * Risk 3 — "a new refusal vocabulary defaults open instead of closed".
+ *
+ * What this is NOT. It is not a secrets floor. Redaction (`skills/ai-council/references/
+ * cost-and-redaction.md`) still runs underneath and is not replaced. It is not
+ * an authorisation either: nothing here ever makes a seat available that was
+ * not already available — every value in the union only ever subtracts.
+ */
+
+/** Reachable-but-refused reasons. Every value means ABSENT. */
+export const POLICY_EXCLUSIONS = [
+    /** The provider's terms forbid this use of the route. */
+    'policy_terms',
+    /** A privacy constraint forbids sending to this route. */
+    'policy_privacy',
+    /** The route's cost property is asserted rather than proven. */
+    'policy_unproven_cost',
+    /** The route serves a model other than the one requested. */
+    'policy_model_mismatch',
+    /** 2.2 — the payload's content class exceeds the seat's ceiling. */
+    'policy_content_ceiling',
+    /** The config named an exclusion this build does not understand. */
+    'policy_unknown',
+] as const;
+
+export type PolicyExclusion = (typeof POLICY_EXCLUSIONS)[number];
+
+const _SET: ReadonlySet<string> = new Set<string>(POLICY_EXCLUSIONS);
+
+/** True for a value this build can act on. `policy_unknown` included: it is a
+ *  real, actionable verdict (refuse), not a parse failure. */
+export function isPolicyExclusion(v: unknown): v is PolicyExclusion {
+    return typeof v === 'string' && _SET.has(v);
+}
+
+/**
+ * Any configured value → a verdict. Unrecognised input, including `null` used
+ * where a string was meant, becomes `policy_unknown` — never `null`, because a
+ * `null` return would put the caller back in the position of deciding what an
+ * unreadable policy means, which is where the open default came from.
+ *
+ * `undefined` and `null` are the two ways of saying "no exclusion configured"
+ * and are the ONLY inputs that return `null`. Everything else is a refusal.
+ */
+export function classifyPolicyExclusion(raw: unknown): PolicyExclusion | null {
+    if (raw === undefined || raw === null) {
+        return null;
+    }
+    return isPolicyExclusion(raw) ? raw : 'policy_unknown';
+}
+
+/** One-line human reason for a refusal. `council:status` prints this. */
+export function policyExclusionReason(p: PolicyExclusion, provider?: string): string {
+    const who = provider === undefined ? 'this seat' : provider;
+    switch (p) {
+        case 'policy_terms':
+            return `${who} is excluded by policy: the route's terms forbid this use`;
+        case 'policy_privacy':
+            return `${who} is excluded by policy: a privacy constraint forbids this route`;
+        case 'policy_unproven_cost':
+            return `${who} is excluded by policy: the route's cost property is asserted, not proven`;
+        case 'policy_model_mismatch':
+            return `${who} is excluded by policy: the route serves a model other than the one requested`;
+        case 'policy_content_ceiling':
+            return `${who} is excluded by policy: the payload exceeds the seat's content ceiling`;
+        case 'policy_unknown':
+            return `${who} is excluded by policy: an exclusion this build does not understand (failing closed)`;
+    }
+}
+
+/**
+ * Parsed together because they are one question — "what may this seat do, and
+ * if it may do nothing, why" — and because `config.ts` sits ~670 lines past
+ * the 1,500-line source ceiling, where every line costs one excess line.
+ *
+ * Returns an error MESSAGE rather than throwing so `config.ts` keeps raising
+ * its own `CouncilConfigError` (which its callers catch by type) without this
+ * module importing it and creating a cycle back into the loader.
+ */
+export interface SeatFields {
+    readonly disabled_reason: string | null;
+    readonly policy_exclusion: PolicyExclusion | null;
+    readonly content_ceiling: ContentClass;
+}
+
+export function parseSeatFields(
+    name: string,
+    raw: Record<string, unknown>,
+): { fields: SeatFields } | { error: string } {
+    const dr = raw['disabled_reason'];
+    let disabled_reason: string | null = null;
+    if (dr !== undefined && dr !== null) {
+        if (typeof dr !== 'string' || dr.trim() === '') {
+            return {
+                error:
+                    `members.${name}.disabled_reason must be a non-empty string when set ` +
+                    `(got ${JSON.stringify(dr)}).`,
+            };
+        }
+        disabled_reason = dr.trim();
+    }
+    // Both of the next two fail CLOSED on an unreadable value: an unknown
+    // exclusion token becomes `policy_unknown` (which resolves ABSENT) and an
+    // unknown ceiling falls back to the RESTRICTIVE one. Throwing instead would
+    // be defensible, but a config typo would then take the whole council down
+    // rather than the one seat it names.
+    return {
+        fields: {
+            disabled_reason,
+            policy_exclusion: classifyPolicyExclusion(raw['policy_exclusion']),
+            content_ceiling: _classifyContentClass(raw['content_ceiling'], _DEFAULT_SEAT_CEILING),
+        },
+    };
+}

package/src/scripts/ai_council/status_surface.ts

@@ -0,0 +1,79 @@
+/**
+ * The seat-status helpers `council:status` renders from.
+ *
+ * Extracted from `council_cli.ts` (road-to-admissible-council-seats 1.2/2.1):
+ * that file sits ~2,460 lines past the 1,500-line ceiling
+ * `check_source_size_budget` ratchets, so every line added there costs one
+ * excess line. These three surfaces are what 1.2 and 2.1 grew, and they are a
+ * coherent unit — "what does this package know about a seat before any call is
+ * made" — rather than an arbitrary slice taken to satisfy a gate.
+ *
+ * Nothing here authorizes anything. `disabledSeats` reports a note the config
+ * carries; `resolvedTransportFor` only ever forwards a REFUSAL input to the
+ * resolver.
+ */
+
+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 type { PolicyExclusion } from './seat_policy.js';
+import { resolveMemberTransport } from './transport_resolver.js';
+
+interface SeatLike {
+    readonly binary: string | null;
+    readonly api_key_ref: string | null;
+    readonly policy_exclusion?: PolicyExclusion | null;
+    readonly content_ceiling?: ContentClass;
+}
+
+interface ConfigLike {
+    readonly members: ReadonlyMap<string, { readonly enabled: boolean; readonly disabled_reason: string | null }>;
+}
+
+/**
+ * Resolve the concrete transport a member would use on THIS machine right now.
+ *
+ * `cmd_status` exists to answer "is the council reachable, and will it bill me".
+ * Since the transport-mode setting was removed, the second half is not a value
+ * anyone can look up in the config — it is a per-machine resolution. Printing a
+ * configured mode would be the same class of stale answer the removed setting
+ * produced. `mode` is pinned to `auto` because the loader no longer emits
+ * anything else.
+ */
+export function resolvedTransportFor(
+    name: string,
+    member: SeatLike,
+    report?: EnvironmentReport,
+    contentClass?: ContentClass | null,
+): ReturnType<typeof resolveMemberTransport> {
+    return resolveMemberTransport({
+        provider: name,
+        report: report ?? detectEnvironment(),
+        invocationMode: null,
+        memberSettings: null,
+        globalMode: 'auto',
+        binaryOverride: member.binary,
+        policyExclusion: member.policy_exclusion ?? null,
+        seatCeiling: member.content_ceiling ?? DEFAULT_SEAT_CEILING,
+        contentClass: contentClass ?? null,
+    });
+}
+
+/**
+ * Disabled seats and the reason each records. `NO_DISABLED_REASON` is the
+ * honest rendering of an unset field: an `enabled: false` with nothing beside
+ * it is a fact about the config, and hiding it is what made the seat silent.
+ */
+export const NO_DISABLED_REASON = 'disabled, no reason recorded';
+
+export function disabledSeats(cfg: ConfigLike | null): Record<string, string> {
+    if (cfg === null) {
+        return {};
+    }
+    return Object.fromEntries(
+        [...cfg.members.entries()]
+            .filter(([, m]) => !m.enabled)
+            .map(([n, m]) => [n, m.disabled_reason ?? NO_DISABLED_REASON]),
+    );
+}
+

package/src/scripts/ai_council/transport_resolver.ts

@@ -49,6 +49,12 @@ import {
     type EnvironmentReport,
 } from '../_lib/environment_detector.js';
 import { resolve_mode } from './modes.js';
+import {
+    admitsContent,
+    DEFAULT_SEAT_CEILING,
+    type ContentClass,
+} from './content_ceiling.js';
+import { policyExclusionReason, type PolicyExclusion } from './seat_policy.js';
 
 /** A concrete transport a member can actually run on. `auto` is not one. */
 export type Transport = 'api' | 'manual' | 'cli';
@@ -62,7 +68,17 @@ export type Transport = 'api' | 'manual' | 'cli';
  * `absentReasonFromCliFailure` below for the mapping FROM the mid-flight
  * `CliFailureClass` a caller already classifies its errors into.
  */
-export type AbsentReason = 'no_binary' | 'no_auth' | 'timeout' | 'quota';
+/** The four REACHABILITY reasons. Each means "the route cannot be run". */
+export type UnreachableReason = 'no_binary' | 'no_auth' | 'timeout' | 'quota';
+
+/**
+ * Reachability OR policy. The policy half (2.1) names the case the four
+ * original values could not: a route that IS reachable and must not be used.
+ * Both halves mean the same thing to a caller — the member is absent — which
+ * is why they share one union rather than sitting in two fields a caller could
+ * forget to check.
+ */
+export type AbsentReason = UnreachableReason | PolicyExclusion;
 
 /** The accepted values of the `mode` key, including the resolver-only `auto`. */
 export const VALID_TRANSPORT_MODES: ReadonlySet<string> = new Set([
@@ -110,6 +126,19 @@ export interface ResolveTransportOptions {
      * env-key auth record exists for this provider" from the report.
      */
     readonly apiKeyPresent?: boolean;
+    /**
+     * A configured policy exclusion for this seat (2.1). Non-null resolves
+     * ABSENT whatever the mode says — a reachable route that must not be used
+     * is not made usable by being reachable.
+     */
+    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.
+     */
+    readonly contentClass?: ContentClass | null;
 }
 
 /** Auth sources that mean "the provider CLI can authenticate". */
@@ -161,6 +190,28 @@ export function resolveTransport(opts: ResolveTransportOptions): ResolvedTranspo
     const authSource = auth?.source ?? null;
     const billing = classifyBilling(provider, authSource);
 
+    // Policy first (2.1). Before the mode dispatch, because `api` and `cli`
+    // below return `available: true` UNCONDITIONALLY — a refusal placed after
+    // them would be unreachable for exactly the seats it exists to stop.
+    const exclusion = opts.policyExclusion ?? null;
+    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',
+            );
+        }
+    }
+
     if (mode === 'manual') {
         return {
             available: true,
@@ -246,6 +297,10 @@ export interface ResolveMemberTransportOptions {
     readonly globalMode?: string | null;
     readonly binaryOverride?: string | null;
     readonly apiKeyPresent?: boolean;
+    /** Forwarded to `resolveTransport` (2.1 / 2.2). */
+    readonly policyExclusion?: PolicyExclusion | null;
+    readonly seatCeiling?: ContentClass | null;
+    readonly contentClass?: ContentClass | null;
 }
 
 export interface ResolvedMemberTransport extends ResolvedTransport {
@@ -287,6 +342,9 @@ export function resolveMemberTransport(
         // optional-boolean field, so the key is omitted entirely rather than
         // forwarded as `apiKeyPresent: undefined`.
         ...(opts.apiKeyPresent !== undefined ? { apiKeyPresent: opts.apiKeyPresent } : {}),
+        policyExclusion: opts.policyExclusion ?? null,
+        seatCeiling: opts.seatCeiling ?? null,
+        contentClass: opts.contentClass ?? null,
     });
     return { ...resolved, configuredMode };
 }