feat(translation): API translation proxy — enable Claude integration cross-platform

[dean0x]

Summary

Implement a translation proxy infrastructure that enables API translation from other LLM providers to Claude SDK-compatible JSON. This supports multi-agent orchestration across different provider ecosystems (OpenAI, Anthropic SDK, Codex, Gemini, etc.).

Changes

• ProxyManager: Core translation orchestration with codec registry and middleware support
• API Translation Codecs: Provider-specific implementations (OpenAI→Claude, Codex→Claude, Gemini→Claude)
• ProxiedClaudeAdapter: Wraps MCP adapters to intercept and translate outbound API calls
• Bootstrap Integration: Configure translation proxies via translate field in AgentConfig
• Test Suite: Full TDD coverage of IR, codecs, middleware, and proxy behaviors

Breaking Changes

None

Testing

• ✅ IR (Intermediate Representation) codec tests
• ✅ Provider-specific codec tests
• ✅ Middleware chain tests
• ✅ ProxyManager lifecycle tests
• ✅ Bootstrap integration tests
• ✅ All new test suites passing

Related Issues

Closes #152 (API translation proxy core)

[greptile-apps]

Confidence Score: 5/5

Safe to merge — all known P1 issues have been resolved; remaining findings are observability gaps and an edge-case flush omission

No P0 or P1 findings remain. The three P2 items are: (1) streaming abort returns 502 instead of 499, (2) LoggingMiddleware response log never fires on the streaming path, and (3) flush() doesn't close active tool calls on abnormal stream termination. None affect correctness on the happy path.

src/translation/codecs/openai-codec.ts (flush gap), src/translation/middleware/logging.ts (streaming observability), src/translation/proxy/translation-proxy.ts (abort code inconsistency)

Important Files Changed

Filename	Overview
src/translation/proxy/translation-proxy.ts	Core HTTP proxy server — well-structured with proper per-request middleware isolation; minor inconsistency in streaming abort error code (502 vs 499)
src/translation/codecs/openai-codec.ts	OpenAI stream parser — prior tool-call re-keying bug fixed via openaiToCanonicalIndex; flush() doesn't close active tool calls, creating a gap for malformed/truncated streams
src/translation/codecs/anthropic-codec.ts	Anthropic source codec — thinking block lifecycle (start/delta/stop) correctly implemented; serialization and parsing look correct
src/translation/proxy/proxy-manager.ts	ProxyManager lifecycle — shared PromptCacheState correctly hoisted out of the per-request factory; start/stop are idempotent
src/translation/middleware/logging.ts	LoggingMiddleware — processResponse is dead for streaming (dominant path); response-level debug log is never emitted in practice
src/translation/middleware/prompt-cache.ts	PromptCacheMiddleware — shared state cross-request race fixed; lastPrefixHash still never updated on streaming path (processStreamEvent absent), leaving cache-hit annotation permanently inactive for streaming
src/translation/middleware/tool-name-mapping.ts	ToolNameMappingMiddleware — deterministic truncation with SHA suffix prevents collisions; per-request instances prevent cross-request map bleed
src/translation/proxy/proxied-claude-adapter.ts	ProxiedClaudeAdapter — cleanly overrides resolveBaseUrl/resolveModel/resolveAuth to isolate Claude Code from backend config; constructor-injected port is stable
src/bootstrap.ts	Bootstrap integration — proxy startup eagerly awaited before agentRegistry factory runs; fatal-on-config-exists policy prevents silent fallback
src/translation/proxy/stream-translator.ts	StreamTranslator — reversed middleware pre-computed at construction; SSE line routing correct; flush delegates to parser

Sequence Diagram

sequenceDiagram
    participant CC as Claude Code
    participant PA as ProxiedClaudeAdapter
    participant TP as TranslationProxy (127.0.0.1:PORT)
    participant MW as Middleware Pipeline
    participant ST as StreamTranslator
    participant OB as OpenAI Backend

    CC->>PA: spawn with ANTHROPIC_BASE_URL
    CC->>TP: POST /v1/messages (Anthropic format)
    TP->>TP: AnthropicCodec.parseRequest
    TP->>MW: runRequestMiddleware
    MW-->>TP: processed CanonicalRequest
    TP->>TP: OpenAICodec.serializeRequest
    alt Streaming
        TP->>OB: POST /chat/completions stream=true
        OB-->>TP: SSE chunks
        loop per SSE line
            TP->>ST: processLine
            ST->>MW: applyMiddleware processStreamEvent
            ST-->>CC: Anthropic SSE event
        end
        TP->>ST: flush()
    else Non-streaming
        TP->>OB: POST /chat/completions
        OB-->>TP: JSON response
        TP->>MW: runResponseMiddleware
        TP-->>CC: 200 Anthropic JSON
    end

