# Trace System

Per-call debug traces for inspecting request/response flow. Every API call writes a structured trace directory.

## Location

```
~/.config/antigravity-proxy/traces/{YYYY-MM-DD}/{HH-MM-SS.sss}_{cascade_short}/
```

Disable with `--no-trace`.

## Files Per Trace

| File            | Purpose                                                    |
| --------------- | ---------------------------------------------------------- |
| `meta.txt`      | One-line grep-friendly summary                             |
| `summary.md`    | Human-readable trace overview with tables                  |
| `request.json`  | Client request metadata (message count, preview, tools)    |
| `response.json` | Token usage (input, output, thinking, cache)               |
| `turns.json`    | Per-turn details (MITM match, gate wait, response preview) |

## Data Flow

```mermaid
sequenceDiagram
    participant H as API Handler
    participant T as TraceHandle
    participant D as Disk

    H->>T: trace.start(cascade_id, endpoint, model)
    H->>T: set_client_request(preview, tool_count, ...)
    Note over H: Request processing...
    H->>T: start_turn()
    H->>T: record_mitm_match(gate_wait_ms)
    Note over H: Response arrives...
    H->>T: record_response(text_len, preview, finish_reason)
    H->>T: set_usage(input, output, thinking, cache)
    H->>T: finish("completed")
    T->>D: Write meta.txt, summary.md, request.json, response.json, turns.json
```

## Example: meta.txt

```
cascade=e57e3ddf endpoint=POST gemini model=gemini-3-flash outcome=completed duration=1865ms stream=false
```

## Example: request.json

```json
{
  "message_count": 2,
  "tool_count": 3,
  "tool_round_count": 0,
  "user_text_len": 46,
  "user_text_preview": "You are a pirate.\n\nSay ahoy in exactly 3 words",
  "system_prompt": true,
  "has_image": false
}
```

## Example: turns.json

```json
[
  {
    "turn": 0,
    "mitm_matched": true,
    "gate_wait_ms": 90,
    "response": {
      "text_len": 18,
      "thinking_len": 0,
      "text_preview": "Ahoy there, matey!",
      "finish_reason": "stop",
      "grounding": false
    }
  }
]
```

## Example: response.json

```json
{
  "usage": {
    "input_tokens": 284,
    "output_tokens": 13,
    "thinking_tokens": 37,
    "cache_read": 0
  }
}
```

## Outcomes

| Outcome          | When                              |
| ---------------- | --------------------------------- |
| `completed`      | Normal response received          |
| `tool_call`      | Model returned function calls     |
| `upstream_error` | Google API returned an error      |
| `timeout`        | No response within timeout window |
| `mitm_timeout`   | MITM gate match timed out         |

## Agent Usage

Traces are designed for LLM consumption. To inspect the last trace:

```bash
# Find latest trace
ls -t ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/ | head -1

# Read the summary
cat ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/$(ls -t ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/ | head -1)/summary.md

# Grep for failures
grep 'outcome=.*error\|outcome=.*timeout' ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/*/meta.txt
```