@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/_cli/cmd_versions.py

@@ -1,160 +0,0 @@
-"""``agent-config versions`` — list available package versions (Phase 4.1).
-
-Queries the npm registry for available versions of
-``@event4u/agent-config`` and prints them. Marks the current pin
-(from ``.agent-settings.yml`` ``agent_config_version``) and the latest
-published version.
-
-Offline-tolerant: when ``--offline`` is passed or the registry is
-unreachable, falls back to reading the local ``package.json`` version
-and prints a single-line notice instead of failing.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-from scripts._lib.agent_settings import project_settings_path, resolve_project_root
-
-PACKAGE_NAME = "@event4u/agent-config"
-
-
-def _project_root() -> Path:
-    """Resolve the consumer project root via the Phase-3 helper.
-
-    Honors ``AGENT_CONFIG_PROJECT_ROOT`` and the Step-7 anchor walk so
-    ``agent-config versions`` invoked from a subdir reads the correct
-    ``.agent-settings.yml`` / ``package.json``.
-    """
-    root, _ = resolve_project_root(None)
-    return root
-
-
-def _local_package_version() -> str:
-    """Return ``version`` from the local ``package.json``, or ``""`` if absent."""
-    candidates = [
-        Path(__file__).resolve().parents[3] / "package.json",
-        _project_root() / "package.json",
-    ]
-    for p in candidates:
-        if p.exists():
-            try:
-                return str(json.loads(p.read_text()).get("version", ""))
-            except (json.JSONDecodeError, OSError):
-                continue
-    return ""
-
-
-def _pinned_version() -> str:
-    """Return the ``agent_config_version`` pin from ``.agent-settings.yml``."""
-    settings = project_settings_path(_project_root())
-    if not settings.exists():
-        return ""
-    try:
-        for line in settings.read_text(encoding="utf-8").splitlines():
-            line = line.strip()
-            if line.startswith("agent_config_version"):
-                _, _, rhs = line.partition(":")
-                return rhs.strip().strip('"').strip("'")
-    except OSError:
-        pass
-    return ""
-
-
-def _query_npm() -> list[str]:
-    """Run ``npm view <pkg> versions --json``; return parsed list or ``[]``."""
-    try:
-        proc = subprocess.run(
-            ["npm", "view", PACKAGE_NAME, "versions", "--json"],
-            capture_output=True, text=True, timeout=15,
-        )
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        return []
-    if proc.returncode != 0:
-        return []
-    try:
-        data = json.loads(proc.stdout)
-    except json.JSONDecodeError:
-        return []
-    if isinstance(data, str):
-        return [data]
-    if isinstance(data, list):
-        return [str(v) for v in data]
-    return []
-
-
-def _format_table(versions: list[str], current: str, pinned: str, limit: int) -> str:
-    rows: list[str] = []
-    head = versions[-limit:] if limit > 0 else versions
-    for v in head:
-        marks = []
-        if v == pinned:
-            marks.append("← pinned")
-        if v == current:
-            marks.append("← latest")
-        suffix = ("  " + " ".join(marks)) if marks else ""
-        rows.append(f"  {v}{suffix}")
-    return "\n".join(rows)
-
-
-def _parse(argv: list[str]) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        prog="agent-config versions",
-        description="List available @event4u/agent-config versions on npm.",
-    )
-    parser.add_argument("--offline", action="store_true",
-                        help="skip npm registry query; only show local package + pin")
-    parser.add_argument("--limit", type=int, default=20,
-                        help="show only the N most recent versions (default: 20; 0 = all)")
-    parser.add_argument("--json", dest="as_json", action="store_true",
-                        help="machine-readable output: {pinned, local, latest, versions[]}")
-    return parser.parse_args(argv)
-
-
-def main(argv: list[str] | None = None) -> int:
-    opts = _parse(list(argv) if argv is not None else sys.argv[1:])
-
-    # AGENT_CONFIG_OFFLINE=1 (set by `install.py --offline`) is honored
-    # as a global kill-switch even when the per-command --offline flag
-    # is absent. Keeps the env-driven offline contract consistent.
-    offline = opts.offline or os.environ.get("AGENT_CONFIG_OFFLINE") == "1"
-
-    local = _local_package_version()
-    pinned = _pinned_version()
-    versions: list[str] = []
-    if not offline:
-        versions = _query_npm()
-    latest = versions[-1] if versions else local
-
-    if opts.as_json:
-        print(json.dumps({
-            "pinned": pinned,
-            "local": local,
-            "latest": latest,
-            "versions": versions,
-            "source": "npm" if versions else "local",
-        }, indent=2))
-        return 0
-
-    print(f"package: {PACKAGE_NAME}")
-    print(f"pinned:  {pinned or '— (no .agent-settings.yml)'}")
-    print(f"local:   {local or '—'}")
-    if not versions:
-        if offline:
-            print("offline mode — registry query skipped")
-        else:
-            print("⚠️   npm registry unreachable; showing local only")
-        return 0
-    print(f"latest:  {latest}")
-    print()
-    print(f"available versions ({'last ' + str(opts.limit) if opts.limit > 0 else 'all'}):")
-    print(_format_table(versions, latest, pinned, opts.limit))
-    return 0
-
-
-if __name__ == "__main__":  # pragma: no cover
-    raise SystemExit(main())

package/src/scripts/_cli/explain_last/__init__.py

@@ -1,122 +0,0 @@
-"""``agent-config explain last`` — execution-trace builder.
-
-Phase 2 of the *Explainability v2* roadmap
-(``agents/roadmaps/explainability-v2-explain-last.md``). Reads the
-persisted :mod:`work_engine` state plus its sibling artefacts (council
-sessions, memory hits, router snapshot) and projects them into the
-versioned :data:`ExplainTrace` v1 contract documented at
-``docs/contracts/explain-trace.schema.json``.
-
-Read-only by construction:
-
-* never writes back to disk;
-* never opens a network socket (Phase 4 enforces via ``test_no_network``);
-* never raises on missing data — every slot degrades to ``null`` and the
-  Markdown renderer emits a ``(none)`` placeholder instead.
-
-The public surface is :func:`build_trace`. Everything else is internal
-plumbing. The CLI dispatcher lives in :mod:`scripts._cli.cmd_explain`
-and is the only intended caller besides the test suite.
-"""
-from __future__ import annotations
-
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any
-
-from scripts._cli.explain_last import (
-    assumptions as _assumptions,
-    council as _council,
-    halt as _halt,
-    inputs as _inputs,
-    memory as _memory,
-    provider as _provider,
-    route as _route,
-)
-from scripts._cli.explain_last.scrubber import scrub_string
-from scripts._cli.explain_last.state_loader import StateLoadError, load_state
-
-TRACE_VERSION = 1
-SUBJECT_BY_KIND = {
-    "ticket": "implement-ticket",
-    "prompt": "work",
-    "diff": "work",
-    "file": "work",
-}
-
-
-def _derive_subject(state: dict[str, Any]) -> str:
-    """Map ``state.input.kind`` + ``state.directive_set`` to a trace subject.
-
-    The schema enum is ``work | implement-ticket | council | video |
-    unknown``. ``council`` and ``video`` are reserved for Phase 3 and
-    forward; today they only fire when the engine explicitly stamps the
-    directive set, never from a kind alone.
-    """
-    directive_set = state.get("directive_set") or ""
-    if directive_set == "video":
-        return "video"
-    if directive_set == "council":
-        return "council"
-    kind = (state.get("input") or {}).get("kind")
-    return SUBJECT_BY_KIND.get(kind or "", "unknown")
-
-
-def _derive_run_id(state: dict[str, Any], state_file: Path) -> str:
-    """Pull ``state.input.data.id`` with mtime fallback.
-
-    Schema requires a non-empty string; the file mtime serialised as
-    ISO-8601 UTC is the documented fallback. Both branches return scrub
-    pre-processed values so a ticket id containing PII never leaks.
-    """
-    data = (state.get("input") or {}).get("data") or {}
-    raw_id = data.get("id")
-    if isinstance(raw_id, str) and raw_id.strip():
-        return scrub_string(raw_id.strip())
-    try:
-        mtime = state_file.stat().st_mtime
-    except OSError:
-        mtime = 0.0
-    return datetime.fromtimestamp(mtime, tz=timezone.utc).isoformat()
-
-
-def build_trace(
-    project_root: Path,
-    state_file: Path,
-    *,
-    now: datetime | None = None,
-) -> dict[str, Any]:
-    """Aggregate every why-slot for the most recent ``/work`` run.
-
-    Returns a JSON-serialisable dict that conforms to
-    ``explain-trace.schema.json``. ``now`` is only injected by the test
-    harness; the production caller passes ``None`` and gets the wall
-    clock. All free-form strings pass through :func:`scrub_string`
-    before being placed in the output (FATAL council fix — see roadmap
-    § "External AI-Council pass").
-    """
-    state = load_state(state_file)
-    generated_at = (now or datetime.now(tz=timezone.utc)).isoformat()
-    return {
-        "version": TRACE_VERSION,
-        "generated_at": generated_at,
-        "run_id": _derive_run_id(state, state_file),
-        "subject": _derive_subject(state),
-        "inputs": _inputs.build(project_root),
-        "route": _route.build(project_root, state),
-        "council": _council.build(project_root, state_file),
-        "memory": _memory.build(project_root, state),
-        "pack": _inputs.build_pack(project_root),
-        "assumptions": _assumptions.build(state),
-        "halt": _halt.build(state),
-        "provider": _provider.build(state),
-    }
-
-
-__all__ = [
-    "TRACE_VERSION",
-    "StateLoadError",
-    "build_trace",
-    "load_state",
-    "scrub_string",
-]

package/src/scripts/_cli/explain_last/assumptions.py

@@ -1,59 +0,0 @@
-"""Resolve the ``assumptions`` why-slot for the trace.
-
-The work-engine writes ``state.input.data.assumptions[]`` at the end
-of the ``refine`` step and on every ``halt``. Each entry is either a
-plain string (legacy shape) or a dict with ``{id, accepted, source}``
-(R2+ shape). Both shapes are normalised here so the schema gate sees a
-uniform list of objects.
-"""
-from __future__ import annotations
-
-from typing import Any
-
-from scripts._cli.explain_last.scrubber import scrub_string
-
-
-def _normalise(raw: Any, fallback_idx: int) -> dict[str, Any] | None:
-    if isinstance(raw, str):
-        text = raw.strip()
-        if not text:
-            return None
-        return {
-            "id": scrub_string(text)[:120] or f"assumption-{fallback_idx}",
-            "accepted": True,
-            "source": "refine",
-        }
-    if isinstance(raw, dict):
-        ident = raw.get("id") or raw.get("text") or f"assumption-{fallback_idx}"
-        if not isinstance(ident, str):
-            ident = str(ident)
-        ident = scrub_string(ident.strip()) or f"assumption-{fallback_idx}"
-        accepted = bool(raw.get("accepted", True))
-        source = raw.get("source") or raw.get("step") or "refine"
-        return {
-            "id": ident,
-            "accepted": accepted,
-            "source": scrub_string(str(source)),
-        }
-    return None
-
-
-def build(state: dict[str, Any]) -> list[dict[str, Any]]:
-    """Return the assumptions list (possibly empty).
-
-    Schema requires an array; ``null`` is not allowed. An empty list
-    is the documented signal that no assumptions were captured.
-    """
-    data = (state.get("input") or {}).get("data") or {}
-    raw_list = data.get("assumptions") or []
-    if not isinstance(raw_list, list):
-        return []
-    out: list[dict[str, Any]] = []
-    for idx, raw in enumerate(raw_list):
-        entry = _normalise(raw, idx)
-        if entry is not None:
-            out.append(entry)
-    return out
-
-
-__all__ = ["build"]

package/src/scripts/_cli/explain_last/council.py

@@ -1,105 +0,0 @@
-"""Resolve the ``council`` why-slot for the trace.
-
-Picks the most recent ``council-responses.json`` whose ``mtime`` lies
-within the run window (state file mtime ± 1h). Cost-metadata fields
-(``input_tokens``, ``output_tokens``, ``cost_usd``, ``latency_ms``) are
-intentionally NOT surfaced — they leak business-intelligence about
-spend rate per the security-engineer council fix.
-"""
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import Any
-
-from scripts._cli.explain_last.scrubber import scrub_string
-
-RUN_WINDOW_SECONDS = 3600
-
-
-def _candidate_files(project_root: Path) -> list[Path]:
-    """Return every council-response file the loader knows about.
-
-    Implementation spec for the council loader; the glob path is the
-    contract it implements.
-    """
-    # council-ref-allowed: council loader implementation per roadmap.
-    sessions_root = project_root / "agents" / "runtime" / "council" / "sessions"
-    tmp_root = project_root / "tmp"
-    candidates: list[Path] = []
-    if sessions_root.exists():
-        for sub in sessions_root.iterdir():
-            if sub.is_dir():
-                candidate = sub / "council-responses.json"
-                if candidate.exists():
-                    candidates.append(candidate)
-    if tmp_root.exists():
-        candidates.extend(sorted(tmp_root.glob("council-*.json")))
-    return candidates
-
-
-def _pick_recent(candidates: list[Path], anchor_mtime: float) -> Path | None:
-    best: tuple[float, Path] | None = None
-    for path in candidates:
-        try:
-            mtime = path.stat().st_mtime
-        except OSError:
-            continue
-        if abs(mtime - anchor_mtime) > RUN_WINDOW_SECONDS:
-            continue
-        if best is None or mtime > best[0]:
-            best = (mtime, path)
-    return best[1] if best else None
-
-
-def _extract_member(entry: dict[str, Any]) -> dict[str, Any] | None:
-    provider = entry.get("provider") or ""
-    model = entry.get("model") or ""
-    member_id = "/".join(part for part in (provider, model) if part) or "unknown"
-    text = entry.get("text")
-    if not isinstance(text, str) or not text.strip():
-        return None
-    verdict = scrub_string(text.strip().splitlines()[0][:200])
-    citations = []
-    for cite in entry.get("citations", []) or []:
-        if isinstance(cite, str):
-            citations.append(scrub_string(cite))
-    return {
-        "member_id": scrub_string(member_id),
-        "verdict": verdict,
-        "citations": citations,
-    }
-
-
-def build(
-    project_root: Path,
-    state_file: Path,
-) -> list[dict[str, Any]] | None:
-    """Return the ``council`` slot or ``None`` if no session matches."""
-    try:
-        anchor = state_file.stat().st_mtime
-    except OSError:
-        return None
-    candidates = _candidate_files(project_root)
-    if not candidates:
-        return None
-    picked = _pick_recent(candidates, anchor)
-    if picked is None:
-        return None
-    try:
-        raw = json.loads(picked.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return None
-    if not isinstance(raw, dict):
-        return None
-    members: list[dict[str, Any]] = []
-    for entry in raw.get("responses", []) or []:
-        if not isinstance(entry, dict):
-            continue
-        member = _extract_member(entry)
-        if member is not None:
-            members.append(member)
-    return members or None
-
-
-__all__ = ["build"]

package/src/scripts/_cli/explain_last/halt.py

@@ -1,44 +0,0 @@
-"""Builder for the ``trace.halt`` slot.
-
-Reads ``state.halts[]`` (the append-only halt log persisted by
-:mod:`work_engine.emitters._emit_halt`) and projects the most recent
-entry into the v1 explain-trace shape: ``{reason, step, surface}``.
-
-Returns ``None`` when the engine never halted (clean run) or when the
-state file predates the halts-bearing schema (forward-compatible read:
-older state files just omit the key). Free-form strings pass through
-:func:`scripts._cli.explain_last.scrubber.scrub_string` so PII or
-cost-metadata leakage from halt surfaces never escapes the trace.
-"""
-from __future__ import annotations
-
-from typing import Any
-
-from scripts._cli.explain_last.scrubber import scrub_string
-
-
-def build(state: dict[str, Any]) -> dict[str, Any] | None:
-    halts = state.get("halts") or []
-    if not isinstance(halts, list) or not halts:
-        return None
-    last = halts[-1]
-    if not isinstance(last, dict):
-        return None
-    reason = last.get("reason")
-    if not isinstance(reason, str) or not reason:
-        return None
-    step = last.get("step")
-    surface = last.get("surface") or []
-    scrubbed_surface: list[str] = []
-    if isinstance(surface, list):
-        for line in surface:
-            if isinstance(line, str):
-                scrubbed_surface.append(scrub_string(line))
-    return {
-        "reason": scrub_string(reason),
-        "step": scrub_string(step) if isinstance(step, str) and step else "",
-        "surface": scrubbed_surface,
-    }
-
-
-__all__ = ["build"]

package/src/scripts/_cli/explain_last/inputs.py

@@ -1,128 +0,0 @@
-"""Resolve the ``inputs`` and ``pack`` why-slots for the trace.
-
-Reuses :mod:`scripts.config.profiles` and :mod:`scripts.config.presets`
-so the rendered chain matches what the runtime loader actually
-consulted (no parallel logic — the v1 ``explain config`` surface
-already covers this and we read through the same resolvers).
-"""
-from __future__ import annotations
-
-import logging
-from contextlib import contextmanager
-from pathlib import Path
-from typing import Any
-
-from scripts._cli.explain_last.scrubber import scrub_string
-from scripts._lib.agent_settings import DEFAULT_PROJECT_FILE, load_agent_settings
-from scripts.config import presets, profiles
-
-_DEFAULT_RULE_LOADING_TIER = "balanced"
-_SILENCED_LOGGERS = ("scripts.config.profiles", "scripts.config.presets")
-
-
-@contextmanager
-def _silence_resolver_warnings():
-    # Profile / preset loggers emit absolute paths on read failure;
-    # the explain trace must never leak them. Failures bubble up via
-    # ProfileError / PresetError anyway, so the warning has no signal.
-    previous: list[tuple[logging.Logger, int]] = []
-    for name in _SILENCED_LOGGERS:
-        log = logging.getLogger(name)
-        previous.append((log, log.level))
-        log.setLevel(logging.ERROR)
-    try:
-        yield
-    finally:
-        for log, level in previous:
-            log.setLevel(level)
-
-
-def _load_settings(project_root: Path) -> dict[str, Any]:
-    path = project_root / DEFAULT_PROJECT_FILE
-    if not path.exists():
-        return {}
-    return load_agent_settings(project_path=path) or {}
-
-
-def build(project_root: Path) -> dict[str, Any] | None:
-    """Return the ``inputs`` slot or ``None`` on broken settings.
-
-    Each knob carries its source (``pack | profile | preset | user |
-    env | runtime | default``) so the renderer's table can attribute
-    the value to the layer that won the resolution race.
-    """
-    try:
-        with _silence_resolver_warnings():
-            settings = _load_settings(project_root)
-            resolved_profile = profiles.resolve_profile(
-                project_root=project_root,
-                user_settings=settings,
-            )
-            resolved_preset = presets.resolve_preset(
-                project_root=project_root,
-                user_settings=settings,
-                profile_preset_id=resolved_profile.preset_id,
-            )
-    except (profiles.ProfileError, presets.PresetError, OSError):
-        return None
-    rule_loading_tier = (
-        (settings.get("rule_loading_tier") or settings.get("cost_profile"))
-        if isinstance(settings, dict) else None
-    )
-    rule_loading_tier_source = "user" if rule_loading_tier else "default"
-    if not rule_loading_tier or rule_loading_tier == "__RULE_LOADING_TIER__":
-        rule_loading_tier = _DEFAULT_RULE_LOADING_TIER
-        rule_loading_tier_source = "default"
-    return {
-        "profile": scrub_string(resolved_profile.id),
-        "preset": scrub_string(resolved_preset.id),
-        "rule_loading_tier": scrub_string(str(rule_loading_tier)),
-        "source_per_knob": {
-            "profile": resolved_profile.source,
-            "preset": resolved_preset.source,
-            "rule_loading_tier": rule_loading_tier_source,
-        },
-    }
-
-
-def _pack_marker(project_root: Path) -> Path | None:
-    for candidate in (
-        project_root / ".agent-pack.yml",
-        project_root / ".agent-src.uncondensed" / ".agent-pack.yml",
-    ):
-        if candidate.exists():
-            return candidate
-    return None
-
-
-def build_pack(project_root: Path) -> dict[str, Any] | None:
-    """Return the active workspace pack or ``None``.
-
-    The discovery pipeline (R3) writes a ``.agent-pack.yml`` marker
-    when a pack is bound to the project. We surface only the id and a
-    short reason; pack-internal payloads stay invisible to the trace.
-    """
-    marker = _pack_marker(project_root)
-    if marker is None:
-        return None
-    try:
-        import yaml  # type: ignore[import-not-found]
-    except ImportError:
-        return None
-    try:
-        raw = yaml.safe_load(marker.read_text(encoding="utf-8")) or {}
-    except (OSError, yaml.YAMLError):
-        return None
-    if not isinstance(raw, dict):
-        return None
-    pack_id = raw.get("id") or raw.get("pack")
-    if not isinstance(pack_id, str) or not pack_id.strip():
-        return None
-    reason = raw.get("reason") or f"declared in {marker.name}"
-    return {
-        "id": scrub_string(pack_id.strip()),
-        "reason": scrub_string(str(reason)),
-    }
-
-
-__all__ = ["build", "build_pack"]