Initial public release
Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
This commit is contained in:
462
crates/luxe-providers/src/wire.rs
Normal file
462
crates/luxe-providers/src/wire.rs
Normal file
@@ -0,0 +1,462 @@
|
||||
//! Wire log — an opt-in, on-disk record of everything Luxe sends to a model and gets back.
|
||||
//!
|
||||
//! Set `LUXE_WIRE_LOG=<path>` and every provider call appends JSONL: the exact request body as it
|
||||
//! goes on the wire (after provider-specific shaping — `cache_control` markers, tool schemas,
|
||||
//! thinking config), the request headers with credential values redacted, and every normalized
|
||||
//! [`ProviderEvent`] coming back. `luxe wire <path>` turns that into an audit report.
|
||||
//!
|
||||
//! Off unless the variable is set, and never fatal: a log that cannot be written is dropped with a
|
||||
//! warning rather than failing a turn. The file is local — nothing here phones home.
|
||||
//!
|
||||
//! Requests are recorded by the adapters, the only place the final body exists; responses by
|
||||
//! [`RecordingProvider`], which wraps any adapter and needs no per-provider knowledge. The two
|
||||
//! halves are tied together by a call id the decorator puts in a task-local, so concurrent
|
||||
//! sessions never interleave into one another's records.
|
||||
|
||||
use std::io::Write;
|
||||
use std::sync::atomic::{AtomicU64, Ordering};
|
||||
use std::sync::{Arc, Mutex, OnceLock};
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
|
||||
use luxe_core::provider::{CompletionRequest, Provider, ProviderError, ProviderEvent};
|
||||
|
||||
/// Header names whose value is a credential and must never reach the log.
|
||||
const SECRET_HEADERS: &[&str] =
|
||||
&["authorization", "x-api-key", "api-key", "cookie", "proxy-authorization"];
|
||||
|
||||
/// The open log file, resolved once from the environment.
|
||||
static SINK: OnceLock<Option<Mutex<std::fs::File>>> = OnceLock::new();
|
||||
|
||||
/// Monotonic provider-call counter.
|
||||
static SEQ: AtomicU64 = AtomicU64::new(0);
|
||||
|
||||
tokio::task_local! {
|
||||
/// The call id of the provider call this task is inside, set by [`RecordingProvider`].
|
||||
static CALL_ID: u64;
|
||||
}
|
||||
|
||||
fn sink() -> Option<&'static Mutex<std::fs::File>> {
|
||||
SINK.get_or_init(|| {
|
||||
let path = std::env::var("LUXE_WIRE_LOG").ok().filter(|path| !path.trim().is_empty())?;
|
||||
let path = std::path::PathBuf::from(path);
|
||||
if let Some(parent) = path.parent() {
|
||||
let _ = std::fs::create_dir_all(parent);
|
||||
}
|
||||
match std::fs::OpenOptions::new().create(true).append(true).open(&path) {
|
||||
Ok(file) => {
|
||||
tracing::info!(path = %path.display(), "wire log enabled");
|
||||
Some(Mutex::new(file))
|
||||
}
|
||||
Err(error) => {
|
||||
tracing::warn!(path = %path.display(), %error, "wire log could not be opened");
|
||||
None
|
||||
}
|
||||
}
|
||||
})
|
||||
.as_ref()
|
||||
}
|
||||
|
||||
/// Whether wire logging is on. Cheap enough to guard every call site.
|
||||
pub fn enabled() -> bool {
|
||||
sink().is_some()
|
||||
}
|
||||
|
||||
/// The call this task belongs to, or `0` for a provider used without the recording wrapper.
|
||||
pub fn current_call_id() -> u64 {
|
||||
CALL_ID.try_with(|id| *id).unwrap_or(0)
|
||||
}
|
||||
|
||||
fn append(record: serde_json::Value) {
|
||||
if let Some(sink) = sink() {
|
||||
append_to(sink, &record);
|
||||
}
|
||||
}
|
||||
|
||||
/// Writes `record` to `sink`, saying once if it could not.
|
||||
fn append_to(sink: &Mutex<impl Write>, record: &serde_json::Value) {
|
||||
let written = match sink.lock() {
|
||||
Ok(mut out) => write_record(&mut *out, record),
|
||||
Err(_) => Err(std::io::Error::other("the log's lock was poisoned")),
|
||||
};
|
||||
if let Err(error) = written {
|
||||
note_dropped(&error);
|
||||
}
|
||||
}
|
||||
|
||||
/// One record as one line.
|
||||
fn write_record(out: &mut impl Write, record: &serde_json::Value) -> std::io::Result<()> {
|
||||
let line = serde_json::to_string(record).map_err(std::io::Error::other)?;
|
||||
writeln!(out, "{line}")
|
||||
}
|
||||
|
||||
/// Whether the log has already said it is dropping records.
|
||||
static DROPPING: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
|
||||
|
||||
/// Says, once, that the log is dropping records, so a cut-short capture does not pass for a
|
||||
/// quiet run. Returns whether this call was the one that said it.
|
||||
fn note_dropped(error: &dyn std::fmt::Display) -> bool {
|
||||
let first = !DROPPING.swap(true, Ordering::Relaxed);
|
||||
if first {
|
||||
tracing::warn!(%error, "the wire log could not be written; later records may be missing");
|
||||
}
|
||||
first
|
||||
}
|
||||
|
||||
fn now_ms() -> u128 {
|
||||
SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_millis()).unwrap_or_default()
|
||||
}
|
||||
|
||||
/// Record one outgoing request exactly as it will be sent.
|
||||
///
|
||||
/// `headers` carries only what the adapter sets explicitly; credential header values become
|
||||
/// `<redacted>`, and the body goes through the shared secret redactor in case a key reached the
|
||||
/// prompt by some other route.
|
||||
pub fn record_request(
|
||||
provider: &str,
|
||||
url: &str,
|
||||
headers: &[(&str, &str)],
|
||||
body: &serde_json::Value,
|
||||
) {
|
||||
if !enabled() {
|
||||
return;
|
||||
}
|
||||
let headers: serde_json::Map<String, serde_json::Value> = headers
|
||||
.iter()
|
||||
.map(|(name, value)| {
|
||||
let secret = SECRET_HEADERS.contains(&name.to_ascii_lowercase().as_str());
|
||||
let value = if secret { "<redacted>" } else { *value };
|
||||
((*name).to_string(), serde_json::Value::String(value.to_string()))
|
||||
})
|
||||
.collect();
|
||||
let body = match serde_json::to_string(body) {
|
||||
Ok(text) => serde_json::from_str(&luxe_core::redact::process_secrets().redact(&text))
|
||||
.unwrap_or_else(|_| body.clone()),
|
||||
Err(_) => body.clone(),
|
||||
};
|
||||
append(serde_json::json!({
|
||||
"kind": "request",
|
||||
"call": current_call_id(),
|
||||
"ts_ms": now_ms(),
|
||||
"provider": provider,
|
||||
"url": url,
|
||||
"headers": headers,
|
||||
"body": body,
|
||||
}));
|
||||
}
|
||||
|
||||
/// Longest reply text kept verbatim; beyond this the record keeps the count and an excerpt.
|
||||
const MAX_TEXT: usize = 4_000;
|
||||
|
||||
/// Longest tool-call argument payload kept verbatim.
|
||||
const MAX_ARGS: usize = 2_000;
|
||||
|
||||
/// Most arrival samples kept, so a pathological stream can't unbound the record.
|
||||
const MAX_ARRIVALS: usize = 2_000;
|
||||
|
||||
/// Accumulates one call's response into a single record.
|
||||
///
|
||||
/// One line per event would be one line per *token* — unreadable, and it would bury the structure
|
||||
/// an audit is actually looking for. Instead the stream is folded into what came back (text, tool
|
||||
/// calls, usage, stop reason) plus an arrival timeline of `[ms_offset, chars]` pairs, which is what
|
||||
/// proves "renders as it arrives" without duplicating the text.
|
||||
#[derive(Default)]
|
||||
struct ResponseRecord {
|
||||
counts: std::collections::BTreeMap<&'static str, u64>,
|
||||
text: String,
|
||||
thinking_chars: usize,
|
||||
tool_calls: Vec<(String, String, String)>,
|
||||
usage: Option<serde_json::Value>,
|
||||
stop: Option<String>,
|
||||
errors: Vec<String>,
|
||||
arrival: Vec<(u128, usize)>,
|
||||
first_delta_ms: Option<u128>,
|
||||
}
|
||||
|
||||
impl ResponseRecord {
|
||||
fn observe(&mut self, event: &ProviderEvent, elapsed_ms: u128) {
|
||||
let kind = match event {
|
||||
ProviderEvent::Start => "start",
|
||||
ProviderEvent::TextStart { .. } => "text_start",
|
||||
ProviderEvent::TextDelta { delta, .. } => {
|
||||
if self.first_delta_ms.is_none() {
|
||||
self.first_delta_ms = Some(elapsed_ms);
|
||||
}
|
||||
if self.text.len() < MAX_TEXT {
|
||||
self.text.push_str(delta);
|
||||
}
|
||||
if self.arrival.len() < MAX_ARRIVALS {
|
||||
self.arrival.push((elapsed_ms, delta.chars().count()));
|
||||
}
|
||||
"text_delta"
|
||||
}
|
||||
ProviderEvent::TextEnd { .. } => "text_end",
|
||||
ProviderEvent::ThinkingStart { .. } => "thinking_start",
|
||||
ProviderEvent::ThinkingDelta { delta, .. } => {
|
||||
if self.first_delta_ms.is_none() {
|
||||
self.first_delta_ms = Some(elapsed_ms);
|
||||
}
|
||||
self.thinking_chars += delta.chars().count();
|
||||
if self.arrival.len() < MAX_ARRIVALS {
|
||||
self.arrival.push((elapsed_ms, delta.chars().count()));
|
||||
}
|
||||
"thinking_delta"
|
||||
}
|
||||
ProviderEvent::ThinkingSignature { .. } => "thinking_signature",
|
||||
ProviderEvent::ReasoningItem { .. } => "reasoning_item",
|
||||
ProviderEvent::ReasoningOpaque { .. } => "reasoning_opaque",
|
||||
ProviderEvent::RedactedThinking { .. } => "redacted_thinking",
|
||||
ProviderEvent::ThinkingEnd { .. } => "thinking_end",
|
||||
ProviderEvent::ToolCallStart { id, name, .. } => {
|
||||
self.tool_calls.push((id.clone(), name.clone(), String::new()));
|
||||
"tool_call_start"
|
||||
}
|
||||
ProviderEvent::ToolCallDelta { json_delta, .. } => {
|
||||
if let Some(call) = self.tool_calls.last_mut() {
|
||||
if call.2.len() < MAX_ARGS {
|
||||
call.2.push_str(json_delta);
|
||||
}
|
||||
}
|
||||
"tool_call_delta"
|
||||
}
|
||||
ProviderEvent::ToolCallEnd { .. } => "tool_call_end",
|
||||
ProviderEvent::Usage(usage) => {
|
||||
self.usage = Some(serde_json::json!({
|
||||
"prompt_tokens": usage.prompt_tokens,
|
||||
"completion_tokens": usage.completion_tokens,
|
||||
"total_tokens": usage.total_tokens,
|
||||
"cache_read_tokens": usage.cache_read_tokens,
|
||||
"cache_write_tokens": usage.cache_write_tokens,
|
||||
"reasoning_tokens": usage.reasoning_tokens,
|
||||
}));
|
||||
"usage"
|
||||
}
|
||||
ProviderEvent::PlanUsage(_) => "plan_usage",
|
||||
ProviderEvent::Done { reason } => {
|
||||
self.stop = Some(format!("{reason:?}"));
|
||||
"done"
|
||||
}
|
||||
ProviderEvent::Error { message, kind } => {
|
||||
self.errors.push(format!("{kind:?}: {message}"));
|
||||
"error"
|
||||
}
|
||||
};
|
||||
*self.counts.entry(kind).or_default() += 1;
|
||||
}
|
||||
|
||||
fn finish(self, call: u64, provider: &str, elapsed_ms: u128, completed: bool) {
|
||||
let text = luxe_core::redact::process_secrets().redact(&self.text);
|
||||
append(serde_json::json!({
|
||||
"kind": "response",
|
||||
"call": call,
|
||||
"ts_ms": now_ms(),
|
||||
"provider": provider,
|
||||
"elapsed_ms": elapsed_ms,
|
||||
"first_delta_ms": self.first_delta_ms,
|
||||
"drained": completed,
|
||||
"events": self.counts,
|
||||
"text": text,
|
||||
"thinking_chars": self.thinking_chars,
|
||||
"tool_calls": self.tool_calls.iter().map(|(id, name, args)| serde_json::json!({
|
||||
"id": id,
|
||||
"name": name,
|
||||
"arguments": luxe_core::redact::process_secrets().redact(args),
|
||||
})).collect::<Vec<_>>(),
|
||||
"usage": self.usage,
|
||||
"stop": self.stop,
|
||||
"errors": self.errors,
|
||||
"arrival": self.arrival,
|
||||
}));
|
||||
}
|
||||
}
|
||||
|
||||
fn record_error(call: u64, provider: &str, error: &ProviderError) {
|
||||
append(serde_json::json!({
|
||||
"kind": "error",
|
||||
"call": call,
|
||||
"ts_ms": now_ms(),
|
||||
"provider": provider,
|
||||
"error": luxe_core::redact::process_secrets().redact(&error.to_string()),
|
||||
}));
|
||||
}
|
||||
|
||||
/// Wraps any provider and records the event stream it produces.
|
||||
///
|
||||
/// Provider-agnostic on purpose: it sees normalized [`ProviderEvent`]s, so a new adapter is logged
|
||||
/// the day it exists. The request half lives in the adapters, which are the only place the final
|
||||
/// wire body is known.
|
||||
pub struct RecordingProvider {
|
||||
inner: Arc<dyn Provider + Send + Sync>,
|
||||
}
|
||||
|
||||
impl RecordingProvider {
|
||||
/// Wrap `inner`, or hand it back untouched when logging is off.
|
||||
pub fn wrap(inner: Arc<dyn Provider + Send + Sync>) -> Arc<dyn Provider + Send + Sync> {
|
||||
if enabled() {
|
||||
Arc::new(Self { inner })
|
||||
} else {
|
||||
inner
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[async_trait::async_trait]
|
||||
impl Provider for RecordingProvider {
|
||||
fn name(&self) -> &str {
|
||||
self.inner.name()
|
||||
}
|
||||
|
||||
async fn stream(
|
||||
&self,
|
||||
req: CompletionRequest,
|
||||
cancel: tokio::sync::watch::Receiver<bool>,
|
||||
) -> Result<futures::stream::BoxStream<'static, ProviderEvent>, ProviderError> {
|
||||
let call = SEQ.fetch_add(1, Ordering::Relaxed);
|
||||
let provider = self.inner.name().to_string();
|
||||
let started = std::time::Instant::now();
|
||||
|
||||
// The adapter records its request from inside this scope, so both halves share `call`.
|
||||
let stream = match CALL_ID.scope(call, self.inner.stream(req, cancel)).await {
|
||||
Ok(stream) => stream,
|
||||
Err(error) => {
|
||||
record_error(call, &provider, &error);
|
||||
return Err(error);
|
||||
}
|
||||
};
|
||||
|
||||
Ok(Box::pin(Recording {
|
||||
inner: stream,
|
||||
open: Some(OpenRecord { call, provider, started, record: ResponseRecord::default() }),
|
||||
}))
|
||||
}
|
||||
|
||||
// Forwarded, or wrapping a provider for the log would quietly switch its cache warming off
|
||||
fn prompt_cache_ttl(&self, req: &CompletionRequest) -> Option<std::time::Duration> {
|
||||
self.inner.prompt_cache_ttl(req)
|
||||
}
|
||||
|
||||
async fn warm_cache(
|
||||
&self,
|
||||
req: CompletionRequest,
|
||||
) -> Result<luxe_core::provider::Usage, ProviderError> {
|
||||
let call = SEQ.fetch_add(1, Ordering::Relaxed);
|
||||
let started = std::time::Instant::now();
|
||||
let warmed = CALL_ID.scope(call, self.inner.warm_cache(req)).await;
|
||||
match &warmed {
|
||||
// A response half, so `luxe wire` shows what the refresh read rather than a row of zeros
|
||||
Ok(usage) => {
|
||||
let mut record = ResponseRecord::default();
|
||||
record.observe(&ProviderEvent::Usage(usage.clone()), started.elapsed().as_millis());
|
||||
record.finish(call, self.inner.name(), started.elapsed().as_millis(), true);
|
||||
}
|
||||
Err(error) => record_error(call, self.inner.name(), error),
|
||||
}
|
||||
warmed
|
||||
}
|
||||
}
|
||||
|
||||
/// The in-flight half of a recorded stream.
|
||||
struct OpenRecord {
|
||||
call: u64,
|
||||
provider: String,
|
||||
started: std::time::Instant,
|
||||
record: ResponseRecord,
|
||||
}
|
||||
|
||||
/// A stream that folds what passes through it into one response record.
|
||||
///
|
||||
/// The record is flushed on **drop**, not just on end-of-stream: the engine stops polling the
|
||||
/// moment it sees `Done` and drops the rest, so an end-of-stream hook alone would silently log
|
||||
/// nothing for a normal turn. `drained` in the record says which of the two happened.
|
||||
struct Recording<S> {
|
||||
inner: S,
|
||||
open: Option<OpenRecord>,
|
||||
}
|
||||
|
||||
impl<S> Recording<S> {
|
||||
fn flush(&mut self, drained: bool) {
|
||||
if let Some(open) = self.open.take() {
|
||||
let elapsed = open.started.elapsed().as_millis();
|
||||
open.record.finish(open.call, &open.provider, elapsed, drained);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl<S> futures::Stream for Recording<S>
|
||||
where
|
||||
S: futures::Stream<Item = ProviderEvent> + Unpin,
|
||||
{
|
||||
type Item = ProviderEvent;
|
||||
|
||||
fn poll_next(
|
||||
self: std::pin::Pin<&mut Self>,
|
||||
cx: &mut std::task::Context<'_>,
|
||||
) -> std::task::Poll<Option<Self::Item>> {
|
||||
let this = self.get_mut();
|
||||
match std::pin::Pin::new(&mut this.inner).poll_next(cx) {
|
||||
std::task::Poll::Ready(Some(event)) => {
|
||||
if let Some(open) = this.open.as_mut() {
|
||||
open.record.observe(&event, open.started.elapsed().as_millis());
|
||||
}
|
||||
std::task::Poll::Ready(Some(event))
|
||||
}
|
||||
std::task::Poll::Ready(None) => {
|
||||
this.flush(true);
|
||||
std::task::Poll::Ready(None)
|
||||
}
|
||||
std::task::Poll::Pending => std::task::Poll::Pending,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl<S> Drop for Recording<S> {
|
||||
fn drop(&mut self) {
|
||||
self.flush(false);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn credential_headers_are_redacted_and_protocol_headers_are_not() {
|
||||
for name in ["Authorization", "x-api-key", "API-KEY", "Cookie"] {
|
||||
assert!(
|
||||
SECRET_HEADERS.contains(&name.to_ascii_lowercase().as_str()),
|
||||
"{name} must be treated as a credential"
|
||||
);
|
||||
}
|
||||
for name in ["anthropic-version", "Content-Type", "Accept", "anthropic-beta"] {
|
||||
assert!(
|
||||
!SECRET_HEADERS.contains(&name.to_ascii_lowercase().as_str()),
|
||||
"{name} is protocol, not a credential"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// A record the log cannot take is said, once, rather than dropped without a word.
|
||||
///
|
||||
/// The break this catches: every failure was swallowed, so a capture that stopped partway read
|
||||
/// as a session that went quiet.
|
||||
#[test]
|
||||
fn a_record_the_log_cannot_take_is_said_once() {
|
||||
struct Full;
|
||||
impl Write for Full {
|
||||
fn write(&mut self, _: &[u8]) -> std::io::Result<usize> {
|
||||
Err(std::io::Error::other("disk full"))
|
||||
}
|
||||
fn flush(&mut self) -> std::io::Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
append_to(&Mutex::new(Full), &serde_json::json!({"kind": "request"}));
|
||||
let error = std::io::Error::other("again");
|
||||
assert!(!note_dropped(&error), "the append said it, so this one does not");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn a_call_id_is_zero_outside_a_recorded_call_and_set_inside_one() {
|
||||
assert_eq!(current_call_id(), 0, "an unwrapped adapter still records, under call 0");
|
||||
CALL_ID.scope(7, async { assert_eq!(current_call_id(), 7) }).await;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user