dsh-trae-connect

DSH Trae Connect

English | 简体中文

Plug the models built into the Trae desktop app (ByteDance's AI coding assistant) — DeepSeek V3/R1, GPT-4o, GPT-4.1, Claude 3.5/3.7 Sonnet, Gemini 2.5 and more — into DeepSeek Harness (DSH) as a zero-configuration model provider. It follows the bridging architecture of dsh-workbuddy-connect: a loopback OpenAI-compatible endpoint + a pi-ai provider + a browser settings card.

The upstream protocol was reverse-engineered from trae2api (MIT), which translates OpenAI chat-completions into Trae's private IDE API.

Features

• Zero-configuration credentials. The plugin reads Trae's desktop sign-in state directly; there is nothing to paste into DSH.
• Automatic model catalog. The available Trae models are fetched from the upstream at startup and refreshed periodically; they show up in DSH's model picker under the trae provider (for example deepseek-v3, deepseek-r1, gpt-4o, claude-3-7-sonnet).
• OpenAI-compatible loopback shim. A local endpoint on 127.0.0.1 translates Trae's private SSE stream into OpenAI chat-completions SSE in real time, including reasoning content. The shim is protected by four independent loopback checks and is never exposed beyond localhost.
• Two credential sources with automatic preference. Desktop session token first, self-renewing OAuth configuration second (details below).
• Stable device identity. Device headers (x-device-id, x-machine-id, ...) are generated once and persisted, so the upstream sees a consistent client instead of a new device per request.
• Settings card in the browser. A card under Settings -> Plugins (settings.trae) shows the current sign-in state and the number of available models, and tolerates registration failures of either half.
• Web status routes. The host half exposes status/capture/checkin routes under its settings namespace, which the companion plugin dsh-points-checkin reuses for TRAE points and daily check-in.
• CLI diagnostics. dsh-trae-connect ships subcommands doctor, status, logout, and setup for checking credential health without opening the browser.

Requirements

• DSH >=0.1.1-rc.1 (built and tested against 0.1.5-rc.2).
• The Trae desktop app signed in at least once (for the desktop-session credential source), or a Trae OAuth refresh token (for the auto-renewing source).

Install

# Preferred: install straight from GitHub (no npm involved; prebuilt lib is committed)
dsh plugin --profile web add github:lament-z/dsh-trae-connect

# Alternative: from npm
dsh plugin --profile web add @lament_z/dsh-trae-connect

# From a local clone / working copy
dsh plugin --profile web add link:<this directory>

Then restart dsh web and reload the page. The first start also compiles nothing and asks for nothing — the plugin activates with the host.

Credentials (two sources, automatic preference)

1. Desktop session (zero configuration). Trae stores its x-ide-token in the Electron Local Storage/leveldb. Place an exported <TraeAppDir>/trae-auth.json in the Trae app directory and the plugin picks it up automatically (fields: ideToken / appId / clientId / userId / device / expiresAt). This source takes priority over the OAuth copy below.
   • macOS app directory candidates: ~/Library/Application Support/TRAE SOLO CN and Trae.
   • Override the directory with the TRAE_APP_DIR environment variable.
2. OAuth configuration (auto-renewing). Set the environment variables TRAE_APP_ID / TRAE_CLIENT_ID / TRAE_REFRESH_TOKEN / TRAE_USER_ID. The plugin exchanges the refresh token at Trae's OAuth endpoint and rotates x-ide-token on its own, without reopening the desktop app.

The desktop session token cannot be renewed by itself — when it expires, reopen Trae once. The OAuth configuration source self-heals and is recommended for long-running hosts.

Usage

1. Install and restart dsh web (see above).
2. Open the DSH web page and check Settings -> Plugins: the trae card should show a signed-in state and a model count.
3. Open the model picker: Trae models appear under the trae provider and can be used in any conversation like built-in models.
4. Optional diagnostics from a terminal:

dsh-trae-connect doctor   # check credential health and upstream reachability
dsh-trae-connect status   # current credential source, expiry, model count
dsh-trae-connect logout   # drop the stored desktop-session copy
dsh-trae-connect setup    # guided setup of the OAuth environment variables

Upstream protocol (implemented)

Purpose	Endpoint
Chat	https://a0ai-api-sg.byteintlapi.com/api/ide/v1/chat (POST)
Model catalog	https://a0ai-api-sg.byteintlapi.com/api/ide/v1/model_list?type=chat (GET)
Token exchange	https://api-sg-central.trae.ai/cloudide/api/v3/trae/oauth/ExchangeToken (POST)

Every upstream request carries the Trae client headers: x-app-id, x-ide-version (1.2.10), x-ide-version-code (20250325), x-ide-version-type (stable), x-device-cpu, x-device-id, x-machine-id, x-device-brand, x-device-type, x-ide-token (auth), Host, and an empty User-Agent.

The upstream returns Trae's private SSE events (output carrying response/reasoning_content, request_wait_in_queue for queueing); the shim in src/upstream.ts rewrites them into OpenAI chat-completions SSE on the fly for the pi-ai provider. Model-name mapping (OpenAI id <-> Trae upstream name) lives in the same file, for example deepseek-v3 <-> deepseek-V3, claude-3-7-sonnet <-> aws_sdk_claude37_sonnet.

Billing

Trae has no public balance endpoint (same as workbuddy-connect), so no points are shown — only the number of available models. For TRAE points and daily check-in, use dsh-points-checkin.

Architecture

• Host (src/index.ts): starts the loopback shim, registers the trae provider, installs the settings section, and refreshes the model catalog.
• Shim (src/shim.ts): the OpenAI-compatible endpoint bound to 127.0.0.1 with four-way loopback authentication.
• Client (src/client/index.tsx): the settings card under Settings -> Plugins showing sign-in state and model count.
• CLI (src/bin.ts): doctor / status / logout / setup.
• Web status (src/web-status.ts): status/capture/checkin routes reused by dsh-points-checkin.

Troubleshooting

• No models appear. Run dsh-trae-connect doctor. If the desktop session expired, reopen the Trae desktop app and restart dsh web; or configure the OAuth environment variables for self-renewal.
• The settings card is missing. Both halves register independently; check the DSH boot log for dsh-trae-connect errors. A failed card never blocks the provider.
• Credential errors right after Trae re-login. The exported trae-auth.json is stale — re-export it or switch to the OAuth source.

License

MIT