Files

Nikketryhard 3d87c04d20 docs: overhaul docs, add architecture and traces, update README/GEMINI

- Add docs/architecture.md with 4 mermaid diagrams
- Add docs/mitm.md with 3 mermaid diagrams (replaces mitm-interception-status)
- Add docs/traces.md documenting per-call trace system
- Rewrite README.md to be concise with mermaid and doc refs
- Rewrite GEMINI.md for core philosophy and agent usage
- Clean extension-server-analysis.md (remove stale debug sections)
- Delete temp docs: standalone-ls-todo, panel-stream-investigation,
  endpoint-gap-analysis, request-comparison

2026-02-18 01:31:18 -06:00

3.1 KiB

Raw Blame History

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

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

{
  "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

[
  {
    "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

{
  "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:

# 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

3.1 KiB Raw Blame History