@event4u/agent-config 6.1.0 → 7.0.0

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

@@ -1,161 +0,0 @@
-#!/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/dist/agent-src/templates/scripts/telemetry_status.py

@@ -1,142 +0,0 @@
-#!/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/dist/agent-src/templates/scripts/tier_usage_report.py

@@ -1,183 +0,0 @@
-#!/usr/bin/env python3
-"""Tier-usage report — aggregate the local tier-usage log into a frequency table.
-
-Phase 5 Step 3 of road-to-surface-discipline. Reads the JSONL log
-written by the dispatcher (default ``.agent-tier-usage.jsonl``; override
-via ``telemetry.tier_usage.output.path``) and emits a per-command
-frequency table grouped by tier, plus distinct ``user_hash`` counts.
-Run-local-only; no upload, no remote aggregation.
-
-Privacy floor mirrors the contract in
-``docs/contracts/command-clusters.md#tier-usage-signal-contract`` and
-the four-layer enforcement model used by artefact-engagement telemetry.
-Records that carry any field outside the contract whitelist are dropped
-at the read gate — the report refuses to render leaked shapes rather
-than re-emit them.
-
-Usage:
-    python3 tier_usage_report.py                       # last 30d, table
-    python3 tier_usage_report.py --window-days 7       # last 7d
-    python3 tier_usage_report.py --window-days 0       # full log
-    python3 tier_usage_report.py --json                # JSON for tooling
-    python3 tier_usage_report.py --log-path X.jsonl    # archived snapshot
-
-Exit codes:
-    0   success or telemetry disabled (single header line)
-    1   no records survived the privacy floor on a non-empty file
-    2   IO error (permission denied; passed path missing)
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from collections import defaultdict
-from datetime import datetime, timedelta, timezone
-from pathlib import Path
-from typing import Any
-
-from telemetry.settings import DEFAULT_TIER_USAGE_LOG_PATH, read_tier_usage_settings
-
-#: Contract whitelist (see ``docs/contracts/command-clusters.md``).
-ALLOWED_FIELDS = frozenset({"ts_bucket", "command", "tier", "outcome", "user_hash"})
-ALLOWED_OUTCOMES = frozenset({"success", "error", "blocked"})
-
-
-def _parse_record(raw: str) -> dict[str, Any] | None:
-    """Return a sanitized record or ``None`` when the line violates the floor."""
-    try:
-        obj = json.loads(raw)
-    except json.JSONDecodeError:
-        return None
-    if not isinstance(obj, dict):
-        return None
-    if not set(obj.keys()).issubset(ALLOWED_FIELDS):
-        return None
-    cmd = obj.get("command")
-    if not isinstance(cmd, str) or not cmd or "/" in cmd or "\\" in cmd:
-        return None
-    if not isinstance(obj.get("tier"), int) or obj["tier"] not in (0, 1, 2, 3):
-        return None
-    if obj.get("outcome") not in ALLOWED_OUTCOMES:
-        return None
-    uh = obj.get("user_hash")
-    if not isinstance(uh, str) or len(uh) != 16:
-        return None
-    if not isinstance(obj.get("ts_bucket"), str):
-        return None
-    return obj
-
-
-def _within_window(ts_bucket: str, window_days: int | None) -> bool:
-    if window_days is None or window_days == 0:
-        return True
-    try:
-        ts = datetime.fromisoformat(ts_bucket.replace("Z", "+00:00"))
-    except ValueError:
-        return False
-    if ts.tzinfo is None:
-        ts = ts.replace(tzinfo=timezone.utc)
-    return ts >= datetime.now(timezone.utc) - timedelta(days=window_days)
-
-
-def aggregate(
-    log_path: Path, window_days: int,
-) -> tuple[dict[tuple[int, str], dict[str, Any]], int, int]:
-    """Return ``((tier, command) -> stats, total_lines, kept)`` over the window."""
-    buckets: dict[tuple[int, str], dict[str, Any]] = defaultdict(
-        lambda: {"count": 0, "users": set()},
-    )
-    total = 0
-    kept = 0
-    if not log_path.exists():
-        return {}, 0, 0
-    with log_path.open("r", encoding="utf-8") as fh:
-        for line in fh:
-            line = line.strip()
-            if not line:
-                continue
-            total += 1
-            rec = _parse_record(line)
-            if rec is None:
-                continue
-            if not _within_window(rec["ts_bucket"], window_days):
-                continue
-            kept += 1
-            key = (int(rec["tier"]), rec["command"])
-            buckets[key]["count"] += 1
-            buckets[key]["users"].add(rec["user_hash"])
-    out = {k: {"count": v["count"], "distinct_users": len(v["users"])}
-           for k, v in buckets.items()}
-    return out, total, kept
-
-
-def render(
-    table: dict[tuple[int, str], dict[str, Any]],
-    window_days: int,
-) -> str:
-    suffix = f" (last {window_days}d)" if window_days else " (full log)"
-    if not table:
-        return f"(no tier-usage records{suffix})\n"
-    rows = sorted(table.items(), key=lambda kv: (kv[0][0], -kv[1]["count"], kv[0][1]))
-    header = f"{'Tier':<6}{'Command':<32}{'Calls':>8}{'Users':>8}"
-    lines = [header, "-" * len(header)]
-    for (tier, command), stats in rows:
-        lines.append(
-            f"{tier:<6}{command:<32}{stats['count']:>8}{stats['distinct_users']:>8}",
-        )
-    lines.append(f"\n(window:{suffix.strip()})")
-    return "\n".join(lines) + "\n"
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="Tier-usage frequency report.")
-    parser.add_argument("--window-days", type=int, default=30,
-                        help="trailing window in days (0 = full log)")
-    parser.add_argument("--json", action="store_true",
-                        help="emit JSON instead of the table")
-    parser.add_argument("--log-path", type=Path, default=None,
-                        help="override settings; read an archived log")
-    parser.add_argument("--settings-file", type=Path, default=Path(".agent-settings.yml"))
-    args = parser.parse_args(argv)
-
-    settings = read_tier_usage_settings(args.settings_file)
-    log_path = args.log_path or settings.log_path or DEFAULT_TIER_USAGE_LOG_PATH
-
-    if args.log_path is None and not settings.enabled:
-        sys.stdout.write(
-            "(tier-usage telemetry disabled; set "
-            "`telemetry.tier_usage.enabled: true` in .agent-settings.yml)\n",
-        )
-        return 0
-
-    try:
-        table, total, kept = aggregate(log_path, args.window_days)
-    except OSError as exc:
-        print(f"❌  {exc}", file=sys.stderr)
-        return 2
-
-    if total > 0 and kept == 0:
-        print(f"❌  {total} record(s) read; 0 survived the privacy floor — "
-              "report refused", file=sys.stderr)
-        return 1
-
-    if args.json:
-        payload = {
-            "window_days": args.window_days,
-            "log_path": str(log_path),
-            "records_total": total,
-            "records_kept": kept,
-            "rows": [
-                {"tier": t, "command": c, "count": v["count"],
-                 "distinct_users": v["distinct_users"]}
-                for (t, c), v in sorted(table.items(), key=lambda kv: (kv[0][0], kv[0][1]))
-            ],
-        }
-        sys.stdout.write(json.dumps(payload, indent=2) + "\n")
-    else:
-        sys.stdout.write(render(table, args.window_days))
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

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

@@ -1,58 +0,0 @@
-"""``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
-``docs/contracts/adr-implement-ticket-runtime.md`` and
-``docs/contracts/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/dist/agent-src/templates/scripts/work_engine/__main__.py

@@ -1,9 +0,0 @@
-"""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())

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

@@ -1,7 +0,0 @@
-"""Internal helpers shared across work_engine submodules.
-
-Currently houses :mod:`agent_settings` — the byte-identical mirror of
-``scripts/_lib/agent_settings.py`` from the agent-config package. The
-parity test in ``tests/test_template_agent_settings_parity.py`` guards
-the two files against drift.
-"""