aeat.entrypoints.mcp._telemetry module

Local session telemetry: payload-free per-call trajectory records.

ADR R7’s operational half: every console session leaves a local, per-call trajectory record so the harness is measurable and a live failure can be traced and promoted into a golden scenario. The records are deliberately METADATA-ONLY — tool name, command key, confirmation route, error flag, duration, and content HASHES of the arguments and result — never the payloads themselves: a tool result carries the taxpayer’s figures, and sensitive-financial-data-secure-storage-only forbids persisting those anywhere outside encrypted secure storage. A hash lets two records be compared for identity (the flywheel’s dedup needs that) without storing a single figure; the full payloads exist only inside the eval harness’s own in-memory LiveTrajectory during a measurement run.

Records append as JSON lines to <aeat_local_storage_root>/telemetry/ <session_id>.jsonl, following the same state-root derivation the diagnostic log uses, so each workspace’s telemetry stays isolated.

The directory is bounded, not unbounded: a SessionTelemetryWriter sweeps its directory once at construction (server start) via prune_telemetry(), dropping trajectory files past an age or count bound while ALWAYS preserving the newest N sessions. Retention only ever removes whole per-session files — it never touches the payload-free posture of the rows that remain, and telemetry is a rebuildable derived surface, so a pruned file is a lost measurement sample, never a correctness dependency.

class ToolCallTelemetryRecord(**data)

Bases: BaseModel

One payload-free tool-call record in a session’s trajectory.

Variables:

• session_id – The serving session this call belongs to.

• sequence – Zero-based position of the call within the session.

• tool_name – The MCP tool name the client invoked.

• command_key – The registry command key the tool maps to (empty for meta/harness tools).

• route – The confirmation route the call took (a ConfirmRoute/ConfirmDecision value string), so override and refusal rates are computable from telemetry alone.

• is_error – Whether the call returned an error result.

• duration_ms – Wall-clock round-trip duration.

• arguments_sha256 – SHA-256 of the canonical arguments JSON.

• result_sha256 – SHA-256 of the result text; empty for refused calls that never ran.

Parameters:

• session_id (str)

• sequence (int)

• tool_name (str)

• command_key (str)

• route (str)

• is_error (bool)

• duration_ms (int)

• arguments_sha256 (str)

• result_sha256 (str)

session_id: str

sequence: int

tool_name: str

command_key: str

route: str

is_error: bool

duration_ms: int

arguments_sha256: str

result_sha256: str

content_sha256(text)

The one-way content reference telemetry stores instead of a payload.

Return type:

str

Parameters:

text (str)

telemetry_dir()

The workspace-scoped telemetry directory under the local storage root.

Return type:

Path

class TelemetryRetention(**data)

Bases: BaseModel

The bounds the startup trajectory-file sweep enforces.

Variables:

• max_age_days – Sessions whose file is older than this are pruned.

• max_sessions – The maximum number of session files kept; the oldest beyond this count are pruned.

• keep_newest – The newest N sessions are ALWAYS retained, whatever their age or the count bound — the sweep never removes them.

Parameters:

• max_age_days (float)

• max_sessions (int)

• keep_newest (int)

max_age_days: float

max_sessions: int

keep_newest: int

prune_telemetry(directory, *, max_age_days, max_sessions, keep_newest, now=None)

Prune per-session trajectory files by age and count, never the newest N.

Session files are ranked newest-first by modification time (ties broken by filename for determinism). The newest keep_newest are retained unconditionally. Of the remainder, a file is removed when it falls beyond the max_sessions count bound OR is older than max_age_days.

Parameters:

• directory (Path) – The telemetry directory to sweep. A missing directory is a no-op (returns an empty tuple).

• max_age_days (float) – Age bound in days; files with an older mtime are pruned.

• max_sessions (int) – Count bound; files ranked at or beyond this position (newest-first, zero-based) are pruned.

• keep_newest (int) – The number of newest sessions to retain unconditionally.

• now (float | None) – Reference epoch seconds for the age comparison; defaults to the wall clock. Injected by tests for deterministic ages.

Return type:

tuple[Path, ...]

Returns:

The tuple of file paths removed, in the order they were pruned.

class SessionTelemetryWriter(*, session_id, directory=None, retention=None)

Bases: object

Appends one session’s records to its JSONL file, creating lazily.

The writer is append-only for its own session’s rows. At construction (server start) it runs a single best-effort prune_telemetry() sweep over its directory so a long-lived installation’s telemetry stays bounded; the sweep is best-effort because a locked or vanished peer file must never abort a new session’s telemetry. The read path is read_session_records(); the flywheel and any operator inspection read the files back through it, and a rebuildable derived surface must never become a correctness dependency.

Parameters:

• session_id (str)

• directory (Path | None)

• retention (TelemetryRetention | None)

property session_id: str

The session identity every record of this writer carries.

property path: Path

The JSONL file this session appends to.

record(*, tool_name, command_key='', route='', is_error=False, duration_ms=0, arguments_text='', result_text='')

Append one payload-free record and return it.

Return type:

ToolCallTelemetryRecord

Returns:

A ToolCallTelemetryRecord.

Parameters:

• tool_name (str)

• command_key (str)

• route (str)

• is_error (bool)

• duration_ms (int)

• arguments_text (str)

• result_text (str)

read_session_records(path)

Load one session file back into typed records (a strict roundtrip surface).

Return type:

tuple[ToolCallTelemetryRecord, ...]

Returns:

A ToolCallTelemetryRecord.

Parameters:

path (Path)