Skip to content

feat(overflow): disclose the relay on MCP; scope an aggregator's own 4xx to the request - #414

Merged
stonexer merged 2 commits into
mainfrom
fix/overflow-disclosure
Sep 9, 2026
Merged

stonexer merged 2 commits into
mainfrom
fix/overflow-disclosure

Conversation

@stonexer

@stonexer stonexer commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Split out of #400 because it changes capacity policy for every overflowed call, not one provider's billing rule. Two commits so the policy half can be reviewed and reverted on its own.

1. Disclose the relay on the MCP surface (low risk)

When treg's own account for a provider is marked out, a platform-eligible endpoint may be served through the overflow relay at the aggregator's real price with 0% markup. That is the documented contract (AGENTS.md non-negotiable 4, money.md "Overflow money", llms.txt, skill.md, treg org overflow off), and /call/ says so in X-Treg-Served-Via. The MCP call tool dropped that header and catalog_get showed only the direct price, so an agent on apollo.people.search (catalog: free) saw cost_usd 0.002 with no explanation. Ledger for 2026-09-08: 100,113 Apollo searches, 24,960 through the relay, 8,810 billed $0.002. Six feedback reports from one org.

  • MCP call result carries served_via and a one-line hint when it names an overflow aggregator (shared _call_impl, so both /mcp/ and /mcp/v2/).
  • catalog_get and GET /catalog/{id} expose overflow_price_usd, overflow_price_unit, overflow_via for endpoints the deployment can relay, and the run hint says a "free" endpoint may bill that price.
  • llms.txt, skill.md and the five installed SKILL.md copies say the same thing.

2. Scope an aggregator's own 4xx to the request (policy change)

One Orthogonal validation 400 with no vendor data was classified malformed, which is aggregator-side and struck overflow:orthogonal for 15 minutes for every org; with the direct tier skipped, every call in that window failed as provider_capacity_unavailable. A bare 4xx from the aggregator (400/422 validation, 404 for a slug it no longer lists) is now contract: request-scoped, no vendor call, nothing charged, no strike, and on the skip-direct ladder the caller gets treg's typed 503 naming the refusal rather than the aggregator envelope. malformed is reserved for non-JSON bodies, 5xx and transport errors. 402 and 401/403 keep their aggregator-side meaning.

Trade-off to weigh: repeated bad requests now reach Orthogonal every time instead of being short-circuited for 15 minutes. Also corrects money.md's stale $20/day aggregator budget (render.yaml sets $500).

Not changed: when a free endpoint is diverted to overflow. Today a zero-cost endpoint is skipped on the same exhausted signal as a paid one, including a credit-balance reading from the capacity sweep; whether a $0 direct call should ever be diverted to a paid relay is a product decision left open.

Verification

  • uv run --with pytest-xdist pytest -n auto: 3203 passed, 5 skipped. test_alembic_head_has_no_model_drift passes against a private TREG_TEST_DB_URL; the shared sqlite files under $TMPDIR/treg-tests are contaminated on this machine by other checkouts' runs.
  • lint-imports: 14 contracts kept. drift.sh origin/main..HEAD: every changed source maps to a fragment updated in these commits (the mixed docs, money.md and proxy-model.md, sit in the second commit).

A free endpoint served through the overflow relay bills the relay's price
(apollo.people.search: 8,810 calls at $0.002 on 2026-09-08) and nothing on
the MCP surface said so. The call result now carries served_via and a hint,
and catalog_get shows overflow_price_usd up front.
…f striking the aggregator

One Orthogonal validation 400 read as malformed took overflow:orthogonal
offline for every org for 15 minutes on 2026-09-08. A bare 4xx with no vendor
data is the aggregator's per-request refusal: no vendor call, no charge, no
strike; malformed is reserved for non-JSON bodies, 5xx and transport errors.
Also corrects the stale $20/day aggregator budget in money.md.
@github-actions github-actions Bot added area:dashboard The web dashboard / landing / tutorials area:docs Documentation & design fragments labels Sep 9, 2026
@stonexer
stonexer merged commit 8f1a71b into main Sep 9, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:dashboard The web dashboard / landing / tutorials area:docs Documentation & design fragments

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant