@event4u/agent-config 2.25.0 → 3.0.0

package/scripts/_cli/explain_last/__init__.py

@@ -0,0 +1,122 @@
+"""``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/scripts/_cli/explain_last/assumptions.py

@@ -0,0 +1,59 @@
+"""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/scripts/_cli/explain_last/council.py

@@ -0,0 +1,105 @@
+"""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/scripts/_cli/explain_last/halt.py

@@ -0,0 +1,44 @@
+"""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/scripts/_cli/explain_last/inputs.py

@@ -0,0 +1,125 @@
+"""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_COST_PROFILE = "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
+    cost_profile = settings.get("cost_profile") if isinstance(settings, dict) else None
+    cost_profile_source = "user" if cost_profile else "default"
+    if not cost_profile or cost_profile == "__COST_PROFILE__":
+        cost_profile = _DEFAULT_COST_PROFILE
+        cost_profile_source = "default"
+    return {
+        "profile": scrub_string(resolved_profile.id),
+        "preset": scrub_string(resolved_preset.id),
+        "cost_profile": scrub_string(str(cost_profile)),
+        "source_per_knob": {
+            "profile": resolved_profile.source,
+            "preset": resolved_preset.source,
+            "cost_profile": cost_profile_source,
+        },
+    }
+
+
+def _pack_marker(project_root: Path) -> Path | None:
+    for candidate in (
+        project_root / ".agent-pack.yml",
+        project_root / ".agent-src.uncompressed" / ".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"]

package/scripts/_cli/explain_last/memory.py

@@ -0,0 +1,94 @@
+"""Resolve the ``memory`` why-slot for the trace.
+
+Two sources are consulted:
+
+* ``state.memory[]`` — the work-engine writes per-run memory hits here
+  during the ``memory`` step. Each entry carries ``{entry_id,
+  hit_score, used_in}`` already shaped to the trace contract.
+* ``<root>/.agent-memory/hits.jsonl`` — optional sidecar produced by
+  the memory-MCP integration. Filtered to entries tagged with the run
+  id when present.
+
+Returns ``null`` when neither source produced a non-empty list (the
+schema accepts a null memory slot so the renderer can drop the
+section cleanly).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from scripts._cli.explain_last.scrubber import scrub_string
+
+MEMORY_SIDECAR = Path(".agent-memory") / "hits.jsonl"
+
+
+def _coerce_entry(raw: dict[str, Any]) -> dict[str, Any] | None:
+    entry_id = raw.get("entry_id") or raw.get("id")
+    if not isinstance(entry_id, str) or not entry_id.strip():
+        return None
+    hit_score = raw.get("hit_score")
+    if hit_score is None:
+        hit_score = raw.get("score", 0.0)
+    try:
+        hit_score = float(hit_score)
+    except (TypeError, ValueError):
+        hit_score = 0.0
+    used_in = raw.get("used_in") or raw.get("step") or "unspecified"
+    return {
+        "entry_id": scrub_string(entry_id.strip()),
+        "hit_score": hit_score,
+        "used_in": scrub_string(str(used_in)),
+    }
+
+
+def _from_state(state: dict[str, Any]) -> list[dict[str, Any]]:
+    entries: list[dict[str, Any]] = []
+    for raw in state.get("memory", []) or []:
+        if not isinstance(raw, dict):
+            continue
+        entry = _coerce_entry(raw)
+        if entry is not None:
+            entries.append(entry)
+    return entries
+
+
+def _from_sidecar(project_root: Path, run_id: str | None) -> list[dict[str, Any]]:
+    path = project_root / MEMORY_SIDECAR
+    if not path.exists():
+        return []
+    entries: list[dict[str, Any]] = []
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                raw = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(raw, dict):
+                continue
+            if run_id and raw.get("run_id") not in (None, run_id):
+                continue
+            entry = _coerce_entry(raw)
+            if entry is not None:
+                entries.append(entry)
+    except OSError:
+        return []
+    return entries
+
+
+def build(
+    project_root: Path,
+    state: dict[str, Any],
+) -> list[dict[str, Any]] | None:
+    """Return the ``memory`` slot or ``None`` if no hits were captured."""
+    run_id = (state.get("input") or {}).get("data", {}).get("id")
+    entries = _from_state(state)
+    entries.extend(_from_sidecar(project_root, run_id if isinstance(run_id, str) else None))
+    return entries or None
+
+
+__all__ = ["build"]

