mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
## Description Adds a gateway turn contract to `POST /v1/compress`, allowing an API gateway to submit a complete provider request and later report the provider response. Requests without a top-level `gateway` object remain unchanged. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [x] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Adds the request half to `/v1/compress` and the response half at `/v1/compress/response`, including bounded pending turns, idempotent rounds, usage relay, and redrive obligations. - Adds a reusable six-stage compress-turn extension seam and turn-hook priority/provider-header support. - Keeps native tool-schema deferral in the licensed extension while sharing protocol-shape helpers with core. - Accepts Anthropic, OpenAI chat, OpenAI Responses, and Kong-shaped usage payloads. - Documents the gateway contract in `docs/content/docs/proxy.mdx` and `wiki/proxy.md`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text tests/gateway + gateway unit + turn-hook seam + test_issue_746_tool_search: 358 passed ruff 0.16.3 lint/format and mypy on touched modules: clean Kong 3.9 Docker e2e (HEADROOM_KONG_E2E=1): 4 passed ``` ## Real Behavior Proof - Environment: Kong 3.9 Docker e2e and real-provider Claude Code through Kong on SWE-bench-mini. - Exact command / steps: `HEADROOM_KONG_E2E=1` gateway e2e; real-provider traffic through the gateway contract with usage relay and licensed native deferral. - Observed result: four Kong e2e tests passed; prefix cache remained intact with zero busts; relayed usage matched Anthropic token-for-token; licensed tool-search deferral reduced cache-read tokens per turn by 27–30%. - Not tested: production rollout at scale. ## Runtime Rollout Safety - Rollout-managed feature(s): gateway contract and in-process pending-turn registry. - Minimum rollout channel: controlled gateway deployment before broader enablement. - Stable/default behavior changed: only requests containing a top-level `gateway` object enter the new contract; ordinary `/v1/compress` bodies are unchanged. - Kill switch / disable path: set `HEADROOM_GATEWAY_CONTRACT=0`. - Unsafe override required: no. - Qualification impact: gateway callers must redeem advertised `redrive` and `relay_usage` obligations. - Rollback path: disable the contract with `HEADROOM_GATEWAY_CONTRACT=0` or revert the feature commit. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) Not applicable; this is an API contract change. ## Additional Notes Pending turns are process-local and bounded by `HEADROOM_GATEWAY_TURN_TTL_SECONDS`, `HEADROOM_GATEWAY_MAX_PENDING_TURNS`, and `HEADROOM_GATEWAY_MAX_REDRIVES`. Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
111 lines
3.8 KiB
Python
111 lines
3.8 KiB
Python
"""A stream-safe, fold-only turn hook: truncates long tool results deterministically.
|
|
|
|
``stream_safe = True`` because ``on_request`` needs no later re-drive, so the
|
|
proxy runs it on streaming turns and the gateway request half runs it even when
|
|
``can_redrive`` is false.
|
|
|
|
Idempotent by construction: a result that already carries the fold marker is
|
|
left alone, so in session mode (where the hook's output is what the next turn's
|
|
prefix replays) turn N+1 reproduces turn N's bytes exactly. The hook rebinds
|
|
``ctx.messages`` to a new list with fresh dicts for the messages it changed and
|
|
never mutates the caller's objects.
|
|
|
|
Handles the chat-completions ``role: "tool"`` string content and Anthropic
|
|
``tool_result`` blocks (string content or a list of text blocks).
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass, field
|
|
from typing import Any
|
|
|
|
from headroom.proxy.turn_hooks import register_turn_hook
|
|
|
|
FOLD_MARKER = " ...[folded by test_fold_only]"
|
|
|
|
|
|
def fold_text(text: str, max_chars: int) -> str:
|
|
if len(text) <= max_chars or text.endswith(FOLD_MARKER):
|
|
return text
|
|
return text[:max_chars] + FOLD_MARKER
|
|
|
|
|
|
@dataclass
|
|
class FoldOnlyHook:
|
|
name: str = "test_fold_only"
|
|
savings_source: str = "test_fold_only"
|
|
stream_safe: bool = True
|
|
max_chars: int = 200
|
|
request_calls: int = 0
|
|
folded: int = 0
|
|
seen_messages: list[list[dict[str, Any]]] = field(default_factory=list)
|
|
|
|
def _fold_block(self, block: Any) -> Any:
|
|
if not isinstance(block, dict) or block.get("type") != "tool_result":
|
|
return block
|
|
content = block.get("content")
|
|
if isinstance(content, str):
|
|
new = fold_text(content, self.max_chars)
|
|
if new is not content:
|
|
self.folded += 1
|
|
return {**block, "content": new}
|
|
return block
|
|
if isinstance(content, list):
|
|
changed = False
|
|
parts = []
|
|
for part in content:
|
|
if (
|
|
isinstance(part, dict)
|
|
and part.get("type") == "text"
|
|
and isinstance(part.get("text"), str)
|
|
):
|
|
new = fold_text(part["text"], self.max_chars)
|
|
if new is not part["text"]:
|
|
changed = True
|
|
part = {**part, "text": new}
|
|
parts.append(part)
|
|
if changed:
|
|
self.folded += 1
|
|
return {**block, "content": parts}
|
|
return block
|
|
|
|
def on_request(self, ctx: Any) -> None:
|
|
self.request_calls += 1
|
|
messages = ctx.messages
|
|
if not isinstance(messages, list):
|
|
return
|
|
self.seen_messages.append(messages)
|
|
out: list[Any] = []
|
|
changed = False
|
|
for m in messages:
|
|
if not isinstance(m, dict):
|
|
out.append(m)
|
|
continue
|
|
if m.get("role") == "tool" and isinstance(m.get("content"), str):
|
|
new = fold_text(m["content"], self.max_chars)
|
|
if new is not m["content"]:
|
|
self.folded += 1
|
|
changed = True
|
|
out.append({**m, "content": new})
|
|
continue
|
|
if m.get("role") == "user" and isinstance(m.get("content"), list):
|
|
blocks = [self._fold_block(b) for b in m["content"]]
|
|
if any(a is not b for a, b in zip(blocks, m["content"])):
|
|
changed = True
|
|
out.append({**m, "content": blocks})
|
|
continue
|
|
out.append(m)
|
|
if changed:
|
|
ctx.messages = out
|
|
|
|
|
|
def register(**kwargs: Any) -> FoldOnlyHook:
|
|
hook = FoldOnlyHook(**kwargs)
|
|
register_turn_hook(hook)
|
|
return hook
|
|
|
|
|
|
def install(app: Any, config: Any) -> None:
|
|
"""``headroom.proxy_extension`` entry-point shape."""
|
|
register()
|