stdtel 0.2.3__py3-none-any.whl

stdtel/manifest.py

@@ -0,0 +1,217 @@
+"""Parse and validate SKILL.md front-matter (the standards-repo contract)."""
+from __future__ import annotations
+
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+SEMVER = re.compile(r"^\d+\.\d+\.\d+$")
+STANDARD_ID = re.compile(r"^STD-[A-Z]+-\d{3}$")
+HARNESSES = {"claude-code", "copilot-vscode", "copilot-cli"}
+SUCCESS_SIGNALS = {"policy", "test", "manual"}
+
+
+@dataclass
+class SkillManifest:
+    name: str
+    version: str
+    standard_id: str
+    policy_ids: list[str]
+    owner: str
+    harness_support: list[str]
+    telemetry_emit: bool = True
+    success_signal: str = "policy"
+    path: Path | None = None
+    extra: dict = field(default_factory=dict)
+
+    def as_attributes(self) -> dict:
+        """Span attributes contributed by the manifest (std.* namespace)."""
+        return {
+            "std.skill.name": self.name,
+            "std.skill.version": self.version,
+            "std.standard_id": self.standard_id,
+            "std.policy.ids": ",".join(self.policy_ids),
+            "std.skill.owner": self.owner,
+        }
+
+
+class ManifestError(ValueError):
+    pass
+
+
+def split_front_matter(text: str) -> tuple[dict, str]:
+    if not text.startswith("---"):
+        raise ManifestError("SKILL.md must start with YAML front-matter (---)")
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        raise ManifestError("unterminated front-matter")
+    data = yaml.safe_load(parts[1]) or {}
+    return data, parts[2]
+
+
+# Agent Skills permits only these six frontmatter keys; everything else is a
+# client-only extension that hard-errors on claude.ai upload. Our contract fields
+# therefore live under `metadata:`, which the spec types as a string->string map,
+# so lists arrive comma-separated.
+SPEC_KEYS = {"name", "description", "license", "compatibility", "metadata", "allowed-tools"}
+CONTRACT_KEYS = ("version", "standard_id", "policy_ids", "owner", "harness_support", "telemetry")
+
+
+def _split_list(value) -> list[str]:
+    """`policy_ids` as a real list (top-level form) or a comma-separated string
+    (spec form, where metadata values must be strings)."""
+    if isinstance(value, str):
+        return [v.strip() for v in value.split(",") if v.strip()]
+    return value
+
+
+def _flatten(data: dict) -> dict:
+    """Contract fields, wherever they live.
+
+    Spec-conformant SKILL.md nests them under `metadata:`; the original flat form
+    is still accepted so existing catalogues keep validating. `metadata:` wins.
+    """
+    meta = data.get("metadata") or {}
+    if not isinstance(meta, dict):
+        meta = {}
+    out = dict(data)
+    for key in CONTRACT_KEYS:
+        if key in meta:
+            out[key] = meta[key]
+    if "telemetry" not in out:
+        # spec form flattens the nested telemetry block into dotted metadata keys
+        tel = {k.split(".", 1)[1]: v for k, v in meta.items() if k.startswith("telemetry.")}
+        if tel:
+            out["telemetry"] = tel
+    for key in ("policy_ids", "harness_support"):
+        if key in out:
+            out[key] = _split_list(out[key])
+    return out
+
+
+def parse_manifest(text: str, path: Path | None = None) -> SkillManifest:
+    data, _ = split_front_matter(text)
+    data = _flatten(data)
+    errors = []
+    for key in ("name", "version", "standard_id", "policy_ids", "owner", "harness_support"):
+        if key not in data:
+            errors.append(f"missing required field: {key}")
+    if errors:
+        raise ManifestError("; ".join(errors))
+    if not SEMVER.match(str(data["version"])):
+        errors.append(f"version must be semver, got {data['version']!r}")
+    if not STANDARD_ID.match(data["standard_id"]):
+        errors.append(f"standard_id must match STD-XXX-000, got {data['standard_id']!r}")
+    if not isinstance(data["policy_ids"], list) or not data["policy_ids"]:
+        errors.append("policy_ids must be a non-empty list")
+    bad = set(data["harness_support"]) - HARNESSES
+    if bad:
+        errors.append(f"unknown harness(es): {sorted(bad)}")
+    tel = data.get("telemetry", {}) or {}
+    if not isinstance(tel, dict):
+        tel = {}
+    signal = str(tel.get("success_signal", "policy"))
+    if signal not in SUCCESS_SIGNALS:
+        errors.append(f"telemetry.success_signal must be one of {sorted(SUCCESS_SIGNALS)}")
+    if errors:
+        raise ManifestError("; ".join(errors))
+    known = SPEC_KEYS | set(CONTRACT_KEYS) | {"description"}
+    return SkillManifest(
+        name=data["name"],
+        version=str(data["version"]),
+        standard_id=data["standard_id"],
+        policy_ids=list(data["policy_ids"]),
+        owner=data["owner"],
+        harness_support=list(data["harness_support"]),
+        telemetry_emit=str(tel.get("emit", True)).lower() not in ("false", "0", "no"),
+        success_signal=signal,
+        path=path,
+        extra={k: v for k, v in data.items() if k not in known},
+    )
+
+
+def load_manifest(path: Path) -> SkillManifest:
+    return parse_manifest(path.read_text(encoding="utf-8"), path=path)
+
+
+def iter_skill_files(root: Path) -> list[Path]:
+    """Every SKILL.md under root, sorted, following symlinked directories.
+
+    Catalogues are assembled by symlinking skills into a shared directory
+    (~/.claude/skills), which Path.rglob would silently refuse to descend into.
+    Each resolved directory is visited once, so a symlink cycle cannot hang a hook.
+    """
+    found, seen = [], set()
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=True):
+        real = os.path.realpath(dirpath)
+        if real in seen:
+            dirnames[:] = []          # cycle, or a second route to the same tree
+            continue
+        seen.add(real)
+        if "SKILL.md" in filenames:
+            found.append(Path(dirpath) / "SKILL.md")
+    return sorted(found)
+
+
+def load_catalogue(root: Path, strict: bool = True) -> dict[str, SkillManifest]:
+    """All SKILL.md files under root, keyed by skill name.
+
+    `strict` is the CI contract gate: any invalid or duplicate manifest raises.
+    Hooks pass strict=False so one broken SKILL.md in a shared skills directory
+    cannot silence telemetry for every other skill (first definition wins).
+    """
+    out: dict[str, SkillManifest] = {}
+    for p in iter_skill_files(root):
+        try:
+            m = load_manifest(p)
+        except (ManifestError, OSError, yaml.YAMLError):
+            if strict:
+                raise
+            continue
+        if m.name in out:
+            if strict:
+                raise ManifestError(f"duplicate skill name {m.name!r}: {p} and {out[m.name].path}")
+            continue
+        out[m.name] = m
+    return out
+
+
+def cli(argv: list[str] | None = None) -> int:
+    """The CI contract gate.
+
+    Exit 0 valid, 1 an invalid manifest, 2 the root cannot be read. That last
+    case used to exit 0 with "0 skill(s) valid" — a typo'd path in CI reported a
+    clean gate over nothing, and `--help` was parsed as a directory name.
+    """
+    import argparse
+
+    ap = argparse.ArgumentParser(
+        prog="stdtel-validate",
+        description="Validate SKILL.md front-matter against the standards contract.")
+    ap.add_argument("root", nargs="?", default="skills",
+                    help="directory to scan recursively for SKILL.md (default: skills)")
+    ap.add_argument("--quiet", "-q", action="store_true", help="only report failures")
+    a = ap.parse_args(sys.argv[1:] if argv is None else argv)
+
+    root = Path(a.root).expanduser()
+    if not root.is_dir():
+        print(f"stdtel-validate: no such directory: {root}", file=sys.stderr)
+        return 2
+    try:
+        cat = load_catalogue(root)
+    except ManifestError as e:
+        print(f"INVALID: {e}", file=sys.stderr)
+        return 1
+    if not a.quiet:
+        for name, m in cat.items():
+            print(f"OK  {name}@{m.version}  {m.standard_id}  policies={len(m.policy_ids)}")
+    print(f"{len(cat)} skill(s) valid in {root}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(cli())

stdtel/policy_report.py

@@ -0,0 +1,126 @@
+"""Grade a PR's tree with OPA and emit `policy_result` rows.
+
+The primary effectiveness metric is *first-time* OPA policy pass rate, so
+`run_seq` — which CI run this was — is the metric, not metadata. It cannot be
+recovered afterwards: re-runs, retries and cancelled jobs make the true ordering
+unknowable from history, which is why this runs in CI and writes an artefact
+rather than being reconstructed by the loader (ADR-002).
+
+    stdtel-policy-report --pr-id owner/repo#42 --run-seq 1 --out policy.jsonl
+
+Grading reuses `eval.run_eval`, so CI and the offline eval runner cannot diverge
+on what "passing" means.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+COLUMNS = ("pr_id", "policy_id", "run_seq", "passed", "evaluated_at")
+
+
+def next_run_seq(previous_runs: int) -> int:
+    """1 for the first CI run on a PR, 2 for the next, and so on.
+
+    Derived from a count of prior completed runs rather than a retry counter:
+    `run_attempt` counts re-runs of one workflow run, not runs of the workflow.
+    """
+    if previous_runs < 0:
+        raise ValueError(f"previous_runs cannot be negative: {previous_runs}")
+    return previous_runs + 1
+
+
+def count_previous_runs(repo: str, workflow: str, branch: str) -> int:
+    """Completed runs of this workflow on this branch, via `gh`.
+
+    Returns 0 when it cannot tell. That biases toward calling a run "first",
+    which is the safer error: a duplicated run_seq=1 is visible as a conflict in
+    the warehouse, whereas silently skipping to 2 would lose the first-time
+    measurement entirely.
+    """
+    out = subprocess.run(
+        ["gh", "api", f"repos/{repo}/actions/workflows/{workflow}/runs",
+         "-f", f"branch={branch}", "-f", "status=completed", "--jq", ".total_count"],
+        capture_output=True, text=True)
+    if out.returncode != 0:
+        print(f"stdtel-policy-report: cannot count prior runs ({out.stderr.strip()}); "
+              f"treating this as the first", file=sys.stderr)
+        return 0
+    try:
+        return int(out.stdout.strip())
+    except ValueError:
+        return 0
+
+
+def build_rows(workdir: Path, policies: list[str], policy_root: Path,
+               pr_id: str, run_seq: int) -> list[dict]:
+    """One row per policy. A policy that cannot be evaluated fails; it is never
+    omitted, because an absent row and a failing row must not look alike."""
+    from eval.run_eval import grade
+
+    evaluated_at = dt.datetime.now(dt.timezone.utc).isoformat().replace("+00:00", "Z")
+    results = grade(Path(workdir), policies, Path(policy_root), dry_run=False)
+    return [{"pr_id": pr_id, "policy_id": policy_id, "run_seq": run_seq,
+             "passed": bool(passed), "evaluated_at": evaluated_at}
+            for policy_id, passed in results.items()]
+
+
+def write_jsonl(path: Path, rows: list[dict]) -> int:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as fh:
+        for row in rows:
+            fh.write(json.dumps({c: row[c] for c in COLUMNS}) + "\n")
+    return len(rows)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="stdtel-policy-report", description=__doc__.splitlines()[0])
+    ap.add_argument("--pr-id", required=True, help="owner/repo#number, matching pull_request.pr_id")
+    ap.add_argument("--policies", type=Path, default=Path("policies"))
+    ap.add_argument("--policy-ids", help="comma-separated; defaults to every package under --policies")
+    ap.add_argument("--workdir", type=Path, default=Path("."))
+    ap.add_argument("--out", type=Path, default=Path("policy-results.jsonl"))
+    run = ap.add_mutually_exclusive_group(required=True)
+    run.add_argument("--run-seq", type=int, help="explicit sequence number")
+    run.add_argument("--derive-run-seq", nargs=3, metavar=("REPO", "WORKFLOW", "BRANCH"),
+                     help="count prior completed runs with gh and use the next number")
+    a = ap.parse_args(sys.argv[1:] if argv is None else argv)
+
+    if not a.policies.is_dir():
+        print(f"stdtel-policy-report: no policy root at {a.policies}", file=sys.stderr)
+        return 2
+
+    if a.policy_ids:
+        policy_ids = [p.strip() for p in a.policy_ids.split(",") if p.strip()]
+    else:
+        policy_ids = discover_policy_ids(a.policies)
+    if not policy_ids:
+        print(f"stdtel-policy-report: no policies found under {a.policies}", file=sys.stderr)
+        return 2
+
+    run_seq = a.run_seq if a.run_seq is not None else next_run_seq(count_previous_runs(*a.derive_run_seq))
+    rows = build_rows(a.workdir, policy_ids, a.policies, a.pr_id, run_seq)
+    write_jsonl(a.out, rows)
+    failed = [r["policy_id"] for r in rows if not r["passed"]]
+    print(f"wrote {len(rows)} policy result(s) to {a.out} (run_seq={run_seq}); "
+          f"{'failed: ' + ', '.join(failed) if failed else 'all passed'}")
+    return 0
+
+
+def discover_policy_ids(policy_root: Path) -> list[str]:
+    """Rego `package` declarations under the root, which are the policy ids."""
+    import re
+    ids = set()
+    for rego in sorted(Path(policy_root).rglob("*.rego")):
+        m = re.search(r"^package\s+([\w.]+)", rego.read_text(), re.M)
+        if m:
+            ids.add(m.group(1))
+    return sorted(ids)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stdtel/skillmap.py

@@ -0,0 +1,15 @@
+"""Generate the Copilot skill lookup table from the skills catalogue."""
+from __future__ import annotations
+import sys
+from pathlib import Path
+import yaml
+from stdtel.manifest import load_catalogue
+
+def generate(root: Path) -> str:
+    cat = load_catalogue(root)
+    table = {n: {"standard_id": m.standard_id, "version": m.version, "policy_ids": ",".join(m.policy_ids)}
+             for n, m in cat.items()}
+    return yaml.safe_dump(table, sort_keys=True)
+
+if __name__ == "__main__":
+    print(generate(Path(sys.argv[1] if len(sys.argv) > 1 else "skills")), end="")

stdtel/spool.py

@@ -0,0 +1,124 @@
+"""Append spans to disk; export them from somewhere else (ADR-008).
+
+A hook that never opens a socket cannot stall on one. That is what "hooks never
+block the developer" was always reaching for — bounding the export timeout only
+traded a 7.34s stall for silent data loss.
+
+The file is NDJSON, one span per line, under `~/.stdtel/spool/`. `scrub()` runs
+before anything is written: the content rules apply to disk, not only to the wire.
+
+Draining is deliberately conservative. Records are removed only after the export
+returns, so a failure leaves everything in place, and the drain rewrites only what
+it actually read — a hook firing mid-drain is not lost.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Callable, Iterable
+
+DEFAULT_MAX_RECORDS = 50_000
+
+
+class SpoolFull(RuntimeError):
+    pass
+
+
+def spool_dir() -> Path:
+    d = Path(os.environ.get("STDTEL_SPOOL_DIR", Path.home() / ".stdtel" / "spool"))
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def spool_path() -> Path:
+    return spool_dir() / "spans.ndjson"
+
+
+def append(records: Iterable[dict]) -> int:
+    """Write records and return. No network, no retry, no blocking."""
+    from stdtel.exporter import scrub
+
+    rows = []
+    for r in records:
+        row = dict(r)
+        row["attributes"] = scrub(dict(row.get("attributes") or {}))
+        row["resource"] = scrub(dict(row.get("resource") or {}))
+        rows.append(row)
+    if not rows:
+        return 0
+    with spool_path().open("a", encoding="utf-8") as fh:
+        for row in rows:
+            fh.write(json.dumps(row) + "\n")
+    return len(rows)
+
+
+def read_all() -> list[dict]:
+    """Every readable record. A corrupt line is skipped, not fatal — one bad
+    write must not strand everything behind it."""
+    path = spool_path()
+    if not path.is_file():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        if not line.strip():
+            continue
+        try:
+            out.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+def _rewrite(rows: list[dict]) -> None:
+    """Replace the spool atomically, so a crash mid-rewrite cannot truncate it."""
+    path = spool_path()
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            for row in rows:
+                fh.write(json.dumps(row) + "\n")
+        os.replace(tmp, path)
+    except Exception:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def drain(export: Callable[[list[dict]], None]) -> int:
+    """Hand every spooled record to `export`, then remove exactly those.
+
+    Records appended while `export` runs are kept: the rewrite drops only the
+    records that were read, matched by position, rather than truncating the file.
+    A raising export removes nothing.
+    """
+    batch = read_all()
+    if not batch:
+        return 0
+    export(batch)                       # may raise; nothing is removed if it does
+    remaining = read_all()[len(batch):]
+    _rewrite(remaining)
+    return len(batch)
+
+
+def max_records_default() -> int:
+    try:
+        return max(1, int(os.environ.get("STDTEL_SPOOL_MAX", DEFAULT_MAX_RECORDS)))
+    except ValueError:
+        return DEFAULT_MAX_RECORDS
+
+
+def trim(max_records: int | None = None) -> int:
+    """Enforce the bound, oldest first. Returns how many were dropped.
+
+    The count is the point: an unbounded spool fills a developer's disk, and a
+    silent drop at the bound would reintroduce exactly the invisible loss this
+    design removes.
+    """
+    max_records = max_records_default() if max_records is None else max_records
+    rows = read_all()
+    if len(rows) <= max_records:
+        return 0
+    dropped = len(rows) - max_records
+    _rewrite(rows[dropped:])
+    return dropped

stdtel/spool_export.py

@@ -0,0 +1,86 @@
+"""Drain the spool and export it (ADR-008).
+
+The hook writes NDJSON and returns; this turns those records back into spans and
+sends them. Run it on a schedule, from `make up`, or with `--watch`.
+
+    stdtel-export --once
+    stdtel-export --watch --interval 30
+
+Export failure leaves the spool untouched, so the next run retries. That is the
+whole point: capture keeps working while the collector does not.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+DEFAULT_INTERVAL_S = 30
+
+
+def export_batch(batch: list[dict], exporter=None) -> int:
+    """Rebuild spans from spooled records and emit them.
+
+    Grouped by resource so each group carries the session's own attributes;
+    records from different sessions must not be merged under one resource.
+    """
+    from stdtel.exporter import SESSION_SPAN_NAME, SPAN_NAME, build_provider, emit_invocations, emit_session_cost
+
+    groups: dict[tuple, list[dict]] = {}
+    for row in batch:
+        key = tuple(sorted((row.get("resource") or {}).items()))
+        groups.setdefault(key, []).append(row)
+
+    total = 0
+    for key, rows in groups.items():
+        provider = build_provider(dict(key), exporter=exporter)
+        invocations = [r for r in rows if r.get("name") == SPAN_NAME]
+        if invocations:
+            by_session: dict[str, list[dict]] = {}
+            for r in invocations:
+                by_session.setdefault(r.get("session_id", ""), []).append(r)
+            for session_id, rs in by_session.items():
+                total += emit_invocations(provider, rs, session_id)
+        for r in rows:
+            if r.get("name") == SESSION_SPAN_NAME:
+                total += emit_session_cost(provider, r.get("attributes") or {},
+                                           r.get("session_id", ""),
+                                           r.get("started_at", 0.0), r.get("ended_at", 0.0))
+    return total
+
+
+def run_once() -> int:
+    from stdtel.spool import drain, trim
+    dropped = trim()
+    if dropped:
+        print(f"stdtel-export: spool over its bound, dropped {dropped} oldest record(s)",
+              file=sys.stderr)
+    try:
+        return drain(export_batch)
+    except Exception as e:                        # noqa: BLE001 - leave the spool intact
+        print(f"stdtel-export: export failed, spool kept for retry: {e}", file=sys.stderr)
+        return -1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="stdtel-export", description=__doc__.splitlines()[0])
+    mode = ap.add_mutually_exclusive_group()
+    mode.add_argument("--once", action="store_true", help="drain and exit (default)")
+    mode.add_argument("--watch", action="store_true", help="drain repeatedly")
+    ap.add_argument("--interval", type=int, default=DEFAULT_INTERVAL_S)
+    a = ap.parse_args(sys.argv[1:] if argv is None else argv)
+
+    if not a.watch:
+        n = run_once()
+        if n >= 0:
+            print(f"exported {n} span(s)")
+        return 0 if n >= 0 else 1
+    while True:
+        n = run_once()
+        if n > 0:
+            print(f"exported {n} span(s)")
+        time.sleep(max(1, a.interval))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stdtel/state.py

@@ -0,0 +1,118 @@
+"""Per-session state shared between hooks (start/stop of skill invocations)."""
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+
+def state_dir() -> Path:
+    d = Path(os.environ.get("STDTEL_STATE_DIR", Path.home() / ".stdtel" / "sessions"))
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+@dataclass
+class SkillWindow:
+    skill: str
+    version: str
+    trigger: str            # caller.type from the transcript, or "unknown"
+    started_at: float
+    ended_at: float | None = None
+    tool_use_id: str | None = None
+    load_tokens: int = 0
+    error: bool = False
+    # straight from the hook payload (validated against a live session 2026-09-10)
+    prompt_id: str = ""         # correlates with native claude_code.* telemetry
+    permission_mode: str = ""   # measured harness mode, not the env's guess
+    duration_ms: int = 0        # the harness's own timing, better than our clock
+
+
+@dataclass
+class SessionState:
+    session_id: str
+    transcript_offset: int = 0
+    started_at: float = 0.0        # wall clock at SessionStart; see stop()
+    resource: dict = field(default_factory=dict)   # std.ticket.id, std.repo, std.team, std.harness
+    windows: list[SkillWindow] = field(default_factory=list)
+    # {tool_name: [calls, failures]} — counts only, never inputs or results.
+    # Aggregated per session rather than one span per tool call: at ~30 calls per
+    # prompt, per-call spans would multiply telemetry volume for a metric that
+    # only needs counts.
+    tool_calls: dict = field(default_factory=dict)
+    # outcome of the last export, so the statusline can say "spans are dropping"
+    # from local state rather than probing the collector on every render
+    last_export_ok: bool | None = None
+
+    @property
+    def path(self) -> Path:
+        return state_dir() / f"{self.session_id}.json"
+
+    @classmethod
+    def load(cls, session_id: str) -> "SessionState":
+        p = state_dir() / f"{session_id}.json"
+        if not p.exists():
+            return cls(session_id=session_id)
+        raw = json.loads(p.read_text())
+        st = cls(session_id=session_id, transcript_offset=raw.get("transcript_offset", 0),
+                 started_at=raw.get("started_at", 0.0), resource=raw.get("resource", {}),
+                 last_export_ok=raw.get("last_export_ok"))
+        st.windows = [SkillWindow(**w) for w in raw.get("windows", [])]
+        st.tool_calls = {k: list(v) for k, v in (raw.get("tool_calls") or {}).items()}
+        return st
+
+    def save(self) -> None:
+        """Every field must be listed here.
+
+        Each hook is a separate process, so anything not written is lost between
+        events — silently, because the field simply reads as its default. Two
+        fields were added without being persisted and produced plausible-looking
+        zeros rather than an error.
+        """
+        self.path.write_text(json.dumps({
+            "transcript_offset": self.transcript_offset,
+            "started_at": self.started_at,
+            "resource": self.resource,
+            "windows": [asdict(w) for w in self.windows],
+            "tool_calls": self.tool_calls,
+            "last_export_ok": self.last_export_ok,
+        }, indent=1))
+
+    def open_window(self, skill: str, version: str, trigger: str, tool_use_id: str | None,
+                    prompt_id: str = "", permission_mode: str = "") -> SkillWindow:
+        w = SkillWindow(skill=skill, version=version, trigger=trigger,
+                        started_at=time.time(), tool_use_id=tool_use_id,
+                        prompt_id=prompt_id, permission_mode=permission_mode)
+        self.windows.append(w)
+        return w
+
+    def close_window(self, tool_use_id: str | None, error: bool = False) -> SkillWindow | None:
+        for w in reversed(self.windows):
+            if w.ended_at is None and (tool_use_id is None or w.tool_use_id == tool_use_id):
+                w.ended_at = time.time()
+                w.error = error
+                return w
+        return None
+
+    def record_tool(self, tool_name: str, failed: bool = False) -> None:
+        if not tool_name:
+            return
+        entry = self.tool_calls.setdefault(tool_name, [0, 0])
+        entry[0] += 1
+        if failed:
+            entry[1] += 1
+
+    def tool_totals(self) -> tuple[int, int]:
+        calls = sum(v[0] for v in self.tool_calls.values())
+        failures = sum(v[1] for v in self.tool_calls.values())
+        return calls, failures
+
+    def open_windows(self) -> list[SkillWindow]:
+        return [w for w in self.windows if w.ended_at is None]
+
+    def drain_closed(self) -> list[SkillWindow]:
+        closed = [w for w in self.windows if w.ended_at is not None]
+        self.windows = [w for w in self.windows if w.ended_at is None]
+        return closed