@event4u/agent-config 2.19.0 → 2.20.0

package/scripts/config/presets.py

@@ -0,0 +1,206 @@
+"""Preset loader — step-15 Phase 1 item 4.
+
+Resolves the active ``preset.id`` and merged knob set from the chain
+documented in :mod:`docs.contracts.config-presets`. Pure, read-only,
+lazy-PyYAML.
+
+Resolution chain (last writer wins for any single knob):
+
+1. ``pack.preset_id`` — set ``preset.id`` (Phase 2; ``None`` until packs
+   land).
+2. ``profile.preset_id`` — set ``preset.id`` if not pack-set.
+3. ``preset.<id>.yml`` — fill all knobs from the seed file.
+4. ``.agent-settings.yml`` user keys under ``preset:`` — override per-knob.
+5. Environment variables (``AGENT_CONFIG_PRESET_*``) — override per-knob,
+   structured keys mapped from the schema (see :data:`ENV_KNOB_MAP`).
+6. Runtime CLI overrides — caller passes a flat ``runtime_overrides`` map.
+
+Profile-aware overlay is **not** done here — callers that need
+profile-specific reads of preset knobs (e.g. ``block_on_risk.code_paths``
+for ``developer`` vs ``block_on_risk.financial_paths`` for ``founder``)
+read the merged knob bag returned by :func:`resolve_preset`.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from copy import deepcopy
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+PRESET_ID_ENV = "AGENT_CONFIG_PRESET_ID"
+SEED_PRESET_IDS: tuple[str, ...] = ("fast", "balanced", "strict")
+DEFAULT_PRESET_ID = "balanced"
+PRESETS_DIRNAME = ".agent-src.uncompressed/presets"
+
+SOURCE_PACK = "pack"
+SOURCE_PROFILE = "profile"
+SOURCE_USER = "user-settings"
+SOURCE_ENV = "env"
+SOURCE_RUNTIME = "runtime"
+SOURCE_DEFAULT = "default"
+
+ENV_KNOB_MAP: dict[str, tuple[str, ...]] = {
+    "AGENT_CONFIG_PRESET_COST_DAILY_MAX_USD": ("cost", "daily_max_usd"),
+    "AGENT_CONFIG_PRESET_COST_WEEKLY_MAX_USD": ("cost", "weekly_max_usd"),
+    "AGENT_CONFIG_PRESET_COST_MONTHLY_MAX_USD": ("cost", "monthly_max_usd"),
+    "AGENT_CONFIG_PRESET_MCP_PER_CALL_MAX_USD": ("mcp", "per_call_max_usd"),
+    "AGENT_CONFIG_PRESET_MCP_PER_SESSION_MAX_USD": ("mcp", "per_session_max_usd"),
+    "AGENT_CONFIG_PRESET_COUNCIL_CAP_PER_CONSULT_USD": (
+        "council",
+        "cap_per_consult_usd",
+    ),
+    "AGENT_CONFIG_PRESET_AUTONOMY_DEFAULT": ("autonomy", "default"),
+    "AGENT_CONFIG_PRESET_CONFIDENCE_MIN_BAND": ("confidence", "min_band"),
+}
+
+
+@dataclass(frozen=True)
+class ResolvedPreset:
+    """Outcome of :func:`resolve_preset`. See config-presets contract."""
+
+    id: str
+    knobs: dict[str, Any] = field(default_factory=dict)
+    source: str = SOURCE_DEFAULT
+    overrides: tuple[str, ...] = ()
+    warning: str | None = None
+
+
+class PresetError(Exception):
+    """Raised when a preset id is referenced but its YAML cannot load."""
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    try:
+        import yaml  # type: ignore[import-not-found]
+    except ImportError:
+        logger.info("PyYAML unavailable; preset %s returned empty", path)
+        return {}
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.warning("preset read failed for %s: %s", path, exc)
+        return {}
+    try:
+        data = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        logger.warning("preset parse failed for %s: %s", path, exc)
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _preset_file(project_root: Path, preset_id: str) -> Path:
+    return project_root / PRESETS_DIRNAME / f"{preset_id}.yml"
+
+
+def _coerce_scalar(raw: str) -> Any:
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    try:
+        return float(raw)
+    except ValueError:
+        pass
+    if raw.lower() in {"true", "false"}:
+        return raw.lower() == "true"
+    return raw
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> list[str]:
+    """Merge ``override`` into ``base`` in place; return dotted-override paths."""
+    paths: list[str] = []
+
+    def walk(b: dict[str, Any], o: dict[str, Any], prefix: str) -> None:
+        for key, value in o.items():
+            dotted = f"{prefix}{key}"
+            if isinstance(value, dict) and isinstance(b.get(key), dict):
+                walk(b[key], value, f"{dotted}.")
+            else:
+                b[key] = deepcopy(value)
+                paths.append(dotted)
+
+    walk(base, override, "")
+    return paths
+
+
+def _pick_id(
+    pack_preset_id: str | None,
+    profile_preset_id: str | None,
+    user_settings: dict[str, Any],
+    runtime_id: str | None,
+) -> tuple[str | None, str]:
+    if runtime_id:
+        return runtime_id, SOURCE_RUNTIME
+    env_id = os.environ.get(PRESET_ID_ENV)
+    if env_id:
+        return env_id, SOURCE_ENV
+    block = user_settings.get("preset") if isinstance(user_settings, dict) else None
+    if isinstance(block, dict) and block.get("id"):
+        return str(block["id"]), SOURCE_USER
+    if pack_preset_id:
+        return pack_preset_id, SOURCE_PACK
+    if profile_preset_id:
+        return profile_preset_id, SOURCE_PROFILE
+    return None, SOURCE_DEFAULT
+
+
+def resolve_preset(
+    *,
+    project_root: Path,
+    user_settings: dict[str, Any] | None = None,
+    pack_preset_id: str | None = None,
+    profile_preset_id: str | None = None,
+    runtime_id: str | None = None,
+    runtime_overrides: dict[tuple[str, ...], Any] | None = None,
+) -> ResolvedPreset:
+    """Return the active :class:`ResolvedPreset` for the current session."""
+    settings = user_settings or {}
+    preset_id, source = _pick_id(
+        pack_preset_id, profile_preset_id, settings, runtime_id,
+    )
+    if preset_id is None:
+        preset_id = DEFAULT_PRESET_ID
+        source = SOURCE_DEFAULT
+    yaml_path = _preset_file(project_root, preset_id)
+    if not yaml_path.exists():
+        raise PresetError(
+            f"preset.id={preset_id!r} ({source}) but {yaml_path} not found",
+        )
+    raw = _load_yaml(yaml_path)
+    knobs = raw.get("preset") or {}
+    if not isinstance(knobs, dict):
+        raise PresetError(f"{yaml_path} has no top-level 'preset:' mapping")
+    knobs = deepcopy(knobs)
+    knobs.pop("id", None)
+    overrides: list[str] = []
+    user_block = settings.get("preset") if isinstance(settings.get("preset"), dict) else None
+    if isinstance(user_block, dict):
+        user_overrides = {k: v for k, v in user_block.items() if k != "id"}
+        if user_overrides:
+            overrides.extend(_deep_merge(knobs, user_overrides))
+    for env_key, path in ENV_KNOB_MAP.items():
+        raw_value = os.environ.get(env_key)
+        if raw_value is None:
+            continue
+        cursor = knobs
+        for part in path[:-1]:
+            cursor = cursor.setdefault(part, {})
+        cursor[path[-1]] = _coerce_scalar(raw_value)
+        overrides.append(".".join(path))
+    if runtime_overrides:
+        for path, value in runtime_overrides.items():
+            cursor = knobs
+            for part in path[:-1]:
+                cursor = cursor.setdefault(part, {})
+            cursor[path[-1]] = value
+            overrides.append(".".join(path))
+    return ResolvedPreset(
+        id=preset_id,
+        knobs=knobs,
+        source=source,
+        overrides=tuple(overrides),
+    )

package/scripts/config/profiles.py

@@ -0,0 +1,173 @@
+"""Profile loader — step-15 Phase 1 item 1.
+
+Resolves the active ``profile.id`` from the chain documented in
+:mod:`docs.contracts.profile-system` and returns a structured
+:class:`ResolvedProfile`. Pure, read-only, lazy-PyYAML.
+
+Resolution chain (last writer wins):
+
+1. Pack-supplied ``profile_id`` (Phase 2 item 7 — pack loader passes it
+   in via ``pack_profile_id``; ``None`` until packs land).
+2. ``.agent-settings.yml`` top-level ``profile.id`` (and any user
+   overrides for ``audience`` / ``defaults`` / ``surface``).
+3. Environment variable ``AGENT_CONFIG_PROFILE_ID``.
+4. Runtime CLI flag — caller passes ``runtime_id``.
+
+Falls back to ``developer`` **only** when no settings file exists yet
+(fresh install before ``/onboard``). With a settings file present but
+no ``profile`` block, the loader returns a structured warning state so
+``/onboard`` can surface "audience not yet picked".
+"""
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from scripts._lib import agent_settings
+
+logger = logging.getLogger(__name__)
+
+PROFILE_ID_ENV = "AGENT_CONFIG_PROFILE_ID"
+SEED_PROFILE_IDS: tuple[str, ...] = (
+    "founder",
+    "developer",
+    "content_creator",
+    "agency",
+    "finance",
+    "ops",
+)
+DEFAULT_PROFILE_ID = "developer"
+PROFILES_DIRNAME = ".agent-src.uncompressed/profiles"
+
+SOURCE_PACK = "pack"
+SOURCE_USER = "user-settings"
+SOURCE_ENV = "env"
+SOURCE_RUNTIME = "runtime"
+SOURCE_DEFAULT = "default"
+SOURCE_MISSING = "missing"
+
+
+@dataclass(frozen=True)
+class ResolvedProfile:
+    """Outcome of :func:`resolve_profile`. See profile-system contract."""
+
+    id: str
+    audience: dict[str, str] = field(default_factory=dict)
+    preset_id: str | None = None
+    personas: tuple[str, ...] = ()
+    skills_hint: tuple[str, ...] = ()
+    commands_hint: tuple[str, ...] = ()
+    docs_first_pointer: str | None = None
+    source: str = SOURCE_DEFAULT
+    warning: str | None = None
+
+
+class ProfileError(Exception):
+    """Raised when a profile id is referenced but its YAML cannot load."""
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    try:
+        import yaml  # type: ignore[import-not-found]
+    except ImportError:
+        logger.info("PyYAML unavailable; profile %s returned empty", path)
+        return {}
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.warning("profile read failed for %s: %s", path, exc)
+        return {}
+    try:
+        data = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        logger.warning("profile parse failed for %s: %s", path, exc)
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _profile_file(project_root: Path, profile_id: str) -> Path:
+    return project_root / PROFILES_DIRNAME / f"{profile_id}.yml"
+
+
+def _build_resolved(
+    profile_id: str,
+    raw: dict[str, Any],
+    *,
+    source: str,
+    warning: str | None = None,
+) -> ResolvedProfile:
+    block = raw.get("profile") or {}
+    audience_raw = block.get("audience") or {}
+    defaults = block.get("defaults") or {}
+    surface = block.get("surface") or {}
+    audience = {str(k): str(v) for k, v in audience_raw.items()}
+    personas = tuple(str(p) for p in (defaults.get("personas") or []))
+    skills_hint = tuple(str(s) for s in (defaults.get("skills_hint") or []))
+    commands_hint = tuple(str(c) for c in (surface.get("commands_hint") or []))
+    docs_pointer = surface.get("docs_first_pointer")
+    return ResolvedProfile(
+        id=profile_id,
+        audience=audience,
+        preset_id=defaults.get("preset_id"),
+        personas=personas,
+        skills_hint=skills_hint,
+        commands_hint=commands_hint,
+        docs_first_pointer=str(docs_pointer) if docs_pointer else None,
+        source=source,
+        warning=warning,
+    )
+
+
+def _pick_id(
+    pack_profile_id: str | None,
+    user_settings: dict[str, Any],
+    runtime_id: str | None,
+) -> tuple[str | None, str]:
+    if runtime_id:
+        return runtime_id, SOURCE_RUNTIME
+    env_id = os.environ.get(PROFILE_ID_ENV)
+    if env_id:
+        return env_id, SOURCE_ENV
+    block = user_settings.get("profile") if isinstance(user_settings, dict) else None
+    if isinstance(block, dict) and block.get("id"):
+        return str(block["id"]), SOURCE_USER
+    if pack_profile_id:
+        return pack_profile_id, SOURCE_PACK
+    return None, SOURCE_MISSING
+
+
+def resolve_profile(
+    *,
+    project_root: Path,
+    user_settings: dict[str, Any] | None = None,
+    pack_profile_id: str | None = None,
+    runtime_id: str | None = None,
+) -> ResolvedProfile:
+    """Return the active :class:`ResolvedProfile` for the current session."""
+    settings = user_settings or {}
+    settings_file = project_root / agent_settings.DEFAULT_PROJECT_FILE
+    profile_id, source = _pick_id(pack_profile_id, settings, runtime_id)
+    if profile_id is None:
+        if settings_file.exists():
+            return ResolvedProfile(
+                id=DEFAULT_PROFILE_ID,
+                source=SOURCE_MISSING,
+                warning=(
+                    "no profile.id in .agent-settings.yml — run /onboard to "
+                    "pick an audience deliberately"
+                ),
+            )
+        return _build_resolved(
+            DEFAULT_PROFILE_ID,
+            _load_yaml(_profile_file(project_root, DEFAULT_PROFILE_ID)),
+            source=SOURCE_DEFAULT,
+        )
+    yaml_path = _profile_file(project_root, profile_id)
+    if not yaml_path.exists():
+        raise ProfileError(
+            f"profile.id={profile_id!r} ({source}) but {yaml_path} not found",
+        )
+    return _build_resolved(profile_id, _load_yaml(yaml_path), source=source)

package/scripts/cost/budget.mjs

@@ -14,10 +14,62 @@ import { dirname } from 'node:path';
 
 const STORE = process.env.BUDGET_STORE || 'agents/cost-tracking/sessions.jsonl';
 const CONFIG = process.env.BUDGET_CONFIG || 'agents/cost-tracking/budget.json';
+const SETTINGS = process.env.AGENT_SETTINGS || '.agent-settings.yml';
+
+// Minimal YAML reader for the `cost:` block — avoids a yaml dep. Reads
+// only the keys this script needs (cost.budgets.{daily,weekly,monthly},
+// cost.enforcement) from the well-formed two-space-indent template.
+function loadSettingsCost() {
+  if (!existsSync(SETTINGS)) return null;
+  let inCost = false, inBudgets = false;
+  const out = { budgets: {}, enforcement: null };
+  for (const raw of readFileSync(SETTINGS, 'utf-8').split('\n')) {
+    const line = raw.replace(/\s+$/, '');
+    if (!line || line.startsWith('#')) continue;
+    if (/^[a-z_]+:/.test(line)) inCost = inBudgets = false;
+    if (line === 'cost:') { inCost = true; continue; }
+    if (!inCost) continue;
+    if (/^  budgets:/.test(line)) { inBudgets = true; continue; }
+    if (inBudgets && /^    [a-z]+:/.test(line)) {
+      const [k, v] = line.trim().split(':').map((s) => s.trim());
+      const n = parseFloat(v);
+      if (Number.isFinite(n) && n > 0) out.budgets[k] = n;
+      continue;
+    }
+    if (/^  enforcement:/.test(line)) {
+      out.enforcement = line.split(':')[1].trim().replace(/['"]/g, '');
+      inBudgets = false;
+    }
+  }
+  const hasAny = Object.keys(out.budgets).length || out.enforcement;
+  return hasAny ? out : null;
+}
 
 function loadConfig() {
+  // Settings file wins when it carries any cost.* values.
+  const fromSettings = loadSettingsCost();
+  if (fromSettings) {
+    const period = process.env.BUDGET_PERIOD || 'all';
+    const periodKey = ({ today: 'daily', week: 'weekly', month: 'monthly' })[period];
+    const budget_usd = periodKey ? fromSettings.budgets[periodKey] : (
+      fromSettings.budgets.monthly || fromSettings.budgets.weekly || fromSettings.budgets.daily
+    );
+    if (Number.isFinite(budget_usd) && budget_usd > 0) {
+      return {
+        budget_usd,
+        enforcement: fromSettings.enforcement || 'advisory',
+        source: 'agent-settings.yml',
+        setAt: null,
+      };
+    }
+  }
   if (!existsSync(CONFIG)) return null;
-  try { return JSON.parse(readFileSync(CONFIG, 'utf-8')); } catch { return null; }
+  try {
+    const cfg = JSON.parse(readFileSync(CONFIG, 'utf-8'));
+    cfg.source = cfg.source || 'budget.json';
+    cfg.enforcement = cfg.enforcement || 'advisory';
+    return cfg;
+  } catch { return null; }
 }
 
 function saveConfig(cfg) {
@@ -123,18 +175,27 @@ function cmdCheck() {
     threshold: alert.threshold,
     recommended_action: recommendedAction(alert.level),
     sessionCount: filtered.length,
+    enforcement: cfg.enforcement || 'advisory',
+    source: cfg.source || 'budget.json',
   };
-  if (process.env.BUDGET_QUIET === '1') return console.log(JSON.stringify(out));
-  console.log(`# Budget check (period: ${period})\n`);
-  console.log('| Metric | Value |\n|---|---:|');
-  console.log(`| Budget | $${cfg.budget_usd.toFixed(2)} |`);
-  console.log(`| Spent | $${totalSpend.toFixed(2)} |`);
-  console.log(`| Remaining | $${out.remaining_usd.toFixed(2)} |`);
-  console.log(`| Utilization | ${out.utilization_pct.toFixed(1)}% |`);
-  console.log(`| Sessions counted | ${filtered.length} |`);
-  console.log(`| **Alert** | **${alert.emoji} ${alert.level}** |`);
-  console.log(`\nAction: ${out.recommended_action}`);
-  if (alert.level === 'HARD_STOP') process.exit(1);
+  const hardStop = alert.level === 'HARD_STOP' && out.enforcement === 'hard-stop';
+  if (process.env.BUDGET_QUIET === '1') {
+    console.log(JSON.stringify(out));
+  } else {
+    console.log(`# Budget check (period: ${period})\n`);
+    console.log('| Metric | Value |\n|---|---:|');
+    console.log(`| Budget | $${cfg.budget_usd.toFixed(2)} |`);
+    console.log(`| Spent | $${totalSpend.toFixed(2)} |`);
+    console.log(`| Remaining | $${out.remaining_usd.toFixed(2)} |`);
+    console.log(`| Utilization | ${out.utilization_pct.toFixed(1)}% |`);
+    console.log(`| Sessions counted | ${filtered.length} |`);
+    console.log(`| **Alert** | **${alert.emoji} ${alert.level}** |`);
+    console.log(`| Enforcement | ${out.enforcement} (source: ${out.source}) |`);
+    console.log(`\nAction: ${out.recommended_action}`);
+  }
+  // Only fail closed when enforcement is hard-stop; advisory mode reports
+  // the breach but exits clean so wrappers keep working.
+  if (hardStop) process.exit(1);
 }
 
 function main() {

package/scripts/cost/preflight.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Cost preflight hook — process-entry gate per ADR docs/adrs/cost/0001-hard-stop-hook.md.
+//
+// Wraps scripts/cost/budget.mjs check. Reads cost.enforcement from
+// .agent-settings.yml. Exits non-zero only when:
+//   - enforcement: hard-stop, AND
+//   - level: HARD_STOP
+//
+// Default behaviour without any budget configured: exit 0 (fail-open).
+// Designed to be invoked by shell / CI wrappers BEFORE composing a
+// turn: `task cost:preflight` or `node scripts/cost/preflight.mjs`.
+
+import { spawnSync } from 'node:child_process';
+
+const QUIET = process.env.PREFLIGHT_QUIET === '1';
+
+function runBudgetCheck() {
+  const env = { ...process.env, BUDGET_QUIET: '1' };
+  const r = spawnSync('node', ['scripts/cost/budget.mjs', 'check'], { env, encoding: 'utf-8' });
+  if (r.error) return { ok: false, fatal: true, msg: String(r.error) };
+  const out = (r.stdout || '').trim();
+  if (!out) return { ok: true, unbudgeted: true };
+  // budget.mjs prints a single JSON line under BUDGET_QUIET=1 when a
+  // budget is set; otherwise it prints a no-budget plaintext notice.
+  if (!out.startsWith('{')) return { ok: true, unbudgeted: true };
+  try {
+    const data = JSON.parse(out);
+    // budget.mjs JSON shape carries `error: 'no budget configured'`
+    // when cost.budgets are all 0 / absent — treat as unbudgeted.
+    if (data.error || !Number.isFinite(data.budget_usd)) return { ok: true, unbudgeted: true };
+    return { ok: true, data, childExit: r.status ?? 0 };
+  } catch (e) {
+    return { ok: false, fatal: true, msg: `parse: ${e.message}`, raw: out };
+  }
+}
+
+function refuse(data) {
+  if (QUIET) {
+    console.log(JSON.stringify({
+      preflight: 'refused',
+      reason: 'cost-hard-stop',
+      level: data.level,
+      utilization_pct: data.utilization_pct,
+      budget_usd: data.budget_usd,
+      spent_usd: data.spent_usd,
+      enforcement: data.enforcement,
+      source: data.source,
+    }));
+    return;
+  }
+  console.error('# 🛑 Cost preflight — HARD STOP\n');
+  console.error('| Metric | Value |');
+  console.error('|---|---:|');
+  console.error(`| Budget | $${data.budget_usd.toFixed(2)} |`);
+  console.error(`| Spent | $${data.spent_usd.toFixed(2)} |`);
+  console.error(`| Utilization | ${data.utilization_pct.toFixed(1)}% |`);
+  console.error(`| Enforcement | ${data.enforcement} (source: ${data.source}) |`);
+  console.error('\nBypass (pick one — see docs/contracts/cost-enforcement.md):');
+  console.error('  1. Raise the budget: edit .agent-settings.yml § cost.budgets.<period>');
+  console.error('  2. Reset the ledger: node scripts/cost/track.mjs reset --confirm');
+  console.error('  3. Disable enforcement: set cost.enforcement: advisory');
+}
+
+function main() {
+  const r = runBudgetCheck();
+  if (!r.ok && r.fatal) {
+    // Fail-open on infra error — never block work because the hook itself broke.
+    if (!QUIET) console.error(`# cost-preflight: skipped (${r.msg})`);
+    process.exit(0);
+  }
+  if (r.unbudgeted) {
+    if (!QUIET) console.log('# cost-preflight: no budget configured — pass.');
+    process.exit(0);
+  }
+  const d = r.data;
+  const hardStop = d.level === 'HARD_STOP' && d.enforcement === 'hard-stop';
+  if (hardStop) {
+    refuse(d);
+    process.exit(1);
+  }
+  if (!QUIET) {
+    console.log(`# cost-preflight: ${d.level} (${d.utilization_pct.toFixed(1)}% of $${d.budget_usd.toFixed(2)}, enforcement=${d.enforcement})`);
+  } else {
+    console.log(JSON.stringify({ preflight: 'pass', level: d.level, enforcement: d.enforcement, utilization_pct: d.utilization_pct }));
+  }
+  process.exit(0);
+}
+
+main();