Loading

_{Reviews (7): Last reviewed commit: "refactor: simplify resolver fixes — remo..." | Re-trigger Greptile}

[dean0x]

Code Review Summary: 17 Blocking Issues Found

Created: 2026-04-23 | Branch: feat/api-translation-proxy → main

Critical Issues by Category

Architecture (3 HIGH - Stateful Middleware Concurrency)

• LoggingMiddleware, PromptCacheMiddleware, ToolNameMappingMiddleware all share instance state across concurrent requests, causing metrics corruption and tool name corruption under load. Fix: Create per-request middleware instances.
  • src/translation/middleware/logging.ts:23
  • src/translation/middleware/prompt-cache.ts:77
  • src/translation/middleware/tool-name-mapping.ts:33

Complexity (4 HIGH - Function Length + Cyclomatic Complexity)

• handleStreamingRequest: 161 lines, 5-level nesting (threshold: 50-200)
• handleNonStreamingRequest: 104 lines, 5-level nesting
• OpenAIStreamParser.processChunk: CC ~18
• buildOpenAIMessages: CC ~14

TypeScript (4 MEDIUM - Type Safety)

• Line 150: Unreachable dead code from double type checks
• Line 342: Non-null assertion without guard (could fail on malformed stream)
• Line 311: Missing exhaustive switch (won't catch new event types)
• Configuration.ts:251: translate typed as string instead of union

Security (2 MEDIUM - Input Validation)

• Line 221: URL reflected verbatim in error response (inject/confuse risk)
• mcp-adapter.ts:350: translate accepts any string, silent fail for invalid values

Performance (2 MEDIUM - Hot Path Inefficiencies)

• Line 53: Array spread on every stream event (hundreds of allocations)
• Line 557: Per-line res.write() creates 6+ syscalls per chunk

Testing (2 HIGH)

• middleware.ts:27: Zero direct unit tests for pipeline runner (ordering contracts untested)
• translation-proxy.ts:204: Five error paths untested (405, 404, 400, 502)

Regression (1 HIGH - Lifecycle)

• index.ts:75: ProxyManager shutdown missing in CLI mode

Consistency (1 MEDIUM)

• logging.ts:17: Import path inconsistent (../../ vs ../)

---

Issues by Confidence Level

≥80% Confidence (17 BLOCKING)
All items above meet ≥80% confidence threshold.

60-79% Confidence (Lower Priority)
See full review reports for architecture coupling, complexity in OpenAICodec, and testing gaps (concurrent requests, JSON fallback streaming, weak assertions).

---

Detailed Files

File	Issues	Severity
src/translation/middleware/logging.ts	2	HIGH (concurrency) + MEDIUM (import)
src/translation/middleware/prompt-cache.ts	1	HIGH (concurrency)
src/translation/middleware/tool-name-mapping.ts	1	HIGH (concurrency)
src/translation/proxy/translation-proxy.ts	4	HIGH×2 (functions) + MEDIUM×2 (security, perf)
src/translation/middleware/middleware.ts	2	HIGH (testing) + MEDIUM (perf)
src/translation/codecs/openai-codec.ts	3	MEDIUM (unreachable, assertion, complexity ~18)
src/translation/codecs/anthropic-codec.ts	1	MEDIUM (switch)
src/adapters/mcp-adapter.ts	1	MEDIUM (validation)
src/core/configuration.ts	1	MEDIUM (type safety)
src/index.ts	1	HIGH (regression)

Recommendation

Status: CHANGES_REQUESTED

The translation proxy feature demonstrates strong architectural fundamentals but has three critical concurrency bugs (stateful middleware shared across requests) that must be fixed before merge. Additionally, function decomposition (complexity), test coverage (middleware runner, error paths), and type safety improvements should be addressed.

Next Steps:

1. Fix stateful middleware (create per-request instances)
2. Decompose long functions and high-CC methods
3. Add missing unit tests
4. Add input validation for translate field
5. Rescan after fixes

---

Generated by Claude Code Code Review Agent
All 17 inline comments above at ≥80% confidence

[dean0x]

Code Review Summary

Consolidated findings from 8 reviewers (≥80% confidence). Filtering for blocking/high-severity issues:

🔴 Blocking Issues (Must Fix Before Merge)

1. TypeScript Type Error in Tests (Confidence: 95%)

   • Location: tests/unit/translation/middleware/middleware.test.ts:35
   • Issue: makeStreamEvent() constructs objects with a delta property, but ContentDeltaEvent in src/translation/ir.ts is defined as { type: 'content_delta'; index: number; text: string } — no delta property
   • Impact: 8 TypeScript errors; tests validate the wrong shape
   • Fix: Use the flat text property instead of nested delta.text

2. Stale JSDoc References (Confidence: 92%)

   • Location: src/core/configuration.ts:232
   • Issue: JSDoc says "kept in sync with SUPPORTED_TRANSLATE_TARGETS in proxy-manager.ts" but that constant was removed in this PR
   • Fix: Update comment to reference agents.ts:23 where it actually lives

3. Security: Raw Backend Error Forwarding (Confidence: 85%)

   • Location: src/translation/proxy/translation-proxy.ts:145-157
   • Issue: Backend error messages forwarded verbatim to client, could leak internal details (stack traces, hostnames, deployment names)
   • Fix: Return generic summary to client ('Backend returned error'), log full detail at debug level

4. Security: Unbounded Error Buffer (Confidence: 82%)

   • Location: src/translation/proxy/translation-proxy.ts:450-451, 502-503
   • Issue: Error response bodies have no size cap, malicious backend could cause memory exhaustion
   • Fix: Add MAX_ERR_BYTES guard (64KB) on error body accumulation, matching pattern for inbound request bodies

🟡 High-Severity Issues (Strong Recommendation to Fix)

5. Dead Code: Unused Return Value (Confidence: 85%)

   • Location: src/translation/proxy/translation-proxy.ts:467, 532
   • Issue: processNonStreamingResponse() returns boolean but return value is ignored at all call sites
   • Fix: Change return type to void to match actual usage

6. Code Duplication: Middleware Loop (Confidence: 82%)

   • Location: src/translation/proxy/stream-translator.ts:100-109
   • Issue: Reimplements the same loop as runStreamEventMiddleware() with no shared source of truth
   • Fix: Either parameterize runStreamEventMiddleware to accept pre-reversed array, or document that production uses StreamTranslator version

7. Complex Nesting (76-line method, 5 levels deep) (Confidence: 85%)

   • Location: src/translation/proxy/translation-proxy.ts:417-492
   • Issue: handleNonStreamingRequest still has deep nesting despite prior refactoring
   • Fix: Extract callback into handleBackendNonStreamingResponse() method to flatten nesting

📋 Summary by Category

Severity	Count	Recommendation
Blocking (Type/Docs/Security)	4	Address before merge
High (Dead code/Duplication/Complexity)	3	Strongly recommended
Lower Confidence (60-79%)	8	Summary comment recommendations

Review Process Notes

• Deduplicated across 8 reviewers: Architecture, Security, Testing, TypeScript, Consistency, Regression, Complexity, Performance
• Inline comments created for: Configuration JSDoc, middleware test types, error forwarding, error buffering, return value, middleware duplication, nesting complexity
• Pre-existing issues identified: 2 flaky CI tests (worker-pool-management.test.ts:157, network-failures.test.ts:312) noted in memory but not blocking this PR

---

Claude Code Code Review Agent • Confidence-weighted filtering applied

[dean0x]

CRITICAL: Database registration throws instead of returning err()

Line 274: The catch block re-throws non-NODE_MODULE_VERSION errors without wrapping in the Result return type. The bootstrap function returns Promise<Result<Container>> — it should never throw.

Fix: Wrap the re-throw in an err() return:

} catch (error: unknown) {
  const msg = error instanceof Error ? error.message : String(error);
  if (msg.includes("NODE_MODULE_VERSION")) {
    return err(new AutobeatError(...));
  }
  return err(
    new AutobeatError(
      ErrorCode.SYSTEM_ERROR,
      `Failed to initialize database: ${msg}`,
    ),
  );
}

