@event4u/agent-config 9.9.0 → 9.11.0

package/src/scripts/ai_council/clients.ts

@@ -109,7 +109,7 @@ export const UNLIMITED_TOKENS_FALLBACK = 16384;
 // OpenAI reasoning models (o1, o3, o4 families) reject `max_tokens` and the
 // `system` role; they require `max_completion_tokens` and accept only `user`
 // (and `developer`) messages.
-const _REASONING_PREFIXES: readonly string[] = ['o1', 'o3', 'o4'];
+const _REASONING_PREFIXES: readonly string[] = ['o1', 'o3', 'o4', 'gpt-5'];
 
 export function _is_reasoning_model(model: string): boolean {
     const name = model.toLowerCase();
@@ -132,6 +132,38 @@ export class CliClientError extends Error {
     }
 }
 
+/**
+ * Anthropic cache_control TTL tiers (road-to-cache-economy Phase 4).
+ * `'5m'` is the permanent default — see `prompt_cache.ttl` in
+ * `docs/contracts/ai-council-config.md` for the falsification condition
+ * that would be required before `'1h'` is ever enabled anywhere.
+ */
+export type PromptCacheTtl = '5m' | '1h';
+export const DEFAULT_PROMPT_CACHE_TTL: PromptCacheTtl = '5m';
+
+/**
+ * Anthropic's cache_control ordering rule: within one request, a 1-hour
+ * breakpoint must be positioned before any 5-minute breakpoint. This
+ * client always applies the SAME configured ttl to both of its
+ * breakpoints (see `_ask_impl`), so the two are never mixed in
+ * practice — this guard exists so a future per-breakpoint ttl never
+ * regresses that invariant silently.
+ */
+export function assertCacheBreakpointOrder(ttls: readonly PromptCacheTtl[]): void {
+    let sawFiveMinute = false;
+    for (const ttl of ttls) {
+        if (ttl === '5m') {
+            sawFiveMinute = true;
+        } else if (ttl === '1h' && sawFiveMinute) {
+            throw new TypeError(
+                `cache_control breakpoint order violation: a '1h' breakpoint ` +
+                    `followed a '5m' one (${JSON.stringify(ttls)}) — Anthropic ` +
+                    `requires every 1h breakpoint before any 5m breakpoint.`,
+            );
+        }
+    }
+}
+
 /** Normalised output from a single council member (dataclass `CouncilResponse`). */
 export class CouncilResponse {
     provider: string;
@@ -319,6 +351,10 @@ interface ApiClientOptions {
     // unless it asks — so a single call never pays the ~1.25× write premium by
     // surprise. Only AnthropicClient consumes this; other providers ignore it.
     enable_prompt_cache?: boolean | undefined;
+    // TTL tier for both cache_control breakpoints (road-to-cache-economy
+    // Phase 4). Default '5m' when omitted — see `DEFAULT_PROMPT_CACHE_TTL`.
+    // Only meaningful when `enable_prompt_cache` is true.
+    prompt_cache_ttl?: PromptCacheTtl | undefined;
 }
 
 /** Shared ctor-options shape for the CLI clients. */
@@ -380,11 +416,17 @@ export class AnthropicClient extends ExternalAIClient {
     // ApiClientOptions.enable_prompt_cache. Prevents silent activation (and the
     // write premium) for callers that don't benefit from a shared-prefix cache.
     private _enablePromptCache: boolean;
+    // TTL applied to BOTH cache_control breakpoints below. '5m' (the
+    // default) is never serialised on the wire — omitting `ttl` is the
+    // Anthropic API's own 5-minute default, so the default case stays
+    // byte-identical to the pre-Phase-4 request shape.
+    private _promptCacheTtl: PromptCacheTtl;
 
     constructor(opts: ApiClientOptions = {}) {
         super();
         this.model = opts.model ?? DEFAULT_ANTHROPIC_MODEL;
         this._enablePromptCache = opts.enable_prompt_cache ?? false;
+        this._promptCacheTtl = opts.prompt_cache_ttl ?? DEFAULT_PROMPT_CACHE_TTL;
         if (opts.client !== undefined && opts.client !== null) {
             this._client = opts.client;
             return;
@@ -455,6 +497,18 @@ export class AnthropicClient extends ExternalAIClient {
             // base_system_prompt alone is often below the model's min cacheable
             // prefix and would never cache solo — the artefact block is where
             // the real saving lands. Two breakpoints (≤ the 4 allowed).
+            //
+            // Both breakpoints share the SAME configured ttl (road-to-
+            // cache-economy Phase 4) — they never diverge, so the API's
+            // "1h before 5m" ordering rule can never be violated here; the
+            // assertion below is a regression guard, not a live branch.
+            // Default '5m' omits the `ttl` field entirely (Anthropic's own
+            // default), so an unconfigured member's wire shape is unchanged
+            // from before Phase 4.
+            const ttl = this._promptCacheTtl;
+            assertCacheBreakpointOrder([ttl, ttl]);
+            const cache_control: Record<string, unknown> =
+                ttl === '1h' ? { type: 'ephemeral', ttl: '1h' } : { type: 'ephemeral' };
             const kwargs: Record<string, unknown> = this._enablePromptCache
                 ? {
                       model: this.model,
@@ -463,7 +517,7 @@ export class AnthropicClient extends ExternalAIClient {
                           {
                               type: 'text',
                               text: system_prompt,
-                              cache_control: { type: 'ephemeral' },
+                              cache_control,
                           },
                       ],
                       messages: [
@@ -473,11 +527,13 @@ export class AnthropicClient extends ExternalAIClient {
                               // volatile suffix (round critiques) rides after
                               // it, so round N+1 reads the cached prefix
                               // instead of re-writing it (A3 read unlock).
+                              // The volatile suffix NEVER carries cache_control
+                              // — the ttl reaches only the stable prefix.
                               content: [
                                   {
                                       type: 'text',
                                       text: stable_prompt,
-                                      cache_control: { type: 'ephemeral' },
+                                      cache_control,
                                   },
                                   ...(volatile_suffix
                                       ? [{ type: 'text', text: volatile_suffix }]

package/src/scripts/ai_council/config.ts

@@ -14,12 +14,16 @@
  * Validation contract (8 rules, all enforced at load time):
  *
  * 1. `enabled` is a bool.
- * 2. `defaults.mode` ∈ {`api`, `manual`, `cli`}; per-member mode same
- *    set. Semantics: `api` = SDK call against a stored key (billable);
+ * 2. `defaults.mode` ∈ {`api`, `manual`, `cli`, `auto`}; per-member mode
+ *    same set. Semantics: `api` = SDK call against a stored key (billable);
  *    `manual` = copy & paste — human transports prompt + reply between
  *    the agent and an external chat surface (free); `cli` = shell out to
  *    a locally-installed CLI under subscription auth (free for
- *    first-party CLIs, billable for community wrappers).
+ *    first-party CLIs, billable for community wrappers); `auto` = pick
+ *    per provider per invocation (cli → api → unavailable), resolved by
+ *    `transport_resolver.ts`. `auto` is opt-in — it is never the shipped
+ *    default, because flipping it would move an existing user's spend
+ *    from per-token dollars onto subscription quota with no config edit.
  * 3. `members.<name>` keys are restricted to the known provider set.
  * 4. `cost_budget.*` numeric fields are >= 0.
  * 5. Enabled members carry a non-empty `model` and `api_key_ref` when
@@ -30,7 +34,8 @@
  *    even if syntactically plausible.
  * 7. Resolved `file:` key paths must have mode 0o600 (delegated to
  *    `resolve_api_key`; runs at use-time, not parse-time).
- * 8. `binary:` is only valid when the member's effective mode is `cli`;
+ * 8. `binary:` is only valid when the member's effective mode is `cli` or
+ *    `auto` (auto may resolve to the cli rung);
  *    `cli_call_budget.max_calls_per_day.<provider>` keys must be valid
  *    providers.
  *
@@ -60,7 +65,7 @@ const _VALID_PROVIDERS: ReadonlySet<string> = new Set([
     'xai',
     'perplexity',
 ]);
-const _VALID_MODES: ReadonlySet<string> = new Set(['api', 'manual', 'cli']);
+const _VALID_MODES: ReadonlySet<string> = new Set(['api', 'manual', 'cli', 'auto']);
 
 /**
  * Prefixes that signal "this is a raw API key" so we refuse it loudly
@@ -362,6 +367,9 @@ export interface CostBudgetConfig {
     readonly max_output_tokens: number;
     readonly max_calls: number;
     readonly max_total_usd: number;
+    /** Rolling 24h cap. 0 disables it — and disabling it also disables the spend
+     * ledger, since the orchestrator only appends an entry while a cap is live. */
+    readonly daily_limit_usd: number;
 }
 
 export interface MemberConfig {
@@ -380,6 +388,13 @@ export interface MemberConfig {
      * back to deterministic config order.
      */
     readonly tier: number | null;
+    /**
+     * Cache-control TTL tier for this member's Anthropic breakpoints
+     * (road-to-cache-economy Phase 4). `'5m'` is the permanent default —
+     * see `prompt_cache.ttl` in `docs/contracts/ai-council-config.md` for
+     * the falsification condition that gates ever enabling `'1h'`.
+     */
+    readonly prompt_cache_ttl: '5m' | '1h';
 }
 
 /**
@@ -1591,12 +1606,14 @@ function _build_cost_budget(d: Dict): CostBudgetConfig {
         max_output_tokens: _pyInt(_get(d, 'max_output_tokens', 200_000)),
         max_calls: _pyInt(_get(d, 'max_calls', 50)),
         max_total_usd: _pyFloat(_get(d, 'max_total_usd', 20.0)),
+        daily_limit_usd: _pyFloat(_get(d, 'daily_limit_usd', 0.0)),
     };
     const fields: Array<[keyof CostBudgetConfig, boolean]> = [
         ['max_input_tokens', false],
         ['max_output_tokens', false],
         ['max_calls', false],
         ['max_total_usd', true],
+        ['daily_limit_usd', true],
     ];
     for (const [fname, isFloat] of fields) {
         const val = cb[fname];
@@ -1643,10 +1660,13 @@ function _build_member(
                 `members.${name}.binary must be a non-empty string when set.`,
             );
         }
-        if (effective_mode !== 'cli') {
+        // `auto` may resolve to the cli rung, so a binary override is
+        // legitimate there too — rejecting it would make `auto` unusable for
+        // anyone whose CLI is not on `$PATH` under its default name.
+        if (effective_mode !== 'cli' && effective_mode !== 'auto') {
             throw new CouncilConfigError(
                 `members.${name}.binary is only valid when the member's ` +
-                    `effective mode is 'cli' (got ${_pyRepr(effective_mode)}). Set ` +
+                    `effective mode is 'cli' or 'auto' (got ${_pyRepr(effective_mode)}). Set ` +
                     `\`mode: cli\` on the member or \`defaults.mode: cli\` to use ` +
                     `this field.`,
             );
@@ -1716,6 +1736,31 @@ function _build_member(
         }
         tier = tier_raw;
     }
+    // road-to-cache-economy Phase 4: `prompt_cache` stays accepted as a
+    // bare bool (the pre-existing, undocumented enable/disable form —
+    // untouched here) OR as a mapping carrying `ttl`. '5m' is the
+    // permanent default; see docs/contracts/ai-council-config.md
+    // § Prompt cache TTL for the falsification condition on '1h'.
+    const prompt_cache_raw = _get(cfg, 'prompt_cache', null);
+    let prompt_cache_ttl: '5m' | '1h' = '5m';
+    if (prompt_cache_raw !== null && prompt_cache_raw !== undefined && !_isBool(prompt_cache_raw)) {
+        if (!_isDict(prompt_cache_raw)) {
+            throw new CouncilConfigError(
+                `members.${name}.prompt_cache must be a bool or a mapping ` +
+                    `(got ${_pyTypeName(prompt_cache_raw)}).`,
+            );
+        }
+        const ttl_raw = _get(prompt_cache_raw, 'ttl', '5m');
+        if (ttl_raw !== '5m' && ttl_raw !== '1h') {
+            throw new CouncilConfigError(
+                `members.${name}.prompt_cache.ttl must be '5m' or '1h' (got ` +
+                    `${_pyRepr(ttl_raw)}). '5m' remains the default until a ` +
+                    `pre-registered 30-debate gap sample clears 40% at ` +
+                    `>=5-minute inter-round gaps.`,
+            );
+        }
+        prompt_cache_ttl = ttl_raw;
+    }
     return {
         name,
         enabled: member_enabled,
@@ -1726,6 +1771,7 @@ function _build_member(
         model_ladder: ladder,
         participate_low_impact: participate_raw,
         tier,
+        prompt_cache_ttl,
     };
 }
 

package/src/scripts/ai_council/modes.ts

@@ -12,17 +12,43 @@
  * - `manual`   — copy-paste loop with the user as transport (free).
  * - `cli`      — shell out to a locally-installed provider CLI under the
  *                user's subscription auth. `billable=False`.
+ * - `auto`     — resolve per provider per invocation (cli → api → unavailable).
+ *                Accepted here as a VALUE; the concrete transport is chosen by
+ *                `transport_resolver.ts`, which owns the chain and the billing
+ *                classification. `manual` is never part of the auto chain.
  *
  * Resolution precedence — first non-empty wins:
  *
  *     1. Invocation flag      e.g. `/council mode:manual`
  *     2. Per-member setting   `ai_council.members.<name>.mode`
- *     3. Global setting       `ai_council.mode`
+ *     3. Global setting       `ai_council.mode` OR `ai_council.defaults.mode`
+ *                             (see `resolve_global_mode` — both shapes reach
+ *                             this resolver, and they must agree)
  *     4. Built-in default     `manual`
+ *
+ * ## Two distinct defaults — the reconciliation (road-to-zero-ceremony-detection)
+ *
+ * The contract used to describe a single fallback (`"api"`) while this module
+ * implemented `manual`. Both were right about different layers, and the docs
+ * conflated them. They are now named separately:
+ *
+ * - **Loader default** — when a config file omits `defaults.mode` entirely,
+ *   `config.ts::_build_defaults` fills `api`. Unchanged; this is what every
+ *   real config observes, because the loader always populates the key.
+ * - **Built-in fallback** — when NO layer supplies a mode at all (a settings
+ *   dict handed straight to the resolver, no config file involved), the answer
+ *   is `manual`, below. That is the fail-closed direction the no-silent-spend
+ *   Iron Law requires: a caller who supplied no transport preference has not
+ *   asked to spend money, so the free transport wins.
  */
 
-export const VALID_MODES: ReadonlySet<string> = new Set(['api', 'manual', 'cli']);
+export const VALID_MODES: ReadonlySet<string> = new Set(['api', 'manual', 'cli', 'auto']);
 
+/**
+ * Built-in fallback when no layer supplies a mode. `manual` — free, no key,
+ * no spend. NOT the same as the loader's `defaults.mode` default (`api`); see
+ * the module header.
+ */
 export const DEFAULT_MODE = 'manual';
 
 /** Raised when a configured / invoked mode is not in `VALID_MODES`. */
@@ -72,6 +98,46 @@ function _pyReprList(items: string[]): string {
     return `[${items.map((i) => _pyRepr(i)).join(', ')}]`;
 }
 
+/**
+ * Extract the global transport mode from an `ai_council` block, accepting BOTH
+ * shapes the block legitimately arrives in.
+ *
+ * `council_cli.ts::_synthesize_ai_council_block` FLATTENS the loader's
+ * `defaults.mode` onto a top-level `mode` key, so the normal path presents the
+ * flat shape. But `build_members` is on the exported surface, and callers that
+ * hand it a RAW `.ai-council.yml`-shaped dict present the nested shape. Reading
+ * only the flat key silently dropped the configured default on that path and
+ * fell through to `DEFAULT_MODE`.
+ *
+ * Flat wins when both are present — it is the synthesized, already-resolved
+ * value. Returns `null` when neither shape carries a usable string, letting the
+ * precedence chain continue to the built-in.
+ */
+export function resolve_global_mode(
+    aiBlock: ReadonlyMap<string, unknown> | Record<string, unknown> | null | undefined,
+): string | null {
+    if (aiBlock === null || aiBlock === undefined) {
+        return null;
+    }
+    const flat = _normalise(_settingsGet(aiBlock, 'mode'));
+    if (flat !== null) {
+        return flat;
+    }
+    const defaults = _settingsGet(aiBlock, 'defaults');
+    if (defaults === null || defaults === undefined) {
+        return null;
+    }
+    if (!(defaults instanceof Map) && typeof defaults !== 'object') {
+        return null;
+    }
+    if (Array.isArray(defaults)) {
+        return null;
+    }
+    return _normalise(
+        _settingsGet(defaults as ReadonlyMap<string, unknown> | Record<string, unknown>, 'mode'),
+    );
+}
+
 export interface ResolveModeOptions {
     invocationMode?: string | null;
     memberSettings?: ReadonlyMap<string, unknown> | Record<string, unknown> | null;

package/src/scripts/ai_council/orchestrator.ts

@@ -51,6 +51,7 @@ import type {
 import {
     estimate_cost,
     estimate_input_tokens,
+    reprice_with_cache,
 } from './pricing.js';
 import type { ProjectContext } from './project_context.js';
 import type { AdvisorPlan } from './advisors.js';
@@ -779,22 +780,34 @@ function _run_round(
         spent.output += response.output_tokens;
         let actual_usd: number | null = null;
         if (estimates !== null && table !== null) {
-            // Bill the actual output against the budget using the
-            // member's per-1M output rate. Re-use estimate_cost with
-            // the *real* token count.
-            const actual = estimate_cost(
+            // Realized cost bills the OBSERVED cache read/write tokens
+            // (Anthropic's usage.input_tokens excludes them), unlike the
+            // cache-agnostic pre-flight estimate above — see
+            // `reprice_with_cache`'s docstring for why the two stay separate.
+            // ttl is '5m': the request builder emits `cache_control:
+            // {type:'ephemeral'}` with no explicit ttl, i.e. the 5-min default.
+            const actual = reprice_with_cache(
                 member.name,
                 member.model,
-                response.input_tokens,
-                response.output_tokens,
+                {
+                    input_tokens: response.input_tokens,
+                    cache_read_input_tokens: response.cache_read_input_tokens,
+                    cache_creation_input_tokens: response.cache_creation_input_tokens,
+                    output_tokens: response.output_tokens,
+                },
                 table,
+                '5m',
             );
             actual_usd = _total_usd(actual);
             spent.usd += _total_usd(actual);
             // Persist to the rolling 24h ledger when the daily cap is
             // active. Errors are swallowed inside record_spend.
             if (budget.daily_limit_usd > 0 && !response.error) {
-                _record_daily_spend(_total_usd(actual), member.name, member.model);
+                _record_daily_spend(_total_usd(actual), member.name, member.model, {
+                    cache_read_input_tokens: response.cache_read_input_tokens,
+                    cache_creation_input_tokens: response.cache_creation_input_tokens,
+                    cache_ttl: '5m',
+                });
             }
         }
         _stamp_transport_metadata(response, member, actual_usd);
@@ -1116,12 +1129,32 @@ export interface RunDebateOptions {
     project?: ProjectContext | null;
     original_ask?: string;
     max_rounds?: number;
+    /**
+     * Third argument (road-to-cache-economy Phase 4): the observed
+     * wall-clock gap, in ms, between the PREVIOUS round finishing (≈ when
+     * its stable prefix was written to the prompt cache) and THIS round
+     * starting (≈ when the same prefix would be read, if byte-identical).
+     * `null` on round 1 — nothing was written yet. Existing callers that
+     * declare only the first two parameters keep working unchanged (JS
+     * ignores extra call arguments).
+     */
     on_round_complete?:
-        | ((round_number: number, responses: CouncilResponse[]) => void)
+        | ((
+              round_number: number,
+              responses: CouncilResponse[],
+              cache_gap_ms_since_previous_round?: number | null,
+          ) => void)
         | null;
     on_continue?: DebateContinuePrompt | null;
     advisor_plans?: Map<string, AdvisorPlan> | null;
     seed_round_1?: CouncilResponse[] | null;
+    /**
+     * Injectable wall-clock source for the Phase-4 gap measurement above.
+     * Defaults to `Date.now`. Tests inject a scripted clock so "rounds
+     * seconds apart" vs "a >5-minute gap" can be asserted deterministically,
+     * without a real multi-minute sleep.
+     */
+    now?: (() => number) | null;
     /**
      * Phase 3: when true (from `ai_council.debate_gates.enabled`), round-2+
      * prompts carry the anti-conformity directive. Default `false` → the debate
@@ -1186,6 +1219,7 @@ export function run_debate(
     const on_continue = opts.on_continue ?? null;
     const advisor_plans = opts.advisor_plans ?? null;
     const seed_round_1 = opts.seed_round_1 ?? null;
+    const now = opts.now ?? Date.now;
 
     if (max_rounds < 1) {
         throw new Error(`max_rounds must be >= 1 (got ${max_rounds})`);
@@ -1207,6 +1241,9 @@ export function run_debate(
     // per-round positions block rides in a volatile suffix (see consult loop).
     let current_suffix = '';
     let current_user_prompt = question.user_prompt;
+    // road-to-cache-economy Phase 4: wall-clock marker for the inter-round
+    // cache-gap measurement. `null` until round 1 finishes.
+    let previous_round_end_ms: number | null = null;
 
     // Phase 3 restate: one pre-round-1 call per member. Runs BEFORE any debate
     // spend so a diverging restatement can be flagged before round-2 cost.
@@ -1231,6 +1268,9 @@ export function run_debate(
 
     for (let round_idx = 0; round_idx < max_rounds; round_idx++) {
         const round_number = round_idx + 1;
+        const round_start_ms = now();
+        const cache_gap_ms_since_previous_round: number | null =
+            previous_round_end_ms === null ? null : round_start_ms - previous_round_end_ms;
         let results: CouncilResponse[];
         if (round_idx === 0 && seed_round_1 !== null) {
             // Pivot from /council default — reuse the existing round 1
@@ -1276,7 +1316,7 @@ export function run_debate(
         }
         all_rounds.push(results);
         if (on_round_complete !== null) {
-            on_round_complete(round_number, results);
+            on_round_complete(round_number, results, cache_gap_ms_since_previous_round);
         }
 
         // Prep the user-prompt for the next round so the cost estimate
@@ -1334,6 +1374,11 @@ export function run_debate(
                 }
             }
         }
+        // road-to-cache-economy Phase 4: mark the end of this round AFTER the
+        // continue-prompt gate above — an interactive pause there is exactly
+        // the kind of real-world inter-round gap this measurement exists to
+        // observe, so it must fall inside the window, not before it.
+        previous_round_end_ms = now();
     }
 
     return all_rounds;