feat(gateway): W3 scaffold for /v1/llm_turn cloud-brain endpoint

[LightDriverCS]

Summary

Phase 1B W3 of BenchAGI ADR-0002 — Cloud Brain via Relay. Adds the /v1/llm_turn endpoint that the BenchAGI cloud orchestrator (W2 — BenchAGI #878) dispatches LlmTurnDirectives to via the relay.

Persona-off-disk invariant: system_prompt arrives inline in the request body — this endpoint MUST NOT write the persona to disk. The legacy /v1/chat path reads ${workspace}/SOUL.md; this endpoint deliberately does not.

Scope (this PR — scaffold)

• New file src/gateway/llm-turn-http.ts (~370 lines)
  • Request/response types (camelCase TS, snake_case wire format)
  • validateLlmTurnRequest pure function with size caps + required-field enforcement
  • handleLlmTurnHttpRequest HTTP handler (returns Promise<boolean> matching the existing dispatch contract)
  • isLlmTurnPath matcher
• Route wiring in src/gateway/server-http.ts (3 small edits)
• 14 unit tests in src/gateway/llm-turn-http.validate.test.ts
• Out-of-scope lint fix in extensions/claude-code-bridge/serve.mjs:35-39 (oxlint curly-rule on a pre-existing single-line return — repo-wide pre-commit hook blocked this commit otherwise)

NOT YET in scope (CALL_ANTHROPIC_TODO — follow-up PR)

The handler validates the request body and returns 501 llm_turn_not_implemented. The follow-up PR will:

1. Resolve agent's local Anthropic auth profile via existing agents/auth-profiles machinery
2. Translate request → SDK params (messages, system_prompt, tools, thinking_level)
3. Apply existing anthropic-payload-policy.ts cache-control machinery
4. Optional write-ahead idempotency record keyed by idempotency_key
5. Call Anthropic SDK
6. Translate response (camelCase → snake_case wire format)
7. Return 200

This scaffold lets the BenchAGI relay claim path land + exercise the route registration end-to-end without burning customer tokens — when the relay POSTs to /v1/llm_turn, it gets a clean 501 and writes error.code: 'llm_turn_not_implemented' to the directive doc, which the cloud orchestrator surfaces to webchat. Once the Anthropic call lands, the same flow returns a real response.

Wire format

Request:

{
  "agent_id": "aurelius",
  "messages": [...],
  "system_prompt": "...",
  "tools": [...],
  "model": "claude-opus-4-7",
  "thinking_level": "high",
  "max_tokens": 8192,
  "cache_control": { "system": "ephemeral" },
  "idempotency_key": "..."
}

Response (when Anthropic call lands):

{
  "content": [...],
  "stop_reason": "end_turn" | "tool_use" | ...,
  "model": "claude-opus-4-7-20260301",
  "usage": { "input_tokens": ..., "output_tokens": ... },
  "used_auth_profile": "anthropic-default"
}

Test plan

• 14 unit tests on validateLlmTurnRequest (pnpm test src/gateway/llm-turn-http.validate.test.ts)
• tsc --noEmit clean (incl. tsgo pre-commit check)
• oxlint clean across the repo
• Codex Stage B Gate W3 (running)
• Integration test (full HTTP path with auth + rate limit) — DEFERRED to the Anthropic-call follow-up PR
• Smoke test against W2's dispatch path (will exercise route end-to-end with 501 response)

Companion PRs in BenchAGI

• #872 — W1 schema (tier + runtime + installBinding)
• #874 — W4 relayDirectives schema (LlmTurn + Tool + Reauth directive types)
• #878 — W2 cloud orchestrator dispatch (writes the directives this endpoint will consume)

🤖 Generated with Claude Code