@event4u/agent-config 14.20.0 → 14.21.0

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 };
 }