[dean0x]

HIGH: Database registration pattern deviation needs DECISION comment

Lines 256-275: Registration changed from lazy registerSingleton to eager registerValue. Every other service uses registerSingleton. Document the intentional deviation with a clear comment explaining why database is eagerly instantiated (to catch native module ABI mismatches early).

[dean0x]

HIGH: URL construction bypasses URL API — src/translation/proxy/translation-proxy.ts:389

String concatenation new URL(targetBaseUrl.replace(/\/$/, "") + "/chat/completions") is fragile for base URLs with paths or query params. Use the URL API correctly:

const base = new URL(this.config.targetBaseUrl);
base.pathname = base.pathname.replace(/\/?$/, "") + "/chat/completions";

[dean0x]

HIGH: Non-streaming response accumulation unbounded — src/translation/proxy/translation-proxy.ts:484-488, 584-589

Success path accumulates chunks with no size cap, unlike error path (MAX_ERR_BYTES) and inbound limit (MAX_BODY_BYTES). A malicious backend could send very large responses without bounds.

Fix: Add size cap on success paths matching inbound limit:

const chunks: Buffer[] = [];
let totalBytes = 0;
backendRes.on("data", (chunk: Buffer) => {
  totalBytes += chunk.length;
  if (totalBytes <= MAX_BODY_BYTES) chunks.push(chunk);
});
backendRes.on("end", () => {
  if (totalBytes > MAX_BODY_BYTES) {
    sendError(res, 502, "api_error", "Backend response too large");
    return;
  }
  // ... process response
});

