@event4u/agent-config 9.10.0 → 9.12.0

package/src/scripts/_lib/package_root.ts

@@ -0,0 +1,72 @@
+/**
+ * Layout-independent package-root resolution for the `_cli` delegate commands.
+ *
+ * `src/scripts/_cli/*.ts` sits three levels below the package root, so every
+ * delegate command derived the root with three hard-coded parent hops. Then the
+ * delegate precompile (`fa51c5a54`) started bundling those same modules into
+ * `dist/cli-delegate/*.js` — **two** levels below the root. Fixed hop counts are
+ * correct in exactly one of the two layouts, and nothing failed loudly: three
+ * hops from the bundle lands on `<pkg>/..`, which for a scoped install is
+ * `node_modules/@event4u`. `conformance` then reported `dist/router.json` and
+ * `src/scripts/hook_manifest.yaml` as missing — files that ship fine — and the
+ * 9.11.0 release PR's `tarball E2E` went red on both Node majors.
+ *
+ * The fix is to stop counting hops. Anchor on the marker that actually defines
+ * the root: the `package.json` whose `name` is this package. That answer holds
+ * for the source tree, for any bundle depth, for npm-global, npx, and
+ * vendor/bin symlink invocations — and it keeps holding if either directory
+ * ever moves.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** `name` in this package's own package.json — the root marker. */
+export const PACKAGE_NAME = '@event4u/agent-config';
+
+/**
+ * Bound on the upward walk. Deep enough for any real install path, finite so a
+ * malformed start value can never spin.
+ */
+const MAX_ASCENT = 16;
+
+/**
+ * Absolute package root for the module at `fromUrlOrPath` (pass
+ * `import.meta.url`).
+ *
+ * Walks up looking for the package.json whose `name` is {@link PACKAGE_NAME}.
+ * A consumer's own package.json encountered on the way is skipped by that name
+ * check, so an install nested under another project resolves correctly.
+ *
+ * `legacyHops` is the pre-existing hop count for the *source* layout and is
+ * used only if no marker is found. Falling back beats throwing during CLI
+ * startup: a wrong path yields one actionable "missing file" message, while an
+ * exception takes down every command in the delegate.
+ */
+export function resolvePackageRoot(fromUrlOrPath: string, legacyHops = 3): string {
+    const start = fromUrlOrPath.startsWith('file:') ? fileURLToPath(fromUrlOrPath) : fromUrlOrPath;
+    const startDir = path.dirname(start);
+
+    let dir = startDir;
+    for (let i = 0; i < MAX_ASCENT; i++) {
+        const manifest = path.join(dir, 'package.json');
+        if (fs.existsSync(manifest)) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(manifest, 'utf8')) as { name?: unknown };
+                if (parsed.name === PACKAGE_NAME) {
+                    return dir;
+                }
+            } catch {
+                // Unreadable / unparseable manifest — not our marker; keep ascending.
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break; // filesystem root
+        }
+        dir = parent;
+    }
+
+    return path.resolve(startDir, ...(Array.from({ length: legacyHops }, () => '..') as string[]));
+}

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
@@ -1655,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.`,
             );

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/transport_resolver.ts

@@ -0,0 +1,331 @@
+/**
+ * Transport resolution for `mode: auto`, plus the two guards that keep it
+ * honest (Phase 2 of `road-to-zero-ceremony-detection`).
+ *
+ * `modes.ts` answers "which mode did the config ask for" — a pure precedence
+ * walk over four layers. This module answers the next question: when that
+ * answer is `auto`, which concrete transport does THIS machine support right
+ * now, how is it billed, and what happens when the chosen rung fails
+ * mid-invocation.
+ *
+ * ## The `auto` chain
+ *
+ *     cli   — the provider's CLI binary resolves AND a credential is present
+ *     api   — else a key resolves
+ *     ∅     — else unavailable, with a one-line reason
+ *
+ * `manual` is deliberately NOT in the chain. It is free and always "available"
+ * (the human is the transport), so an availability-ranked chain would always
+ * end there and `auto` would silently become "ask the human to copy-paste".
+ * Manual stays an explicit opt-in.
+ *
+ * ## The billing invariant
+ *
+ * Billing is classified from (provider, detected auth source) by
+ * `classifyBilling` in `_lib/environment_detector.ts` — never from the
+ * transport this module picked. That is the property that keeps the existing
+ * per-provider rules intact under `auto`:
+ *
+ * - a VENDOR-OFFICIAL CLI under a subscription login is unmetered, so the USD
+ *   cost gate stays off and `cli_call_budget` guards the plan quota instead;
+ * - a COMMUNITY wrapper (`grok`, `perplexity`) shells out to the same paid API
+ *   and stays metered even though the transport is also spelled `cli`;
+ * - an unknown source is metered — deliberately over-gated.
+ *
+ * `makesProviderCall` below IS transport-derived, and is not a billing term:
+ * it records that `manual` performs no provider call at all, which is why no
+ * amount of billing classification applies to it.
+ *
+ * @see docs/contracts/ai-council-config.md § Transport modes
+ */
+
+import {
+    classifyBilling,
+    isCommunityCli,
+    strongestAuth,
+    PROVIDER_CLI_META,
+    type AuthSource,
+    type BillingClass,
+    type EnvironmentReport,
+} from '../_lib/environment_detector.js';
+
+/** A concrete transport a member can actually run on. `auto` is not one. */
+export type Transport = 'api' | 'manual' | 'cli';
+
+/** The accepted values of the `mode` key, including the resolver-only `auto`. */
+export const VALID_TRANSPORT_MODES: ReadonlySet<string> = new Set([
+    'api',
+    'manual',
+    'cli',
+    'auto',
+]);
+
+export interface ResolvedTransport {
+    /** False when `auto` found no usable rung; `reason` then says why. */
+    readonly available: boolean;
+    /** The concrete transport, or `null` when unavailable. */
+    readonly transport: Transport | null;
+    /** How a provider call is paid for. From auth source only — never from `transport`. */
+    readonly billing: BillingClass;
+    /** The auth source the classification used, or `null` when none was detected. */
+    readonly authSource: AuthSource | null;
+    /** Transport-derived, NOT a billing term: `manual` performs no provider call. */
+    readonly makesProviderCall: boolean;
+    /** One-line reason. Non-empty exactly when `available` is false. */
+    readonly reason: string | null;
+}
+
+export interface ResolveTransportOptions {
+    readonly provider: string;
+    /** The mode `resolve_mode` returned — `api` | `manual` | `cli` | `auto`. */
+    readonly mode: string;
+    /** The single read-only environment report. */
+    readonly report: EnvironmentReport;
+    /** Member-level `binary:` override, when set. Counts as a resolved binary. */
+    readonly binaryOverride?: string | null;
+    /**
+     * Whether the member's `api_key_ref` resolves. Defaults to "a key-file or
+     * env-key auth record exists for this provider" from the report.
+     */
+    readonly apiKeyPresent?: boolean;
+}
+
+/** Auth sources that mean "the provider CLI can authenticate". */
+const CLI_AUTH_SOURCES: ReadonlySet<AuthSource> = new Set(['cli-subscription', 'cli-api-key']);
+
+/** Auth sources that mean "a stored key exists for the api transport". */
+const KEY_AUTH_SOURCES: ReadonlySet<AuthSource> = new Set(['key-file', 'env-key']);
+
+function hasSource(
+    report: EnvironmentReport,
+    provider: string,
+    allowed: ReadonlySet<AuthSource>,
+): boolean {
+    return report.auth.some((a) => a.provider === provider && allowed.has(a.source));
+}
+
+/** Resolved CLI binary for `provider` from the report, or `null`. */
+function cliBinary(report: EnvironmentReport, provider: string): string | null {
+    const meta = PROVIDER_CLI_META[provider];
+    if (meta === undefined) return null;
+    const binaryName = meta[0];
+    const host = report.hosts.find(
+        (h) => h.binary !== null && stripExeSuffix(basename(h.binary)) === binaryName,
+    );
+    return host?.binary ?? null;
+}
+
+/** Last path segment, separator-agnostic (no `node:path` import needed). */
+function basename(p: string): string {
+    const parts = p.split(/[/\\]/);
+    return parts[parts.length - 1] ?? p;
+}
+
+/** Strip a Windows executable suffix so `claude.cmd` matches `claude`. */
+function stripExeSuffix(name: string): string {
+    return name.replace(/\.(exe|cmd)$/i, '');
+}
+
+/**
+ * Resolve one member's transport.
+ *
+ * Explicit `api` / `manual` / `cli` pass through unchanged — this function
+ * never overrides a mode the user or a per-member override asked for. Only
+ * `auto` walks the chain.
+ */
+export function resolveTransport(opts: ResolveTransportOptions): ResolvedTransport {
+    const { provider, mode, report } = opts;
+    const auth = strongestAuth(report, provider);
+    const authSource = auth?.source ?? null;
+    const billing = classifyBilling(provider, authSource);
+
+    if (mode === 'manual') {
+        return {
+            available: true,
+            transport: 'manual',
+            // Classified from the auth source like every other member; it is
+            // simply never consulted because no provider call happens.
+            billing,
+            authSource,
+            makesProviderCall: false,
+            reason: null,
+        };
+    }
+
+    if (mode === 'api' || mode === 'cli') {
+        return {
+            available: true,
+            transport: mode,
+            billing,
+            authSource,
+            makesProviderCall: true,
+            reason: null,
+        };
+    }
+
+    if (mode !== 'auto') {
+        return unavailable(
+            provider,
+            billing,
+            `mode=${JSON.stringify(mode)} is not one of ` +
+                `${[...VALID_TRANSPORT_MODES].sort().join(', ')}`,
+        );
+    }
+
+    // ── the auto chain ──────────────────────────────────────────────────
+    const override = (opts.binaryOverride ?? null)?.trim() ?? null;
+    const binary = override !== null && override !== '' ? override : cliBinary(report, provider);
+    const cliAuthed = hasSource(report, provider, CLI_AUTH_SOURCES);
+
+    if (binary !== null && cliAuthed) {
+        return {
+            available: true,
+            transport: 'cli',
+            billing,
+            authSource,
+            makesProviderCall: true,
+            reason: null,
+        };
+    }
+
+    const keyPresent = opts.apiKeyPresent ?? hasSource(report, provider, KEY_AUTH_SOURCES);
+    if (keyPresent) {
+        return {
+            available: true,
+            transport: 'api',
+            billing,
+            authSource,
+            makesProviderCall: true,
+            reason: null,
+        };
+    }
+
+    return unavailable(provider, billing, autoUnavailableReason(provider, binary, cliAuthed));
+}
+
+function unavailable(
+    _provider: string,
+    billing: BillingClass,
+    reason: string,
+): ResolvedTransport {
+    return {
+        available: false,
+        transport: null,
+        // Unavailable members never spend, but the class stays over-gated so a
+        // caller that ignores `available` cannot read this as "free".
+        billing,
+        authSource: null,
+        makesProviderCall: false,
+        reason,
+    };
+}
+
+/** The one-line reason `auto` prints when no rung resolved. */
+function autoUnavailableReason(
+    provider: string,
+    binary: string | null,
+    cliAuthed: boolean,
+): string {
+    const expected = PROVIDER_CLI_META[provider]?.[0] ?? provider;
+    if (binary === null && !cliAuthed) {
+        return (
+            `no transport available: \`${expected}\` is not on PATH and no key resolves ` +
+            `— install the CLI and log in, or add an api_key_ref`
+        );
+    }
+    if (binary === null) {
+        return (
+            `no transport available: a credential is present but \`${expected}\` is not ` +
+            `on PATH and no key resolves — install the CLI, or add an api_key_ref`
+        );
+    }
+    return (
+        `no transport available: \`${expected}\` is on PATH but not authenticated and no ` +
+        `key resolves — log in to the CLI, or add an api_key_ref`
+    );
+}
+
+// ── mid-flight fallback ─────────────────────────────────────────────────
+
+/**
+ * Why a CLI call failed, normalised from `CliClient._classify_stderr` and the
+ * `binary_missing` skip reason.
+ */
+export type CliFailureClass =
+    | 'binary_missing'
+    | 'auth_rejected'
+    | 'cli_unsupported'
+    | 'timeout'
+    | 'server_error'
+    | 'quota_exhausted'
+    | 'other';
+
+/**
+ * Failure classes that may fall through to the `api` rung.
+ *
+ * All three share one property: the CLI provably never reached the provider,
+ * so retrying on another transport cannot double-charge. Everything absent
+ * from this set — notably `timeout` and `server_error` — may have left a
+ * half-completed call behind, and falling through would risk paying twice for
+ * one question. `quota_exhausted` is excluded for a different reason: the
+ * quota is a cap the user deliberately set, so routing around it would defeat
+ * the guard rather than recover from a fault.
+ */
+const FALLBACK_ELIGIBLE: ReadonlySet<CliFailureClass> = new Set([
+    'binary_missing',
+    'auth_rejected',
+    'cli_unsupported',
+]);
+
+/** Normalise a raw client error / skip reason into a `CliFailureClass`. */
+export function classifyCliFailure(raw: string): CliFailureClass {
+    const s = raw.trim().toLowerCase();
+    if (s === 'binary_missing' || s === 'file_not_found') return 'binary_missing';
+    if (s === 'auth_expired' || s === 'auth_rejected' || s === 'unauthorized') {
+        return 'auth_rejected';
+    }
+    if (s === 'cli_unsupported' || s === 'unsupported' || s === 'parse_failed') {
+        return 'cli_unsupported';
+    }
+    if (s === 'timeout') return 'timeout';
+    if (s === 'cli_quota_exhausted' || s === 'quota_exhausted') return 'quota_exhausted';
+    if (/^exit_5\d\d$/.test(s) || s === 'server_error' || s === 'os') return 'server_error';
+    return 'other';
+}
+
+/** True when `failure` is eligible to fall through to the `api` rung. */
+export function isFallbackEligible(failure: CliFailureClass): boolean {
+    return FALLBACK_ELIGIBLE.has(failure);
+}
+
+/**
+ * One-shot, per-provider fallback ledger for a single invocation.
+ *
+ * Construct one per council run. `attempt` returns `'api'` at most ONCE per
+ * provider, and only for a fallback-eligible failure class; every later call
+ * for that provider returns `'stop'`. This is the double-spend guard: a
+ * timeout never falls through, and an eligible failure never falls through
+ * twice.
+ */
+export class MidFlightFallback {
+    private readonly used = new Set<string>();
+
+    /** `'api'` to retry on the api rung, `'stop'` to surface the failure. */
+    attempt(provider: string, failure: CliFailureClass): 'api' | 'stop' {
+        if (!isFallbackEligible(failure)) return 'stop';
+        if (this.used.has(provider)) return 'stop';
+        this.used.add(provider);
+        return 'api';
+    }
+
+    /** Providers that have already spent their one fallback. */
+    spent(): readonly string[] {
+        return [...this.used].sort();
+    }
+}
+
+/**
+ * True when `provider`'s CLI transport is a community wrapper — re-exported
+ * so callers reasoning about `auto` do not have to reach into the detector.
+ */
+export { isCommunityCli };

package/src/scripts/check_bundle_path_leakage.ts

@@ -62,10 +62,16 @@ const REPO = path.resolve(path.dirname(_HERE), '..', '..');
 
 // Tracked directories that may hold a build-generated bundle. Only
 // `dist/install/` is force-included in `.gitignore` today (`!/dist/install/`);
-// `dist/hooks/` and `dist/mcp/` are listed defensively in case a future
-// change tracks them too — `git ls-files` on an untracked directory returns
-// nothing, so listing an as-yet-untracked root here is always safe.
-const BUNDLE_ROOTS: readonly string[] = ['dist/install', 'dist/hooks', 'dist/mcp'];
+// `dist/hooks/`, `dist/mcp/` and `dist/cli-delegate/` are listed defensively
+// in case a future change tracks them too — `git ls-files` on an untracked
+// directory returns nothing, so listing an as-yet-untracked root here is
+// always safe.
+const BUNDLE_ROOTS: readonly string[] = [
+    'dist/install',
+    'dist/hooks',
+    'dist/mcp',
+    'dist/cli-delegate',
+];
 
 interface LeakPattern {
     readonly name: string;