CLI Bridge (Bun RPC)
Relevant source files
The following files were used as context for generating this wiki page:
The CLI Bridge facilitates communication between the main Node.js proxy service and the official upstream endpoints by executing requests within the Bun runtime. It ensures that outgoing traffic matches the TLS fingerprint and request structure of the official desktop client, thereby minimizing detection as a third-party agent. The main Node.js service delegates complex upstream calls—including session admission and chat completions—to this bridge via a Remote Procedure Call (RPC) mechanism.
Sources: cli-bridge/README.md:3-23, cli-bridge/AGENTS.md:7-10
Architecture and Execution Flow
The CLI Bridge eliminates TLS fingerprint discrepancies by utilizing the Bun runtime (v1.4.2), which is the same runtime used by the official client's orchestrator. The Node.js parent process spawns a Bun child process to perform cryptographic operations, device signing, and catalog protocol handling.
Request Delegation Flow
The following diagram illustrates how a request moves from the proxy service through the Bun bridge to the upstream API.
The bridge process handles Ed25519 device signatures and maintains specific protocol headers like x-freebuff-catalog-protocol.
Sources: cli-bridge/README.md:25-36, cli-bridge/README.md:58-75
RPC Actions and Endpoints
The bridge exposes a specific set of actions that the Node.js service can invoke. These actions are managed in an action table and dispatched based on the action field in the RPC payload.
| Action | Purpose | Key Parameters |
|---|---|---|
catalog | Fetches the model catalog from upstream | cfg |
session | Creates a new session or admission | cfg, modelKey |
admit | Performs admission for a specific model | cfg, handle |
chat | Initiates a new chat completion | messages, tools, stream |
reuse | Resumes an existing chat session | instanceId, runId, messages |
Sources: cli-bridge/README.md:52-56, cli-bridge/lib/upstream/actions.ts
Config Passthrough Requirements
To ensure console settings take effect, the bridge must explicitly pass through configuration fields. Key fields that must be preserved during delegation include:
officialToolNames: Controls which official tools are injected.systemPrompt: Passes custom or official system templates.layer: Specifies the provider layer (e.g., worker, manager).reasoningEffort: Controls model reasoning intensity.
Sources: cli-bridge/AGENTS.md:12-16, test/suites/entries/verify/config-passthrough.ts:10-25
Tool Mapping and Translation
The CLI Bridge maintains a critical mapping between downstream tool names and official upstream tool names. This ensures compatibility with the official tool fingerprint.
Tool Mapping Architecture
The mapping serves two directions: translating downstream requests to upstream formats and reverting upstream responses back for the downstream client.
Mapping Consistency
A strict contract exists between the Node.js side (src/upstream/signals/tool-name-map.ts) and the Bun side (cli-bridge/lib/tool-map.ts). Both sides must contain identical mapping entries to avoid "unknown tool" errors or inconsistent behavior during session reuse. Mapping failures or silent drops are prohibited; if no mapping exists, the original tool name is retained rather than discarded.
Sources: cli-bridge/AGENTS.md:18-22, cli-bridge/lib/tool-map.ts, src/upstream/signals/AGENTS.md:46-51
Implementation Details
The Bun-side implementation is structured to avoid unnecessary dependencies, focusing on direct upstream communication.
Module Structure
| Path | Responsibility |
|---|---|
cli-bridge/serve.ts | The entry point for the bridge server. |
cli-bridge/lib/upstream/bridge.ts | Assembles various upstream endpoints into a bridge object. |
cli-bridge/lib/upstream/actions.ts | The dispatch table for RPC commands. |
cli-bridge/lib/tool-map.ts | Holds the MAP_TOOLS logic for tool name translation. |
Sources: cli-bridge/AGENTS.md:29-35, cli-bridge/serve.ts
RPC Payload Structure
RPC calls typically involve a JSON payload sent to the Bun process. An example reuse action payload involves the following structure:
{
"action": "reuse",
"modelKey": "m-1",
"instanceId": "inst-9",
"messages": [{"role": "user", "content": "hello"}],
"tools": [],
"stream": true,
"layer": "worker",
"officialToolNames": ["read_files"],
"systemPrompt": { "mode": "custom", "text": "..." }
}
Sources: test/suites/entries/verify/config-passthrough.ts:88-100
Conclusion
The CLI Bridge serves as the high-fidelity communication layer for the freebuff-proxy project. By executing upstream requests within a Bun environment identical to the official client, it preserves TLS integrity and ensures that all downstream configuration—such as tool injection and system prompts—is correctly translated and transmitted to the official endpoints.