[dean0x]

HIGH: serializeContentBlock missing exhaustive never check — src/translation/codecs/anthropic-codec.ts:178

The switch statement uses a silent fallback return { type: "text", text: "" } instead of exhaustive never checking. If a new CanonicalContent variant (e.g., audio) is added, this function will not be flagged by the compiler. The same file uses exhaustive checking correctly at line 324.

Fix: Add exhaustive check:

case "image":
case "document":
case "json":
case "tool_result":
  return { type: "text", text: "" };
default: {
  const _exhaustive: never = content;
  return { type: "text", text: "" };
}

[dean0x]

MEDIUM: TLS bypass suggestion in error message — src/utils/url-probe.ts:146

Confidence: 90%. The error suggests NODE_TLS_REJECT_UNAUTHORIZED=0 to work around TLS failures. This is dangerous (OWASP A02) and normalizes disabling certificate verification for the entire Node.js process, exposing all HTTPS connections (including API proxy traffic with API keys) to MITM.

Fix: Replace with safer recommendation:

return `TLS/SSL error connecting to ${urlStr}: ${error.message}. Verify the servers TLS certificate is valid, or configure a custom CA bundle via NODE_EXTRA_CA_CERTS.`;

[dean0x]

MEDIUM: No protocol scheme restriction on probeUrl — src/utils/url-probe.ts:212-221

