agent_engine/runtime/trace/
mod.rs

1//! Versioned, provider-neutral request trace envelope (spec §6.1, §6.4).
2//!
3//! `synaps-request-trace/1` carries **bounded, safe-alphabet metadata only**:
4//! no field can hold free-form text. Every content-derived value is a count,
5//! byte length, enum, keyed digest ([`ComponentDigest`]), or a validated
6//! bounded identifier ([`TraceId`] / [`WireName`] — ≤256 bytes, restricted
7//! ASCII alphabet, no whitespace/control/quotes/backslashes). Short strings
8//! spelled from the ID alphabet remain representable — the enforced invariant
9//! is *bounded + safe*, which structurally excludes prompt text, message
10//! content, tool results, headers, query strings, and credentials of any
11//! realistic shape. Digests are HMAC-SHA256, keyed by a random
12//! per-installation key stored as a private regular file (`0600`, parent
13//! `0700`, symlink- and special-file-refusing) under the Synaps base
14//! directory — keying prevents offline dictionary confirmation of prompt
15//! contents from a leaked trace log. Neither the key nor digest preimages are
16//! ever logged.
17//!
18//! Task 7 delivered the types + serde + key/digest primitives; Task 8 wires
19//! the Anthropic transports (`runtime/api.rs`, `runtime/api_sync.rs`) into
20//! the emission seam in [`emit`], with structural builders in [`anthropic`]
21//! (the normalized IR / `TranslationReport` arrive in Task 9; the bounded
22//! persistence writer in Task 11). Task 10A extends the seam to the
23//! OpenAI-compatible transports — Chat Completions and Responses/Codex —
24//! via [`openai`]; Task 10B covers Gemini/Vertex and the cloud-invoke
25//! routes via [`google`]; Task 10C completes the set with extension-hosted
26//! providers via [`extension`].
27//! Serde contract (deliberate): optional metrics serialize as **absent** —
28//! never fabricated zeros — and both absent and explicit `null` deserialize
29//! to `None`. Struct field order is the deterministic serialization order.
30
31pub mod anthropic;
32pub mod controls;
33pub mod diagnostics;
34pub mod emit;
35pub mod execution;
36pub mod export;
37pub mod extension;
38pub mod google;
39mod key;
40pub mod openai;
41mod types;
42
43pub use controls::{
44    default_capture_dir, ContentCapture, TraceArm, TraceControls, TraceStatusReport,
45    CAPTURE_MAX_BYTES, CAPTURE_TTL, CONTENT_CAPTURE_SCHEMA,
46};
47pub use diagnostics::{CacheActivity, CacheSnapshotStore, ContextReport, ReportValue};
48pub use emit::{
49    wire_meta_from_sent_bytes, AttemptClock, CollectingTraceSink, NoopTraceSink,
50    RequestCorrelation, RequestStructure, RequestTracer, TraceContext, TraceSink,
51};
52pub use execution::ExecutionCorrelation;
53pub use export::{
54    export_content, export_metadata, redact_value, sweep_expired_captures, ContentExport,
55    ExportError, MetadataExportStats, CONTENT_EXPORT_SCHEMA,
56};
57pub use key::{
58    default_digest_key_path, keyed_digest, load_or_create_digest_key, load_or_create_digest_key_at,
59    ComponentDigest, DigestDomain, TraceDigestKey, TraceKeyError,
60};
61pub use types::{
62    ActivationGrantRef, BlockKind, BlockMeta, CacheBoundaryLocation, CacheBoundaryMeta, CacheMeta,
63    CacheSegmentDelta, CacheTtlClass, EndpointMeta, ExecutionCommitStatus, ExecutionEffect,
64    ExecutionPhase, MessageMeta, MessageRole, PrefixMeta, RequestAnatomy, RequestTrace, RetryClass,
65    RetryMeta, SegmentChange, StopReason, SystemSegmentKind, SystemSegmentMeta, TimingStages,
66    ToolExecutionEvent, ToolMeta, TraceId, TraceSchemaVersion, TranslationAction,
67    TranslationElement, TranslationLoss, TransportKind, TransportOutcome, UsageMeta,
68    UsageProvenance, WireMeta, WireName, TRACE_ID_MAX_BYTES, TRACE_SCHEMA, WIRE_NAME_MAX_BYTES,
69};
70
71#[cfg(test)]
72mod tests;
73
74#[cfg(test)]
75mod wiring_tests;
76
77#[cfg(test)]
78mod openai_wiring_tests;
79
80#[cfg(test)]
81mod google_wiring_tests;
82
83#[cfg(test)]
84mod extension_wiring_tests;
agent_engine/runtime/trace/mod.rs

agent_engine/runtime/trace/
mod.rs
