from __future__ import annotations """Structured DEBUG traces and stream cleanup warnings. Trace payloads are preserved in ``record.extra.trace_payload`` by Loguru. Conversation and Claude Code prompts are logged verbatim unless values live under sanitized credential keys (e.g. ``api_key``, ``authorization``). The default INFO log level excludes these detailed request traces. """ import asyncio import sys from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping from typing import Any, Protocol from loguru import logger from free_claude_code.core.async_iterators import try_close_async_iterator class _FramedOutput(Protocol): @property def frames(self) -> tuple[str, ...]: ... TRACE_PAYLOAD_BINDING = "trace_payload" _SECRET_VALUE_KEYS = frozenset( k.lower() for k in ( "authorization", "x-api-key", "x-goog-api-key", "api-key", "anthropic-auth-token", "api_key", "api_keys", "password", "secret", "token", "bearer_token", "openapi_token", "nvidia-api-key", "aws_bearer_token_bedrock", ) ) def sanitize_trace_value(obj: Any) -> Any: """Recursively copy JSON-like structures redacting credential-shaped keys.""" if isinstance(obj, Mapping): out: dict[str, Any] = {} for k, v in obj.items(): name = str(k).lower() if name in _SECRET_VALUE_KEYS or name.replace("-", "_").endswith( ( "_api_key", "_api_keys", "_api_token", "_api_tokens", "_secret_key", "_secret_keys", ) ): out[str(k)] = "" else: out[str(k)] = sanitize_trace_value(v) return out if isinstance(obj, tuple | list): return [sanitize_trace_value(x) for x in obj] return obj def trace_event( lazy_fields: Callable[[], Mapping[str, Any]] | None = None, /, *, stage: str, event: str, source: str, **fields: Any, ) -> None: """Defer sanitization and the optional field factory until DEBUG is enabled.""" logger.opt(lazy=True).debug( "TRACE {}", lambda: event, trace_payload=lambda: sanitize_trace_value( { "stage": stage, "event": event, "source": source, **fields, **(lazy_fields() if lazy_fields is not None else {}), } ), ) async def close_stream_input( iterator: object, *, owner: str, source: str, preserved_error: BaseException | None, ) -> None: """Close one transform input and observe cleanup failure without raising it.""" close_error = await try_close_async_iterator(iterator) if close_error is None: return logger.bind( stage="lifecycle", event="stream.input.close_failed", source=source, owner=owner, close_exc_type=type(close_error).__name__, preserved_exc_type=( type(preserved_error).__name__ if preserved_error is not None else None ), ).opt(exception=close_error).warning("Stream input cleanup failed") def extract_claude_session_id_from_headers(headers: Mapping[str, str]) -> str | None: """Best-effort session id forwarded by Claude Code / SDK via HTTP.""" lowered = {str(k).lower(): v for k, v in headers.items() if isinstance(v, str)} for key in ( "anthropic-session-id", "x-anthropic-session-id", "claude-session-id", "x-claude-session-id", ): candidate = lowered.get(key) if candidate: return candidate return None async def traced_async_stream[T: str | _FramedOutput]( agen: AsyncIterator[T], *, stage: str, source: str, complete_event: str, interrupted_event: str, chunk_event: str | None = None, chunk_interval: int = 250, extra: Mapping[str, Any] | None = None, ) -> AsyncGenerator[T]: """Emit TRACE rows when a text stream completes, fails, cancels, or periodically.""" common = dict(extra or {}) count = 0 nbytes = 0 interrupted = False try: async for chunk in agen: count += 1 nbytes += sum( len(frame.encode("utf-8", errors="replace")) for frame in ((chunk,) if isinstance(chunk, str) else chunk.frames) ) if chunk_event and chunk_interval > 0 and count % chunk_interval == 0: trace_event( stage=stage, event=chunk_event, source=source, stream_chunks_so_far=count, stream_bytes_so_far=nbytes, **common, ) yield chunk except GeneratorExit: raise except asyncio.CancelledError: interrupted = True trace_event( stage=stage, event=interrupted_event, source=source, stream_chunks=count, stream_bytes=nbytes, outcome="cancelled", **common, ) raise except BaseExceptionGroup as grp: interrupted = True trace_event( stage=stage, event=interrupted_event, source=source, stream_chunks=count, stream_bytes=nbytes, outcome="exception_group", note=str(grp), **common, ) raise except Exception as exc: interrupted = True trace_event( stage=stage, event=interrupted_event, source=source, stream_chunks=count, stream_bytes=nbytes, outcome="error", exc_type=type(exc).__name__, **common, ) raise finally: await close_stream_input( agen, owner="traced_async_stream", source=source, preserved_error=sys.exception(), ) if not interrupted: trace_event( stage=stage, event=complete_event, source=source, stream_chunks=count, stream_bytes=nbytes, outcome="ok", **common, ) def provider_chat_body_snapshot(body: Mapping[str, Any]) -> dict[str, Any]: """Sanitized OpenAI-compat chat body subset for traces (conversation text verbatim).""" keys = ("model", "messages", "tools", "tool_choice", "temperature", "max_tokens") snap = {k: body[k] for k in keys if k in body and body[k] is not None} return sanitize_trace_value(snap)