Module log 

Hand-rolled JSON-lines logger. ~150 lines reusing the serde_json serializer — deliberately not tracing (its implicit async span context is moot for a processes-plus-threads design, and the process tree gives us correlation for free). RFC 0010 §default-logging.

One NDJSON event per line to stderr (stdout is reserved for the agent’s result). The canonical line schema (RFC 0010 §line-schema) is: ts level event run_id agent_id agent_path comp pid [span_id parent_span_id trace_id] [dur_ms] [err] <event-specific>.

Structs

EventWindow

A snapshot of the ring window an agentd://events?after=<seq> read returns: the entries with seq > after (after optional level/event-prefix filtering), plus the ring’s current window bounds and cumulative dropped. RFC 0016 §7.2.

LogCtx

The correlation context stamped on every line. Children inherit run_id and trace_id and extend agent_path (the cheap subtree-query superpower: an agent_path prefix selects a subtree with no backend join). RFC 0010 §tree-correlation.

Logger

A logger bound to one LogCtx. Cheap to clone (clones the ctx); writes serialize behind a process-global stderr mutex so lines never interleave.

Enums

Comp

Which component is emitting. Part of the correlation tuple.

Level

Constants

EVENTS_RING_DEFAULT

Default ring capacity (AGENTD_EVENTS_RING, RFC 0016 §7.2/§11): the last N emitted lines held in memory. Bounds memory on a slow subscriber.

EVENTS_SCHEMA

Envelope version for the agentd://events read body (RFC 0016 §7.2/§8.1). Bumped only on a breaking change to the {oldest_seq,newest_seq,dropped, events} envelope — NOT the line schema (RFC 0010 owns + versions that).

Functions

install_event_ring

Install the bounded event ring with capacity cap (RFC 0016 §7.2). Called once by the supervisor when the served agentd://events resource is wanted (gated by --serve-mcp + the events feature at the call site). Idempotent — a second call resizes/clears. Never fatal (telemetry never crashes the run, §8.4).

read_event_window

Drain the ring into an EventWindow for a cursor read. Returns the entries with seq > after, capped at limit (oldest-first), each with its seq folded into the RFC 0010 §3.2 line object. level/event_prefixes are the optional §7.3 server-side filters (a cheap prefix match over the held lines — no query engine). None when no ring is installed (the resource 404s at the server). RFC 0016 §7.2/§7.3.

rfc3339_millis

Format a SystemTime as RFC 3339 UTC with millisecond precision, with no date-library dependency. Uses Howard Hinnant’s civil_from_days algorithm. Pre-epoch times clamp to the epoch (we never log them).

take_events_dirty

Take-and-clear the “new events since last check” flag — the served agentd://events resource calls this on its coalescing tick to decide whether to fire a notifications/resources/updated. Returns true if any line was captured since the last call. RFC 0016 §7.2.