"""TraceLogger — structured per-run trace for every agent invocation. Writes append-only JSONL entries to ``~/.polyhedra/sessions//trace.jsonl``. This is the authoritative source for token usage in V4.4+ (replaces ``QuantState.token_log`` for new code paths). STRUCT-3 (V4.4) — FR-S3.1 through FR-S3.4. """ from __future__ import annotations import hashlib import json import logging import time import uuid from datetime import datetime, timezone from pathlib import Path from typing import TYPE_CHECKING, Any if TYPE_CHECKING: from polyhedra.agents.base import AgentResponse logger = logging.getLogger(__name__) _TRACE_FILENAME = "trace.jsonl" class TraceLogger: """Logs each agent invocation to a session-scoped ``trace.jsonl`` file. Usage:: trace = TraceLogger(session_dir) run_id = trace.start_run("trendanalyst") response = await agent.handle(...) trace.end_run(run_id, response, prompt_tokens=843, completion_tokens=412, cache_hit=False) """ def __init__(self, session_dir: Path) -> None: self._path = session_dir / _TRACE_FILENAME self._in_flight: dict[str, dict[str, Any]] = {} # run_id -> partial entry # ------------------------------------------------------------------ # # Public API (FR-S3.1) # ------------------------------------------------------------------ # def start_run(self, agent_role: str, *, prompt: str = "", session_id: str = "") -> str: """Begin tracing an agent run. Returns a ``run_id`` (UUID4).""" run_id = str(uuid.uuid4()) self._in_flight[run_id] = { "run_id": run_id, "session_id": session_id, "agent_role": agent_role, "timestamp_start": datetime.now(tz=timezone.utc).isoformat(), "_start_mono": time.monotonic(), "input_hash": _sha256_prefix(prompt) if prompt else "", } return run_id def end_run( self, run_id: str, response: "AgentResponse", *, prompt_tokens: int = 0, completion_tokens: int = 0, cache_hit: bool = False, estimated_cost_usd: float | None = 0.0, ) -> None: """Finish tracing and append the completed entry to ``trace.jsonl``.""" partial = self._in_flight.pop(run_id, None) if partial is None: logger.warning("TraceLogger.end_run: unknown run_id %s", run_id) return start_mono: float = partial.pop("_start_mono", time.monotonic()) latency_ms = int((time.monotonic() - start_mono) * 1000) next_role = response.mentions[0] if response.mentions else None entry: dict[str, Any] = { **partial, "timestamp_end": datetime.now(tz=timezone.utc).isoformat(), "latency_ms": latency_ms, "output_hash": _sha256_prefix(response.content), "prompt_tokens": prompt_tokens, "completion_tokens": completion_tokens, "estimated_cost_usd": ( round(estimated_cost_usd, 6) if estimated_cost_usd is not None else None ), "cache_hit": cache_hit, "artifact_written": response.artifact_path or "", "next_role": next_role, "routing_reason": "", "error": response.error, } self._append(entry) def read_trace(self, last_n: int | None = None) -> list[dict[str, Any]]: """Read the trace file and return entries, optionally limited to *last_n*.""" if not self._path.exists(): return [] entries: list[dict[str, Any]] = [] try: with self._path.open("r", encoding="utf-8") as fh: for line in fh: line = line.strip() if line: try: entries.append(json.loads(line)) except json.JSONDecodeError: pass except OSError as exc: logger.error("TraceLogger: failed to read %s: %s", self._path, exc) if last_n is not None: entries = entries[-last_n:] return entries # ------------------------------------------------------------------ # # Internal helpers # ------------------------------------------------------------------ # def _append(self, entry: dict[str, Any]) -> None: try: self._path.parent.mkdir(parents=True, exist_ok=True) with self._path.open("a", encoding="utf-8") as fh: fh.write(json.dumps(entry, ensure_ascii=False) + "\n") except OSError as exc: logger.error("TraceLogger: failed to write trace entry: %s", exc) def _sha256_prefix(text: str, length: int = 16) -> str: return hashlib.sha256(text.encode("utf-8", errors="replace")).hexdigest()[:length]