Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(toin): make diagnostic pattern identifiers addressable (#4021)

Mansurshakh Japarovdef6d41185d3
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 404ecbd81..ccedd24a2 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -5935,7 +5935,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
limit: Maximum number of patterns to return (default 20)
Response includes for each pattern:
- - hash: Truncated tool signature hash (12 chars)
+ - hash: Full aggregation key identifying one scoped tool pattern
- compressions: Total compression events
- retrievals: Total retrieval events
- retrieval_rate: Percentage of compressions that triggered retrieval
@@ -5959,7 +5959,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
patterns_list.append(
{
- "hash": sig_hash[:12],
+ "hash": sig_hash,
"compressions": total_compressions,
"retrievals": total_retrievals,
"retrieval_rate": f"{retrieval_rate:.1%}",
@@ -5979,36 +5979,41 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
return patterns_list[:limit]
- @app.get("/v1/toin/pattern/{hash_prefix}", dependencies=[Depends(_require_loopback)])
+ @app.get("/v1/toin/pattern/{hash_prefix:path}", dependencies=[Depends(_require_loopback)])
async def toin_pattern_detail(hash_prefix: str):
- """Get detailed TOIN pattern info by hash prefix.
+ """Get detailed TOIN pattern info by the listed identifier or a unique prefix.
- Searches for a pattern where the tool signature hash starts with
- the provided prefix. Returns full pattern details if found.
+ Pass the ``hash`` returned by ``/v1/toin/patterns`` for an exact
+ lookup. A shorter aggregation-key prefix is accepted only when it
+ identifies one pattern; ambiguous prefixes return 409.
- Path params:
- hash_prefix: Beginning of the tool signature hash (min 4 chars recommended)
-
- Response: Full pattern.to_dict() with all learned statistics and recommendations.
+ Response: Learned statistics without query text or field semantics.
"""
toin = get_toin()
exported = toin.export_patterns()
patterns_data = exported.get("patterns", {})
- # Search for pattern with matching hash prefix
- for sig_hash, pattern_dict in patterns_data.items():
- if sig_hash.startswith(hash_prefix):
- # Keep this response aligned with /v1/toin/patterns while
- # excluding query text, field semantics, and other internal
- # learning state from the detail endpoint.
- return {
- "compressions": pattern_dict.get("total_compressions", 0),
- "retrievals": pattern_dict.get("total_retrievals", 0),
- "retrieval_rate": pattern_dict.get("retrieval_rate", 0.0),
- "confidence": pattern_dict.get("confidence", 0.0),
- "skip_recommended": pattern_dict.get("skip_compression_recommended", False),
- "optimal_max_items": pattern_dict.get("optimal_max_items", 20),
- }
+ pattern_dict = patterns_data.get(hash_prefix)
+ if pattern_dict is None:
+ matches = (
+ pattern for key, pattern in patterns_data.items() if key.startswith(hash_prefix)
+ )
+ pattern_dict = next(matches, None)
+ if next(matches, None) is not None:
+ raise HTTPException(
+ status_code=409,
+ detail="Ambiguous TOIN pattern prefix; use a full hash from /v1/toin/patterns",
+ )
+ if pattern_dict is not None:
+ # Keep query text, field semantics, and internal learning state private.
+ return {
+ "compressions": pattern_dict.get("total_compressions", 0),
+ "retrievals": pattern_dict.get("total_retrievals", 0),
+ "retrieval_rate": pattern_dict.get("retrieval_rate", 0.0),
+ "confidence": pattern_dict.get("confidence", 0.0),
+ "skip_recommended": pattern_dict.get("skip_compression_recommended", False),
+ "optimal_max_items": pattern_dict.get("optimal_max_items", 20),
+ }
raise HTTPException(
status_code=404, detail=f"No TOIN pattern found with hash starting with: {hash_prefix}"
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index b4200bcaa..0d5eba03d 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -279,8 +279,16 @@ const hints = await client.feedback.getHints('list_servers');
// TOIN (Tool Output Intelligence Network)
const toinStats = await client.toin.getStats();
const patterns = await client.toin.getPatterns(20);
+const pattern = patterns[0] && await client.toin.getPattern(patterns[0].hash);
```
+Each `hash` is the complete scoped aggregation key, including tenant, auth mode,
+model family, and tool signature. Pass it back unchanged for an exact lookup;
+the client URL-encodes it. Shorter aggregation-key prefixes are accepted only
+when they identify one pattern; ambiguous prefixes return HTTP 409 rather than
+an arbitrary pattern.
+
+
## Configuration Types
Full TypeScript interfaces for every Python config dataclass.
diff --git a/tests/test_proxy_loopback_gating.py b/tests/test_proxy_loopback_gating.py
index 1e76430e1..382baa449 100644
--- a/tests/test_proxy_loopback_gating.py
+++ b/tests/test_proxy_loopback_gating.py
@@ -112,7 +112,9 @@ def test_toin_pattern_detail_whitelists_learned_payload(monkeypatch: pytest.Monk
}
monkeypatch.setattr("headroom.proxy.server.get_toin", lambda: FakeTOIN())
- response = _loopback_client().get("/v1/toin/pattern/unknown")
+ client = _loopback_client()
+ identifier = client.get("/v1/toin/patterns").json()[0]["hash"]
+ response = client.get(f"/v1/toin/pattern/{identifier}")
assert response.status_code == 200
assert response.json() == {
@@ -125,6 +127,63 @@ def test_toin_pattern_detail_whitelists_learned_payload(monkeypatch: pytest.Monk
}
+def scoped_toin(monkeypatch: pytest.MonkeyPatch, tmp_path):
+ from headroom.telemetry.toin import TOINConfig, ToolIntelligenceNetwork
+
+ toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(tmp_path / "toin.json")))
+ patterns = {
+ "global|unknown|unknown|abc123": 8,
+ "global|unknown|unknown|abc456": 16,
+ "global|payg|claude|abc123": 24,
+ "other-tenant|unknown|unknown|abc123": 32,
+ "tenant/alpha?scope=one#fragment|unknown|unknown|abc123": 40,
+ }
+ toin.import_patterns(
+ {
+ "instance_id": "scoped-pattern-regression",
+ "patterns": {
+ key: {
+ "tool_signature_hash": key.rsplit("|", 1)[-1],
+ "sample_size": count,
+ "total_compressions": count,
+ "total_retrievals": 0,
+ }
+ for key, count in patterns.items()
+ },
+ }
+ )
+ monkeypatch.setattr("headroom.proxy.server.get_toin", lambda: toin)
+ return patterns
+
+
+def test_listed_toin_identifiers_address_their_own_scoped_pattern(scoped_toin) -> None:
+ from urllib.parse import quote
+
+ client = _loopback_client()
+ listed = client.get("/v1/toin/patterns").json()
+ assert {item["hash"] for item in listed} == set(scoped_toin)
+ for item in listed:
+ response = client.get(f"/v1/toin/pattern/{quote(item['hash'], safe='')}")
+ assert response.status_code == 200
+ assert response.json()["compressions"] == item["compressions"]
+
+
+ ("prefix", "status", "count"),
+ [
+ ("global|unknown|unknown|abc", 409, None),
+ ("global|unknown|unknown|abc1", 200, 8),
+ ("missing-pattern", 404, None),
+ ],
+)
+def test_toin_prefix_lookup_is_unambiguous(scoped_toin, prefix, status, count) -> None:
+ response = _loopback_client().get(f"/v1/toin/pattern/{prefix}")
+ assert response.status_code == status
+ if count is not None:
+ assert response.json()["compressions"] == count
+
+
# Mutating routes reachable from loopback. `require_loopback` cannot stop a
# remote page from POSTing to a known 127.0.0.1 URL: a "simple" cross-origin
# request (Content-Type: text/plain carrying JSON) skips preflight, and the