Confidence: 82%. The function validates URL parsing but allows any scheme (file://, ftp://, etc.). While the URL eventually goes to http.request which would fail, defense-in-depth would reject non-HTTP schemes at the probe entry point.

Fix: Add scheme validation:

if (parsedUrl.protocol !== "https:" && parsedUrl.protocol !== "http:") {
  return err(new Error(`Unsupported protocol "${parsedUrl.protocol}" — only http: and https: are supported`));
}

[dean0x]

MEDIUM: rawError cast bypasses unknown narrowing — src/utils/url-probe.ts:101

Confidence: 82%. Line 101 casts rawError (typed unknown) directly to NodeJS.ErrnoException without instanceof guard. The pattern is used correctly elsewhere (bootstrap.ts:262).

Fix: Narrow properly before accessing ErrnoException fields:

const error = rawError instanceof Error
  ? (rawError as NodeJS.ErrnoException)
  : Object.assign(new Error(String(rawError)), { code: undefined }) as NodeJS.ErrnoException;

[dean0x]

HIGH: handleConfigureAgent exceeds complexity threshold — src/adapters/mcp-adapter.ts:3326

Confidence: 88%. The method spans 220+ lines with 3 case branches and cyclomatic complexity ~15. The set branch alone is 140 lines with 6+ decision points.

Fix: Extract each switch case into dedicated private methods:

private async handleConfigureAgent(args: unknown): Promise<MCPToolResponse> {
  const { agent, action, ...fields } = ConfigureAgentSchema.safeParse(args).data;
  switch (action) {
    case "check": return this.handleConfigureAgentCheck(agent);
    case "set": return this.handleConfigureAgentSet(agent, fields);
    case "reset": return this.handleConfigureAgentReset(agent);
  }
}

This keeps each method under 30 lines and improves maintainability.

[dean0x]

HIGH: probeUrl adds 5s latency to ConfigureAgent check — src/adapters/mcp-adapter.ts:3357-3364

Confidence: 82%. The check action now awaits a 5s timeout probe unconditionally. Users calling ConfigureAgent check frequently for status will experience 5s stalls if the backend is unreachable.

Fix: Make probe optional via tool schema parameter, or reduce timeout to 2-3s for check action, or make probe fire-and-forget. The set action probe is more acceptable since it only fires on config changes.

[dean0x]

MEDIUM: Inconsistent response typing in ConfigureAgent — src/adapters/mcp-adapter.ts:3521-3536

Confidence: 82%. The check action defines a typed CheckPayload interface (line 3366), but the set action removed the equivalent SetPayload and now inlines the response object without type annotation. This creates asymmetry within the same handler.

Fix: Either remove CheckPayload too (both inline) or keep both typed. Simpler: inline CheckPayload also for consistency.

[dean0x]

MEDIUM: argumentsAccumulator string concat causes O(n²) behavior — src/translation/codecs/openai-codec.ts:353,381

Confidence: 80%. Tool call arguments accumulate via += string concatenation. JavaScript strings are immutable, so each concat allocates a new string (n² copies for large payloads).

Fix: Use array accumulator and join at the end:

interface ActiveToolCall {
  id: string;
  name: string;
  argumentsChunks: string[];  // was argumentsAccumulator
  started: boolean;
}
// On delta: tc.argumentsChunks.push(tcArgs);
// On stop: arguments: tc.argumentsChunks.join("")

[dean0x]

MEDIUM: probeUrl silently swallows deep-probe network errors — src/utils/url-probe.ts:245-247

Confidence: 82%. When the deep probe (GET /models) fails with a network error but the base HEAD probe succeeded, the error is silently discarded. This loses diagnostic information about authentication failures.

Fix: Include a warning in the returned result:

if ("error" in deepResult) {
  const baseMessage = messageForStatus(statusCode, headers, parsedUrl, false);
  return ok({
    reachable: true,
    statusCode,
    message: `${baseMessage}. Note: API key validation failed (${deepResult.error.message})`,
    severity: "warning",
    durationMs,
  });
}

[dean0x]

MEDIUM: messageForError uses 6 if-chains instead of lookup — src/utils/url-probe.ts:121-151

Confidence: 82%. The function has cyclomatic complexity ~8 with a long chain of if/else-if blocks. The TLS error check alone is a 7-operand disjunction (lines 137-144). Each new error code extends the chain linearly.

Fix: Extract TLS codes to a Set and consider a dispatch table:

const TLS_ERROR_CODES = new Set([
  "CERT_HAS_EXPIRED", "CERT_INVALID",
  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
  "SELF_SIGNED_CERT_IN_CHAIN", "DEPTH_ZERO_SELF_SIGNED_CERT",
]);

function isTlsError(code: string): boolean {
  return TLS_ERROR_CODES.has(code) || code.startsWith("ERR_TLS") || code.startsWith("ERR_SSL");
}

[dean0x]

HIGH: ThinkingDeltaEvent type change is breaking — src/translation/ir.ts:218-222

Confidence: 90%. The ThinkingDeltaEvent gained a required index field, breaking any external consumer constructing or pattern-matching on this type.

Note: If src/translation/ir.ts is internal-only (appears to be — not re-exported from src/utils/index.ts), this is acceptable and severity drops to informational. Please confirm the IR types are not part of public API surface.

If external consumers exist, this breaking change needs a CHANGELOG note and migration guide.

[dean0x]

Review Summary: PR #152

Overall Status: Changes Requested (15 high-confidence issues found)

Issue Breakdown by Severity

• CRITICAL: 1 (database registration throw)
• HIGH: 7 (URL API fragility, unbounded response accumulation, exhaustive checking, complexity, probe latency, type regression)
• MEDIUM: 7 (security, type safety, performance, consistency, diagnostics)

Lower-Confidence Suggestions (60-79%, for consideration)

1. Dynamic vs static import inconsistency (84%) — agents.ts uses dynamic import for probeUrl, but mcp-adapter.ts uses static. Document or standardize.
2. SSRF via redirect following (65%) — Current code is safe but future changes could expose internal services.
3. Probe timeout handling in tests (70%) — Missing edge case: what if probeUrl exceeds 5000ms timeout?
4. Double loadAgentConfig call (65%) — When translate is set, config is loaded twice in agents.ts.
5. Version generation error handling (60%) — generate-version.mjs lacks error handling for readFileSync failures.
6. Timing side-channels (60%) — durationMs in probe responses could help fingerprint infrastructure (low risk for local tool).

Consolidated Findings

Multiple reviewers independently flagged the same issues, confirming high confidence:

• Database registration inconsistency (Architecture, Consistency, TypeScript)
• URL construction fragility (Architecture, Performance)
• Unbounded response accumulation (Performance, Security)
• handleConfigureAgent complexity (Complexity reviewer — 220 lines, CC ~15)
• TLS bypass suggestion (Security with OWASP reference)

Next Steps

1. Fix CRITICAL issue: database registration throw in catch block
2. Address HIGH issues in order (7 items)
3. Consider MEDIUM issues (7 items)
4. Optional: review lower-confidence suggestions

---

Reviewed by 9 independent agents (Security, Architecture, Performance, Complexity, Consistency, Regression, Testing, TypeScript, Dependencies)
Claude Code — feat/api-translation-proxy