Upstream Fingerprinting & Signals
Relevant source files
The following files were used as context for generating this wiki page:
Upstream Fingerprinting & Signals manages the translation between downstream client requests and official upstream client behavior. This system ensures that the proxy presents itself as a legitimate official client by simulating specific "signals" such as official tool signatures, system prompt structures, and device fingerprints. Failure to match these signals results in upstream rejection, typically manifesting as HTTP 503 errors or session admission failures.
Sources: src/upstream/signals/AGENTS.md:6-12, README.md:145-155, test/suites/entries/verify/tool/name-mapping.ts:7-12
Signal Architecture and Data Flow
The signaling system acts as a translation layer between two distinct environments: the downstream agent (OpenAI-compatible) and the upstream official service. It performs bi-directional mapping of tool names, parameter shapes, and system prompt dynamic segments.
The system ensures that out-bound requests contain only official tool signatures to satisfy upstream fingerprinting requirements while restoring downstream-specific names in responses to maintain compatibility.
Sources: src/upstream/signals/AGENTS.md:6-14, test/suites/entries/verify/tool/name-mapping.ts:14-22
Tool Name and Parameter Mapping
The proxy maintains a bi-directional mapping table to convert common downstream tool names (e.g., bash, read) into their official upstream equivalents (e.g., run_terminal_command, read_files).
Bi-Directional Tool Mapping Logic
- Downlink (Request): Downstream tool names are mapped to official equivalents if they exist; otherwise, they are passed through to avoid silent deletion.
- Uplink (Response): Official tool names in the upstream response are restored to the names originally declared by the downstream client.
| Downstream Name | Official Upstream Equivalent | Purpose |
|---|---|---|
bash | run_terminal_command | Execute shell commands |
write | write_file | Create or update files |
read | read_files | Read file content |
edit | str_replace | Text replacement in files |
ask_user_question | ask_questions | User confirmation/input |
Sources: test/suites/entries/verify/tool/name-mapping.ts:60-75, src/upstream/foreign-client-signals.ts:133-145
Parameter Translation Rules
Parameter shapes often differ between official tools and downstream clients. The translateParamsForDownstream function applies specific rules to prevent validation failures:
- Synthesis: Adds required fields that the upstream lacks (e.g., adding a
descriptiontobashcommands). - Normalization: Converts types (e.g., converting upstream
timeout_seconds: -1to downstreamtimeoutMs: undefined). - Pruning: Removes extra properties to satisfy strict downstream schemas (
additionalProperties: false).
Sources: src/upstream/signals/AGENTS.md:23-35, test/suites/entries/verify/tool/param/dispatch-ready.ts:108-115
System Prompt Fingerprinting
Upstream services use specific dynamic segments in the system prompt to identify official clients. The proxy dynamically renders these segments to ensure they do not appear as static "frozen" snapshots from previous captures.
Dynamic Rendering Segments
The renderWorkerSystem function processes the official worker template to inject real-time metadata:
- Current Date: Replaces captured dates with the current runtime date in the official format (e.g.,
January 2, 2030). - Repository Stats: Generates line-separated key-value pairs inside
<repository_stats>tags rather than JSON objects. - Git Metadata: Injects
changed_file_pathswith specific counts and labels.
Foreign Client Detection Signals
The proxy monitors "foreign client signals" based on mirrored upstream constants. These signals are used to detect if a downstream request might trigger an upstream ban or downgrade.
Key Signal Categories
- Harness Names: Specific tool names like
Agent,KillShell(Claude Code) orShell(Cursor) that are never used by the official client. - Prompt Markers: Phrases such as "You are Claude Code" or specific version strings like
cc_version=. - Generic Tools: Common names like
web_searchorglobwhich, while used by the official client, are not unique enough to form a signature.
| Signal Type | Example | Impact |
|---|---|---|
| Forbidden Tool | KillShell, browser_exec | High risk of 503/Ban |
| Official Signature | run_terminal_command, str_replace | Required for admission |
| Prompt Marker | cc_entrypoint=, cc_version= | Triggers foreign detection |
Sources: src/upstream/foreign-client-signals.ts:40-65, src/upstream/foreign-client-signals.ts:85-115
Tool Injection Selection
The system filters which official tools to inject into a session based on the downstream client's declared capabilities.
- Injection Logic: The
injectableOfficialTools(declared)function only includes official tools that have a valid mapping back to a tool actually declared by the client. - Safety Floor: The system no longer allows empty tool sets. If no tools are selected, it defaults to injecting the full official set to avoid upstream 503 errors caused by missing client signatures.
- Grouping: Tools are categorized as
common(reachable by downstream) ororphan(only available to official clients).
Sources: test/suites/entries/verify/tool/official-select.ts:50-65, test/suites/entries/verify/tool/official-select.ts:77-85
Upstream Fingerprinting & Signals ensures the proxy remains invisible to upstream detection by maintaining strict parity with official client behavior while preserving the flexibility of downstream agents.