trae-native-debug - SKILL.md Agent Skill

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.

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.

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.
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.
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.
If Trae updated or offsets moved, read references/update-recovery.md.
If unsure why a prior approach is rejected, read references/native-route-map.md before creating new probes.

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.

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.