Skip to content

docs(protocol): correct depth-refusal contract to match live router behavior#65

Merged
drewstone merged 1 commit into
mainfrom
fix/protocol-spec-accuracy
May 26, 2026
Merged

docs(protocol): correct depth-refusal contract to match live router behavior#65
drewstone merged 1 commit into
mainfrom
fix/protocol-spec-accuracy

Conversation

@drewstone
Copy link
Copy Markdown
Contributor

Summary

Doc-only correction to the protocol spec that shipped in #64. Investigation of the proposed follow-ups (`agent-gateway` middleware, `cli-bridge` propagation) surfaced two factual inaccuracies I'd written into the spec from assumption rather than measurement.

What I found while investigating the follow-ups

Layer Already implemented? Evidence
`tangle-router` depth enforcement Yes (live) `app/api/chat/route.ts:1390-1410` — reads inbound `x-tangle-forwarded-depth`, refuses with HTTP 429 + `bridge_depth_exceeded` at `CLI_BRIDGE_MAX_DEPTH` (default 4), emits incremented outbound depth
`cli-bridge` authorization forwarding Yes (live) `src/routes/chat-completions.ts:190+212` — reads `x-tangle-forwarded-authorization`, threads to sandbox backend as `forwardedAuthorization` metadata
`cli-bridge` depth enforcement No, but not needed Always sits downstream of router for sandbox dispatches → bounded transitively
`agent-gateway` middleware No, deferred No production consumer of the forwarded-header path through agent-gateway today; first real consumer drives the work

Doc bugs this fixes

  1. Refusal status code: spec said `413 Payload Too Large`; live router uses `429 Too Many Requests` with body code `bridge_depth_exceeded`. Implementations targeting the spec would have returned the wrong code.
  2. Spec read as fully shipped end-to-end. Added an Implementation status table making per-layer reality explicit so future implementers don't mistake the contract for the live state.

Decision not to build the originally-named follow-ups (yet)

After reading the actual code:

  • `cli-bridge` depth handling is redundant. Depth is enforced upstream at `tangle-router` for the only recursion path that exists today (`bridge/sandbox/*` dispatches). Adding a duplicate check in cli-bridge gains nothing measurable.
  • `agent-gateway` middleware has no current consumer. agent-gateway is in production at gtm-agent + agent-builder, but no caller emits `X-Tangle-Forwarded-*` headers to them today. Building enforcement before a consumer = engineering for a hypothetical.

Both are tracked on the ops board for when a real consumer materializes (a third-party agent-gateway deployment, or an agent-to-agent call that bypasses tangle-router).

What's NOT in this PR

  • No code changes to `agent-runtime` (headers builders are already correct — they emit; refusal is the gateway's job).
  • No changes to `cli-bridge` or `tangle-router`.
  • No new middleware in `agent-gateway`.

This is a 17-line doc fix.

Test plan

  • `pnpm typecheck` — clean
  • `pnpm test` — 354/354
  • biome check — clean (one pre-existing warning in `tests/mcp/in-process-executor.test.ts:116` from main, untouched)

…ehavior

Investigation surfaced two doc inaccuracies the freshly-merged spec doc
inherited from my own assumption rather than measurement:

  1. Refusal status code is 429 + body code 'bridge_depth_exceeded' (live
     in tangle-router app/api/chat/route.ts:1390-1410), not the 413 the
     spec claimed. Updated header table + invariant #5 accordingly.

  2. The spec read as fully shipped end-to-end. Added an Implementation
     status table making the per-layer reality explicit:
       - agent-runtime emits all six headers (this is the work that
         shipped in #64).
       - tangle-router enforces depth + forwards auth (already live).
       - cli-bridge forwards authorization to sandbox backends (already
         live); does not enforce depth locally — inherits via router.
       - agent-gateway middleware: NOT YET. Deferred to a real consumer.

No code changes. The agent-runtime headers builders and emitters are
already correct (they emit the header; refusal is the gateway's job).
The doc was the only thing out of step.
Copy link
Copy Markdown
Contributor

@tangletools tangletools left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE. Doc-only fix, 17 lines, no code changes. Verified the three factual claims against source:

  • tangle-router/app/api/chat/route.ts:1390-1410 does refuse with HTTP 429 + bridge_depth_exceeded. ✓
  • cli-bridge/src/routes/chat-completions.ts:190+212 does read x-tangle-forwarded-authorization and thread it to backends. ✓
  • agent-gateway/src/ has zero x-tangle-forwarded-* handling. ✓ (true negative)

Approving without further reservations. The new Implementation status table is exactly the kind of "what's actually shipped vs what the spec demands of conformant implementations" delineation that keeps a normative spec from rotting into vaporware.

Senior staff principal call to NOT build the original two follow-ups is the right one: cli-bridge depth is redundant with router-side enforcement, agent-gateway middleware has no consumer today. Both tracked on ops board for when a consumer surfaces.

@drewstone drewstone merged commit aa5de1c into main May 26, 2026
1 check passed
@drewstone drewstone deleted the fix/protocol-spec-accuracy branch May 26, 2026 23:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants