File size: 6,825 Bytes
e99df76
 
2415446
691dc7c
2415446
61bb677
 
2415446
691dc7c
2415446
 
e99df76
a9e27c0
2415446
 
 
 
 
a9e27c0
 
 
 
 
 
2415446
 
 
 
 
 
 
f7872b8
 
2415446
 
f7872b8
2415446
 
 
 
 
 
f7872b8
2415446
 
 
 
 
 
 
 
 
f7872b8
 
 
 
 
 
 
 
 
 
 
2415446
 
 
 
 
 
 
 
 
e99df76
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2415446
 
 
 
 
 
 
 
 
 
 
 
 
 
e99df76
2415446
 
 
 
 
 
 
 
e99df76
2415446
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
a9e27c0
 
2415446
 
 
 
 
 
 
 
a9e27c0
8e438ab
2415446
 
 
 
 
 
 
a9e27c0
 
 
 
2415446
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
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)] = "<redacted>"
            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)