@event4u/agent-config 1.13.0 → 1.14.0

package/.agent-src/templates/scripts/telemetry_report.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""``./agent-config telemetry:report`` — aggregate the engagement log.
+
+Reads ``.agent-engagement.jsonl``, groups events by ``(kind, id)``,
+quartile-buckets the artefacts (essential / useful / retirement
+candidate), and prints a markdown table or JSON document.
+
+Usage:
+    # Defaults: --since 30d --top 20 markdown
+    ./agent-config telemetry:report
+
+    # Last 7 days, JSON, no truncation
+    ./agent-config telemetry:report --since 7d --format json --top 0
+
+    # Override log path (tests; consumer copies; reports on archived logs)
+    ./agent-config telemetry:report --log-path /tmp/snapshot.jsonl
+
+Exit codes:
+    0   success (empty log → empty-but-valid report)
+    2   IO / settings parse error, unparseable --since, or
+        redaction-validator failure on a row sourced from the log
+        (a path-shaped or extension-shaped id slipped past the write
+        gate; the report is refused rather than shared)
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from telemetry.aggregator import aggregate
+from telemetry.engagement import EngagementSchemaError
+from telemetry.report_renderer import render_json, render_markdown
+from telemetry.settings import read_settings
+
+_DURATION_RE = re.compile(r"^\s*(\d+)\s*([dhm])\s*$")
+
+
+def _parse_since(value: str | None) -> tuple[datetime | None, str | None]:
+    """Parse ``30d`` / ``7d`` / ``24h`` / ``60m`` into a UTC cutoff.
+
+    Returns ``(cutoff_or_None, human_label)``. ``value`` of ``None`` or
+    ``"all"`` means "no lower bound" — both cutoff and label are
+    ``None``. Raises ``ValueError`` on malformed input so the CLI can
+    surface a clean error and exit 2.
+    """
+    if value is None or value.strip().lower() == "all":
+        return None, None
+    match = _DURATION_RE.match(value)
+    if not match:
+        raise ValueError(
+            f"--since must be <int>{{d,h,m}} or 'all', got {value!r}"
+        )
+    qty = int(match.group(1))
+    unit = match.group(2)
+    delta = {
+        "d": timedelta(days=qty),
+        "h": timedelta(hours=qty),
+        "m": timedelta(minutes=qty),
+    }[unit]
+    cutoff = datetime.now(tz=timezone.utc) - delta
+    label = f"last {qty}{unit}"
+    return cutoff, label
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-config telemetry:report",
+        description=(
+            "Render an artefact-engagement report from the JSONL log. "
+            "Read-only; never mutates settings or the log."
+        ),
+    )
+    parser.add_argument(
+        "--since",
+        default="30d",
+        help=(
+            "Lower-bound time window: <int>{d,h,m} or 'all'. "
+            "Default: 30d. Events at or before the cutoff are excluded."
+        ),
+    )
+    parser.add_argument(
+        "--top",
+        type=int,
+        default=20,
+        help=(
+            "Truncate each bucket to N rows. Default: 20. Use 0 to "
+            "disable truncation."
+        ),
+    )
+    parser.add_argument(
+        "--format",
+        choices=("markdown", "json"),
+        default="markdown",
+    )
+    parser.add_argument(
+        "--log-path",
+        type=Path,
+        default=None,
+        help=(
+            "Override the log path. Default: read "
+            "telemetry.artifact_engagement.output.path from "
+            ".agent-settings.yml (falls back to .agent-engagement.jsonl)."
+        ),
+    )
+    parser.add_argument(
+        "--settings",
+        type=Path,
+        default=Path(".agent-settings.yml"),
+        help="Override settings path (tests).",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        cutoff, since_label = _parse_since(args.since)
+    except ValueError as exc:
+        print(f"❌  {exc}", file=sys.stderr)
+        return 2
+
+    if args.log_path is not None:
+        log_path = args.log_path
+    else:
+        try:
+            settings = read_settings(args.settings)
+        except OSError as exc:
+            print(f"❌  cannot read settings: {exc}", file=sys.stderr)
+            return 2
+        log_path = settings.log_path
+
+    try:
+        result = aggregate(log_path, since=cutoff)
+    except OSError as exc:
+        print(f"❌  cannot read log {log_path}: {exc}", file=sys.stderr)
+        return 2
+
+    top = None if args.top <= 0 else args.top
+    try:
+        if args.format == "json":
+            rendered = render_json(result, top=top, since_label=since_label)
+        else:
+            rendered = render_markdown(result, top=top, since_label=since_label)
+    except EngagementSchemaError as exc:
+        print(
+            f"❌  redaction validator refused report: {exc}",
+            file=sys.stderr,
+        )
+        return 2
+    sys.stdout.write(rendered)
+
+    if result.skipped_lines:
+        print(
+            f"⚠️   skipped {result.skipped_lines} malformed line(s)",
+            file=sys.stderr,
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.agent-src/templates/scripts/telemetry_status.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""``./agent-config telemetry:status`` — read-only status report.
+
+Prints the current ``telemetry.artifact_engagement`` configuration
+plus log statistics. Safe even when telemetry is disabled — never
+creates the log, never validates, never writes. ``--format json`` is
+the machine-readable contract.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from telemetry.engagement import EngagementSchemaError, parse_event
+from telemetry.settings import TelemetrySettings, read_settings
+
+
+def _last_event_ts(log_path: Path) -> str | None:
+    """Return the ``ts`` of the last well-formed event, or None.
+
+    Reads from the tail to keep the cost bounded on long logs. We
+    skip malformed lines silently — Phase 4 surfaces those via the
+    aggregator's ``--strict`` flag.
+    """
+    if not log_path.is_file():
+        return None
+    try:
+        with log_path.open("rb") as fh:
+            fh.seek(0, 2)  # EOF
+            size = fh.tell()
+            chunk_size = min(size, 4096)
+            fh.seek(size - chunk_size)
+            tail = fh.read().decode("utf-8", errors="replace")
+    except OSError:
+        return None
+    for line in reversed(tail.splitlines()):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = parse_event(line + "\n")
+        except EngagementSchemaError:
+            continue
+        return event.ts
+    return None
+
+
+def _log_stats(log_path: Path) -> dict[str, Any]:
+    if not log_path.is_file():
+        return {"exists": False, "size_bytes": 0, "line_count": 0}
+    try:
+        size = log_path.stat().st_size
+        with log_path.open("rb") as fh:
+            line_count = sum(1 for _ in fh)
+    except OSError as exc:
+        return {"exists": True, "error": str(exc)}
+    return {"exists": True, "size_bytes": size, "line_count": line_count}
+
+
+def _build_report(settings: TelemetrySettings) -> dict[str, Any]:
+    log_path = settings.log_path
+    return {
+        "enabled": settings.enabled,
+        "section_present": settings.section_present,
+        "granularity": settings.granularity,
+        "record": {
+            "consulted": settings.record_consulted,
+            "applied": settings.record_applied,
+        },
+        "log": {
+            "path": str(log_path),
+            **_log_stats(log_path),
+            "last_event_ts": _last_event_ts(log_path),
+        },
+    }
+
+
+def _render_text(report: dict[str, Any]) -> str:
+    lines: list[str] = []
+    enabled = "✅  enabled" if report["enabled"] else "⛔  disabled"
+    if not report["section_present"]:
+        enabled += " (no telemetry section in .agent-settings.yml — using defaults)"
+    lines.append(f"  artifact-engagement: {enabled}")
+    lines.append(f"  granularity:         {report['granularity']}")
+    rec = report["record"]
+    lines.append(
+        f"  record:              consulted={rec['consulted']} "
+        f"applied={rec['applied']}"
+    )
+    log = report["log"]
+    lines.append(f"  log path:            {log['path']}")
+    if log.get("exists"):
+        if "error" in log:
+            lines.append(f"  log error:           {log['error']}")
+        else:
+            lines.append(
+                f"  log size:            {log['size_bytes']} bytes "
+                f"({log['line_count']} events)"
+            )
+            if log.get("last_event_ts"):
+                lines.append(f"  last event ts:       {log['last_event_ts']}")
+    else:
+        lines.append("  log:                 not yet created")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-config telemetry:status",
+        description=(
+            "Print the artifact-engagement telemetry status. Read-only "
+            "— never creates the log, never modifies settings."
+        ),
+    )
+    parser.add_argument("--format", choices=("text", "json"), default="text")
+    parser.add_argument(
+        "--settings",
+        type=Path,
+        default=Path(".agent-settings.yml"),
+        help="Override settings path (tests).",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        settings = read_settings(args.settings)
+    except OSError as exc:
+        print(f"❌  cannot read settings: {exc}", file=sys.stderr)
+        return 2
+
+    report = _build_report(settings)
+    if args.format == "json":
+        print(json.dumps(report, sort_keys=True, indent=2))
+    else:
+        print(_render_text(report))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.agent-src/templates/scripts/work_engine/__init__.py

@@ -0,0 +1,58 @@
+"""``work_engine`` — universal execution engine (R1).
+
+The package owns the linear step dispatcher that drives
+``/implement-ticket`` and any future intent-routed flow. Phase 2 added
+the persistent ``state`` schema and the v0→v1 migration; Phase 3 moves
+the dispatcher, CLI and step modules over from the legacy
+``implement_ticket`` package — which is now a thin compatibility shim
+that re-exports from here with a ``DeprecationWarning``.
+
+Architectural constraints (from
+``agents/contexts/adr-implement-ticket-runtime.md`` and
+``agents/contexts/implement-ticket-flow.md``):
+
+- Runtime is Python 3.10+.
+- The dispatcher is linear, not a DAG. Eight fixed steps, fixed order.
+- ``DeliveryState`` is the only object shared between steps — no
+  hidden state, no side channels.
+- Every step terminates in ``success | blocked | partial``. ``blocked``
+  and ``partial`` halt the flow and surface numbered questions.
+- The dispatcher never calls git, writes commits, or opens PRs.
+"""
+from __future__ import annotations
+
+from .delivery_state import (
+    AGENT_DIRECTIVE_PREFIX,
+    DeliveryState,
+    Outcome,
+    Step,
+    StepResult,
+    agent_directive,
+    is_agent_directive,
+)
+from .cli import DEFAULT_STATE_FILE, main
+from .dispatcher import STEP_ORDER, dispatch
+from .persona_policy import (
+    DEFAULT_PERSONA,
+    PersonaPolicy,
+    known_personas,
+    resolve_policy,
+)
+
+__all__ = [
+    "AGENT_DIRECTIVE_PREFIX",
+    "DEFAULT_PERSONA",
+    "DEFAULT_STATE_FILE",
+    "DeliveryState",
+    "Outcome",
+    "PersonaPolicy",
+    "STEP_ORDER",
+    "Step",
+    "StepResult",
+    "agent_directive",
+    "dispatch",
+    "is_agent_directive",
+    "known_personas",
+    "main",
+    "resolve_policy",
+]

package/.agent-src/templates/scripts/work_engine/__main__.py

@@ -0,0 +1,9 @@
+"""Module entry point — lets ``python3 -m implement_ticket`` run the CLI."""
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())