@event4u/agent-config 9.0.0 → 9.2.0

package/src/scripts/ai_council/clients.ts

@@ -138,6 +138,12 @@ export class CouncilResponse {
     text: string;
     input_tokens: number;
     output_tokens: number;
+    // Prompt-cache accounting (Anthropic). `cache_read_input_tokens` bill at
+    // ~0.1× input; `cache_creation_input_tokens` at 1.25×/2×. Both default 0
+    // (no cache, or a provider that does not report them) so existing callers
+    // and the persisted response JSON stay backward-compatible.
+    cache_creation_input_tokens: number;
+    cache_read_input_tokens: number;
     latency_ms: number;
     error: string | null;
     metadata: Record<string, unknown>;
@@ -148,6 +154,8 @@ export class CouncilResponse {
         text: string;
         input_tokens?: number;
         output_tokens?: number;
+        cache_creation_input_tokens?: number;
+        cache_read_input_tokens?: number;
         latency_ms?: number;
         error?: string | null;
         metadata?: Record<string, unknown>;
@@ -157,6 +165,8 @@ export class CouncilResponse {
         this.text = opts.text;
         this.input_tokens = opts.input_tokens ?? 0;
         this.output_tokens = opts.output_tokens ?? 0;
+        this.cache_creation_input_tokens = opts.cache_creation_input_tokens ?? 0;
+        this.cache_read_input_tokens = opts.cache_read_input_tokens ?? 0;
         this.latency_ms = opts.latency_ms ?? 0;
         this.error = opts.error ?? null;
         // Python dataclass uses `field(default_factory=dict)` — each instance
@@ -278,6 +288,15 @@ interface ApiClientOptions {
     model?: string | undefined;
     client?: unknown;
     api_key?: string | null | undefined;
+    // Anthropic prompt caching (GA — no beta header). **Explicit opt-in,
+    // default OFF** — a caller must pass `true` to send the stable `system` +
+    // artefact prefix as cache-controlled blocks (member 2..N in a round, and
+    // round-2+ within the 5-min TTL, then read it at ~0.1× input). The council
+    // builder opts in via `_construct_api_member`; any other `AnthropicClient`
+    // caller (e.g. an API-mode team, a single-shot feature) gets NO caching
+    // 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;
 }
 
 /** Shared ctor-options shape for the CLI clients. */
@@ -335,10 +354,15 @@ export class AnthropicClient extends ExternalAIClient {
     override name = 'anthropic';
     override billable = true;
     private _client: unknown;
+    // Prompt caching is explicit opt-in (default OFF) — see
+    // 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;
 
     constructor(opts: ApiClientOptions = {}) {
         super();
         this.model = opts.model ?? DEFAULT_ANTHROPIC_MODEL;
+        this._enablePromptCache = opts.enable_prompt_cache ?? false;
         if (opts.client !== undefined && opts.client !== null) {
             this._client = opts.client;
             return;
@@ -381,12 +405,44 @@ export class AnthropicClient extends ExternalAIClient {
             if (typeof create !== 'function') {
                 throw new TypeError("'messages.create' is not callable");
             }
-            response = create.call(messages, {
-                model: this.model,
-                max_tokens,
-                system: system_prompt,
-                messages: [{ role: 'user', content: user_prompt }],
-            });
+            // Prompt caching (GA — no beta header). Breakpoints on BOTH the
+            // system block (stable across rounds) and the user artefact block
+            // (the large system+artefact prefix is byte-identical across
+            // members 2..N within a round, so they read it at ~0.1× input).
+            // 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).
+            const kwargs: Record<string, unknown> = this._enablePromptCache
+                ? {
+                      model: this.model,
+                      max_tokens,
+                      system: [
+                          {
+                              type: 'text',
+                              text: system_prompt,
+                              cache_control: { type: 'ephemeral' },
+                          },
+                      ],
+                      messages: [
+                          {
+                              role: 'user',
+                              content: [
+                                  {
+                                      type: 'text',
+                                      text: user_prompt,
+                                      cache_control: { type: 'ephemeral' },
+                                  },
+                              ],
+                          },
+                      ],
+                  }
+                : {
+                      model: this.model,
+                      max_tokens,
+                      system: system_prompt,
+                      messages: [{ role: 'user', content: user_prompt }],
+                  };
+            response = create.call(messages, kwargs);
         } catch (exc) {
             return new CouncilResponse({
                 provider: this.name,
@@ -426,6 +482,12 @@ export class AnthropicClient extends ExternalAIClient {
             text,
             input_tokens: usage ? (_getattr(usage, 'input_tokens', 0) as number) : 0,
             output_tokens: usage ? (_getattr(usage, 'output_tokens', 0) as number) : 0,
+            cache_creation_input_tokens: usage
+                ? (_getattr(usage, 'cache_creation_input_tokens', 0) as number)
+                : 0,
+            cache_read_input_tokens: usage
+                ? (_getattr(usage, 'cache_read_input_tokens', 0) as number)
+                : 0,
             latency_ms,
         });
     }

package/src/scripts/ai_council/pricing.ts

@@ -101,6 +101,68 @@ export function estimate_cost(
     };
 }
 
+// ── prompt-cache repricing ─────────────────────────────────────────
+//
+// Prompt-cache multipliers derived from the base input rate (Anthropic, GA —
+// no beta header): cache reads bill at ~0.1× input; cache writes at 1.25×
+// (5-min TTL) / 2× (1-h TTL). Kept as CONSTANTS, not columns in
+// `.agent-prices.md`, because that table's row format is byte-frozen (see the
+// file header) and downstream tests pin it.
+export const CACHE_READ_MULTIPLIER = 0.1;
+export const CACHE_WRITE_MULTIPLIER_5M = 1.25;
+export const CACHE_WRITE_MULTIPLIER_1H = 2.0;
+
+export interface CacheTokenBreakdown {
+    input_tokens: number; // uncached input, billed at the full rate
+    cache_read_input_tokens?: number; // billed at CACHE_READ_MULTIPLIER × input
+    cache_creation_input_tokens?: number; // billed at the write multiplier
+    output_tokens: number;
+}
+
+/**
+ * Realized cost of a call given OBSERVED cache-token counts (from
+ * `CouncilResponse.usage`). Deliberately separate from `estimate_cost`, which
+ * stays cache-agnostic (a conservative 0%-cache-hit pre-flight) so the budget
+ * gate never under-predicts. This function is the post-hoc actual that surfaces
+ * the saving. `ttl` selects the write multiplier (default 5-min).
+ */
+export function reprice_with_cache(
+    provider: string,
+    model: string,
+    tokens: CacheTokenBreakdown,
+    table: PriceTable,
+    ttl: '5m' | '1h' = '5m',
+): CostEstimate {
+    const price = lookup(table, provider, model);
+    const read = tokens.cache_read_input_tokens ?? 0;
+    const write = tokens.cache_creation_input_tokens ?? 0;
+    const totalInput = tokens.input_tokens + read + write;
+    if (price === null) {
+        return {
+            provider,
+            model,
+            input_tokens: totalInput,
+            output_tokens: tokens.output_tokens,
+            input_usd: 0.0,
+            output_usd: 0.0,
+        };
+    }
+    const writeMult = ttl === '1h' ? CACHE_WRITE_MULTIPLIER_1H : CACHE_WRITE_MULTIPLIER_5M;
+    const inputUsd =
+        (tokens.input_tokens / 1_000_000) * price.input_per_1m_usd +
+        (read / 1_000_000) * price.input_per_1m_usd * CACHE_READ_MULTIPLIER +
+        (write / 1_000_000) * price.input_per_1m_usd * writeMult;
+    const outputUsd = (tokens.output_tokens / 1_000_000) * price.output_per_1m_usd;
+    return {
+        provider,
+        model,
+        input_tokens: totalInput,
+        output_tokens: tokens.output_tokens,
+        input_usd: inputUsd,
+        output_usd: outputUsd,
+    };
+}
+
 // ── staleness ──────────────────────────────────────────────────────
 
 /** Return the most recent Monday 00:00 UTC as a date (YYYY-MM-DD). */

package/src/scripts/council_cli.ts

@@ -603,8 +603,13 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
                 );
             }
             const api_key_ref = (cfg['api_key_ref'] as string | null) ?? null;
+            // Council opts in explicitly (caching is client-default OFF): on
+            // unless the operator sets `prompt_cache: false` on the member.
+            const enable_prompt_cache = cfg['prompt_cache'] !== false;
             for (const sib_model of siblings[name] as string[]) {
-                members.push(_construct_api_member(name, sib_model, { api_key_ref }));
+                members.push(
+                    _construct_api_member(name, sib_model, { api_key_ref, enable_prompt_cache }),
+                );
             }
             continue;
         }
@@ -613,6 +618,9 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
             members.push(
                 _construct_api_member(name, model, {
                     api_key_ref: (cfg['api_key_ref'] as string | null) ?? null,
+                    // Council opts in explicitly (client-default OFF); on unless
+                    // the operator sets `prompt_cache: false`.
+                    enable_prompt_cache: cfg['prompt_cache'] !== false,
                 }),
             );
         } else if (mode === 'cli' && _CLI_PROVIDERS.has(name)) {
@@ -747,14 +755,18 @@ function _format_advisor_summary(
 function _construct_api_member(
     name: string,
     model: string | null,
-    opts: { api_key_ref?: string | null } = {},
+    opts: { api_key_ref?: string | null; enable_prompt_cache?: boolean | undefined } = {},
 ): ExternalAIClient {
     const api_key_ref = opts.api_key_ref ?? null;
     if (name === 'anthropic') {
         const api_key = api_key_ref
             ? resolve_api_key(api_key_ref, 'ai_council.members.anthropic')
             : load_anthropic_key();
-        return new AnthropicClient({ model: model || 'claude-sonnet-4-5', api_key });
+        return new AnthropicClient({
+            model: model || 'claude-sonnet-4-5',
+            api_key,
+            enable_prompt_cache: opts.enable_prompt_cache,
+        });
     }
     if (name === 'openai') {
         const api_key = api_key_ref
@@ -1409,6 +1421,8 @@ function _serialise_responses(responses: CouncilResponse[]): Dict[] {
             text: r.text,
             input_tokens: r.input_tokens,
             output_tokens: r.output_tokens,
+            cache_creation_input_tokens: r.cache_creation_input_tokens,
+            cache_read_input_tokens: r.cache_read_input_tokens,
             latency_ms: r.latency_ms,
             error: r.error,
             metadata,
@@ -1427,6 +1441,8 @@ function _deserialise_responses(items: Dict[]): CouncilResponse[] {
                 text: (d['text'] as string) ?? '',
                 input_tokens: _pyInt(d['input_tokens'] ?? 0, 0),
                 output_tokens: _pyInt(d['output_tokens'] ?? 0, 0),
+                cache_creation_input_tokens: _pyInt(d['cache_creation_input_tokens'] ?? 0, 0),
+                cache_read_input_tokens: _pyInt(d['cache_read_input_tokens'] ?? 0, 0),
                 latency_ms: _pyInt(d['latency_ms'] ?? 0, 0),
                 error: (d['error'] as string | null) ?? null,
                 metadata: (d['metadata'] as Dict) || {},

package/src/scripts/install.ts

@@ -2494,7 +2494,11 @@ function _detect_legacy_for_migration(project_root: string): string[] {
         return [];
     }
 
-    if (isFile(path.join(project_root, CONSUMER_BRIDGE_MARKER_RELPATH))) return [];
+    // Migration-idempotency sentinel. Previously the consumer bridge marker;
+    // that file was retired (ADR-020 amendment 2026-07-13), so the durable
+    // "this project has already been installed / migrated" signal is now the
+    // install-mode marker, written on every full or minimal install.
+    if (isFile(path.join(project_root, INSTALL_MODE_MARKER_REL))) return [];
 
     const found: string[] = [];
     for (const name of MIGRATE_LEGACY_YAML_FILES) {
@@ -2573,38 +2577,34 @@ function _format_global_root_for_marker(global_root: string): string {
 }
 
 /**
- * Write `agents/.event4u-bridge.yml`. Skipped under `AGENT_CONFIG_DEV_MODE=1`
- * and when the project root is the agent-config source repo
- * (`.agent-src.uncondensed/` present) — same rationale. Atomic write.
+ * Remove a legacy `agents/.event4u-bridge.yml` if a previous install wrote
+ * one. The bridge marker was retired (ADR-020 dated amendment 2026-07-13):
+ * it carried no project-specific data — `global_root` is derived directly
+ * from the well-known `~/.event4u/agent-config` path — yet was committed to
+ * the shared project tree, so every developer's install rewrote its volatile
+ * `installed_at` / `installer_version` fields and overwrote each other's.
+ * The global root is now resolved from the well-known path; the migration
+ * idempotency sentinel moved to `agents/.agent-state/install-mode.txt`.
+ *
+ * Skipped under `AGENT_CONFIG_DEV_MODE=1` and inside the agent-config source
+ * repo (detected by the uncondensed-source marker dir) — the same gate the
+ * writer used. Returns the removed path (so the caller can report it) or null.
  */
-function _write_consumer_bridge_marker(
+function _remove_legacy_consumer_bridge_marker(
     project_root: string,
-    installer_version: string,
     env: NodeJS.ProcessEnv | null = null,
-    now: Date | null = null,
 ): string | null {
     const env_map = env ?? process.env;
     if (env_map['AGENT_CONFIG_DEV_MODE'] === '1') return null;
     if (isDir(path.join(project_root, '.agent-src.uncondensed'))) return null;
 
-    const global_root_str = _format_global_root_for_marker(
-        user_global_paths.event4u_root(env_map),
-    );
-    const stamp = utcStamp(now ?? undefined);
-
-    const body =
-        '# event4u/agent-config — consumer bridge marker (auto-written).\n' +
-        '# Spec: docs/contracts/consumer-bridge.md (event4u-bridge/v1).\n' +
-        '# Reader contract: expand ~ against the current $HOME; fail closed\n' +
-        '# when global_root is missing on disk; never write back through it.\n' +
-        'schema: event4u-bridge/v1\n' +
-        `global_root: ${global_root_str}\n` +
-        `installed_at: ${stamp}\n` +
-        `installer_version: ${installer_version}\n`;
-
     const target = path.join(project_root, CONSUMER_BRIDGE_MARKER_RELPATH);
-    mkdirp(path.dirname(target));
-    atomicWrite0644(target, body, '.event4u-bridge.');
+    if (!isFile(target)) return null;
+    try {
+        fs.rmSync(target);
+    } catch {
+        return null;
+    }
     return target;
 }
 
@@ -2641,16 +2641,14 @@ function _write_per_tool_project_anchors(
         const target = path.join(project_root, rel_path);
         mkdirp(path.dirname(target));
 
-        const bridge_abs = path.join(project_root, CONSUMER_BRIDGE_MARKER_RELPATH);
-        const bridge_rel = path.relative(path.dirname(target), bridge_abs);
-
         const body =
             '# event4u/agent-config — per-tool project anchor (auto-written).\n' +
             '# Spec: docs/contracts/consumer-bridge.md § Per-tool anchor strategy.\n' +
-            `# Tool: ${tool_id}. Bridge marker: agents/.event4u-bridge.yml.\n` +
+            `# Tool: ${tool_id}. Resolves the global install directly — no\n` +
+            '# project-local bridge marker (retired, ADR-020 amendment 2026-07-13).\n' +
+            '# This anchor is gitignored: each developer regenerates it on install.\n' +
             'schema: event4u-bridge/v1\n' +
             `tool: ${tool_id}\n` +
-            `bridge: ${bridge_rel}\n` +
             `global_root: ${global_root_str}\n` +
             `installed_at: ${stamp}\n`;
 
@@ -3377,15 +3375,15 @@ function install_global(
         const rc = _update_installed_tools_manifest(project_root, tools, 'global', force, files_by_tool);
         if (rc !== 0) return rc;
 
-        // Consumer bridge marker (Phase 4.2). The surrounding
-        // `.agent-src.uncondensed` guard already covers the source-repo case;
-        // the dev-mode skip is enforced inside the writer.
-        const marker_path = _write_consumer_bridge_marker(project_root, installed_version);
-        if (marker_path !== null && !state.QUIET) {
-            const rel = isRelativeTo(marker_path, project_root)
-                ? path.relative(project_root, marker_path)
-                : marker_path;
-            info(`Bridge marker written: ${rel}`);
+        // Consumer bridge marker retired (ADR-020 amendment 2026-07-13):
+        // clean up any legacy `agents/.event4u-bridge.yml` a prior install
+        // committed. The global root is resolved from the well-known path.
+        const removed_marker = _remove_legacy_consumer_bridge_marker(project_root);
+        if (removed_marker !== null && !state.QUIET) {
+            const rel = isRelativeTo(removed_marker, project_root)
+                ? path.relative(project_root, removed_marker)
+                : removed_marker;
+            info(`Removed legacy bridge marker: ${rel}`);
         }
 
         const anchor_paths = _write_per_tool_project_anchors(project_root, tools);
@@ -3800,13 +3798,14 @@ function install_minimal(target_root_in: string, force: boolean, user_type: stri
         }
     }
 
-    const installed_version = installed_lock.current_package_version();
-    const marker_path = _write_consumer_bridge_marker(target_root, installed_version);
-    if (marker_path !== null) {
-        const rel = isRelativeTo(marker_path, target_root)
-            ? path.relative(target_root, marker_path)
-            : marker_path;
-        success(`Wrote ${rel}`);
+    // Bridge marker retired (ADR-020 amendment 2026-07-13) — clean up any
+    // legacy `agents/.event4u-bridge.yml` a prior install left behind.
+    const removed_marker = _remove_legacy_consumer_bridge_marker(target_root);
+    if (removed_marker !== null) {
+        const rel = isRelativeTo(removed_marker, target_root)
+            ? path.relative(target_root, removed_marker)
+            : removed_marker;
+        success(`Removed legacy bridge marker: ${rel}`);
     }
 
     _write_install_mode_marker(target_root, 'minimal');

package/src/scripts/lint_agents_layout.ts

@@ -42,7 +42,11 @@ const ALLOWED_FLAT_FILES: ReadonlySet<string> = new Set([
     // separate violation caught by check_tracked_but_ignored.ts.
     '.ai-video.xml',       // operator AI-video config; gitignored per .gitignore § AI Video
     'installed-tools.lock', // installer per-user inventory; gitignored per ADR-020
-    '.event4u-bridge.yml',  // consumer bridge marker; ADR-020 (should only be in consumers)
+    // Retired marker (ADR-020 amendment 2026-07-13). No longer written; the
+    // global root resolves from `~/.event4u/agent-config`. Kept tolerated so a
+    // legacy leftover in a not-yet-reinstalled consumer is not flagged as a
+    // violation — the next install deletes it.
+    '.event4u-bridge.yml',
 ]);
 
 // All directories allowed at the agents/ root in the SOURCE REPO.
@@ -75,6 +79,8 @@ const ALLOWED_SOURCE_DIRS: ReadonlySet<string> = new Set([
 const CONSUMER_EXPECTED_ENTRIES: ReadonlySet<string> = new Set([
     // Required consumer entries
     'overrides',
+    // Retired marker (ADR-020 amendment 2026-07-13) — no longer written, but
+    // kept in the tolerated set so a legacy leftover does not warn.
     '.event4u-bridge.yml',
     '.gitkeep',
     // Optional but legitimate consumer entries (will not trigger warnings)
@@ -93,9 +99,9 @@ const CONSUMER_EXPECTED_ENTRIES: ReadonlySet<string> = new Set([
 const MIGRATE_HINT =
     'Run `npx @event4u/agent-config migrate` to sweep legacy project-scope ' +
     'artefacts in one pass. The unified `migrate` command (see ' +
-    '`docs/contracts/migrate-command.md`) leaves `agents/overrides/` + ' +
-    '`agents/.event4u-bridge.yml` as the only consumer-side files; the ' +
-    'wizard recreates fresh config on `agent-config setup`.';
+    '`docs/contracts/migrate-command.md`) leaves `agents/overrides/` as the ' +
+    'only consumer-side agent surface; the wizard recreates fresh config on ' +
+    '`agent-config setup`.';
 
 function _isDir(p: string): boolean {
     try {