trae-native-debug

name	trae-native-debug
description	Maintain, debug, and recover MTGA's Trae native custom-model route. Use when Trae native integration fails, Trae updates shift ai_agent.dll hook offsets, errors such as 4028/4054/429 appear, native rewriter or SseOpenPayload URL rewriting needs diagnosis, or Codex needs to avoid repeating prior renderer-JS/private-protocol dead ends.

Trae Native Debug

Operating Rules

• Treat the active integration point as native Rust-side URL rewriting in ai_agent.dll, not renderer JS.
• Prefer the existing runtime path in python-src/modules/trae_patch/ and service glue in python-src/modules/services/trae_native_route.py.
• Keep python-src/scripts/trae_patch/ for repro, CDP triggering, and maintenance probes only. Do not move runtime-required code back into scripts.
• Do not hand-roll Trae private SSE/WebSocket events unless the user explicitly asks to compare alternatives. The current goal is to reuse Trae's native parser by rewriting the outgoing request URL before reqwest.
• Avoid noisy foreground probes. Capture long output to files or existing JSONL logs, summarize only the relevant events, and stop background processes when done.
• Do not stage changes unless the user explicitly asks. This project has a history of large touched sets during Trae debugging.

Workflow

1. Classify the failure before changing code.

   • 4028: generic Trae custom-model failure. It can mean auth, unreachable local service, wrong URL, 4xx, or malformed response.
   • 4054: usually means Trae's native/custom-model tunnel path rejected or could not consume the stream; prior private protocol hand-roll attempts hit this.
   • 429: usually caused by repeated live upstream probes or duplicate requests; throttle and inspect request counts before blaming auth.

2. Confirm which path is under test.

   • Native route should launch Trae with CDP, start local loopback on 127.0.0.1:18083, and run the native rewriter.
   • Legacy reverse-hosts route is separate. Shared proxy behavior such as config hot update should flow through ProxyApp.apply_runtime_config().
   • If debugging a route choice or UI config, inspect settings/state first; otherwise stay native.

3. Reproduce with the smallest useful surface.

   • For module availability: uv run python -m modules.trae_patch.trae_native_sse_open_url_rewriter --help
   • For byte-pattern drift: run scripts/trae_patch/trae_native_byte_pattern.py with the known URL-copy pattern.
   • For a real custom-model session: use scripts/trae_patch/trae_native_custom_model_session.py.
   • For UI-triggered repro without manual clicking: use scripts/trae_patch/trae_cdp_send_chat.py.

4. If Trae updated or offsets moved, read references/update-recovery.md.

5. If unsure why a prior approach is rejected, read references/native-route-map.md before creating new probes.

Known Stable Facts

• The useful native chain is: CustomModelProxyManager -> official custom-model WebSocket tunnel -> SSE instruction -> reqwest -> user base_url.
• The current patch avoids Trae's private tunnel protocol by rewriting the final URL used for the outgoing OpenAI-compatible request.
• Renderer/global scans for BootConfig, MNI channel interception, and hand-built JS/internal events were negative or higher-maintenance routes.
• The known URL-copy byte pattern is 48 8b 52 08 4d 8b 46 10 48 8d 8d 20 01 00 00; the call offset used by the rewriter is 0x0F.

Resources

• references/native-route-map.md: architecture, file map, and prior dead ends.
• references/update-recovery.md: procedure for recovering after Trae version changes or breakpoint drift.