package/scripts/_cli/explain_last/provider.py

@@ -0,0 +1,52 @@
+"""Builder for the ``trace.provider`` slot.
+
+Bounded to video runs (``state.directive_set == "video"``). The
+work_engine does not yet ship a video directive set — this builder is
+forward-compatible: when the engine eventually persists a provider
+selection (``state.video_provider`` or
+``state.contract.video_provider`` are both accepted shapes), the slot
+populates; otherwise it returns ``None``.
+
+The v1 schema requires ``{id, selection_reason}``. Both fields pass
+through :func:`scripts._cli.explain_last.scrubber.scrub_string` so a
+reason explaining "selected because user has $40/m budget on
+provider-x.internal" never leaks billing or hostnames.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from scripts._cli.explain_last.scrubber import scrub_string
+
+
+def _extract(state: dict[str, Any]) -> dict[str, Any] | None:
+    direct = state.get("video_provider")
+    if isinstance(direct, dict):
+        return direct
+    contract = state.get("contract")
+    if isinstance(contract, dict):
+        nested = contract.get("video_provider")
+        if isinstance(nested, dict):
+            return nested
+    return None
+
+
+def build(state: dict[str, Any]) -> dict[str, Any] | None:
+    if (state.get("directive_set") or "") != "video":
+        return None
+    payload = _extract(state)
+    if payload is None:
+        return None
+    pid = payload.get("id")
+    reason = payload.get("selection_reason")
+    if not isinstance(pid, str) or not pid:
+        return None
+    if not isinstance(reason, str) or not reason:
+        reason = ""
+    return {
+        "id": scrub_string(pid),
+        "selection_reason": scrub_string(reason),
+    }
+
+
+__all__ = ["build"]

package/scripts/_cli/explain_last/render.py

@@ -0,0 +1,52 @@
+"""Deterministic Markdown projection of an :class:`ExplainTrace`.
+
+Pure-function ``render(trace) -> str``. Same input ``ExplainTrace``
+always yields byte-identical Markdown — Phase 4 snapshot tests rely on
+this. Each section lives in its own module under :mod:`sections/`; the
+orchestrator only fixes the order. Phase 3 wired ``halt`` and
+``provider`` sections; ``halt`` always renders (clean / dirty branch
+both deterministic), ``provider`` emits an empty string on non-video
+runs so the orchestrator drops it silently.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from scripts._cli.explain_last import sections
+
+_SECTION_ORDER = (
+    sections.header,
+    sections.route,
+    sections.inputs,
+    sections.memory,
+    sections.council,
+    sections.halt,
+    sections.provider,
+    sections.assumptions,
+    sections.pack,
+)
+
+TIP_FOOTER = (
+    "_tip: pass `--json` to emit machine-readable trace; "
+    "`--quiet` to drop this footer._\n"
+)
+
+
+def render(trace: dict[str, Any], *, with_footer: bool = True) -> str:
+    """Render ``trace`` to Markdown.
+
+    ``with_footer=False`` suppresses the trailing tip line (council
+    fix: CI scripts parse the output and choke on a stray footer).
+    """
+    parts: list[str] = []
+    for section in _SECTION_ORDER:
+        chunk = section.render(trace)
+        if chunk:
+            parts.append(chunk)
+    body = "\n".join(parts).rstrip() + "\n"
+    if with_footer:
+        body += "\n" + TIP_FOOTER
+    return body
+
+
+__all__ = ["TIP_FOOTER", "render"]