docs(protocol): correct depth-refusal contract to match live router behavior by drewstone · Pull Request #65 · tangle-network/agent-runtime

drewstone · 2026-05-26T23:44:47Z

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

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.
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.

tangletools

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 · 2026-05-26T23:44:47Z

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

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.
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.

tangletools

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 · 2026-05-26T23:44:47Z

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

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.
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.

tangletools

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 · 2026-05-26T23:44:47Z

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

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.
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.

tangletools

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 · 2026-05-26T23:44:47Z

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

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.
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.

tangletools

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 · 2026-05-26T23:44:47Z

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

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.
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.

tangletools

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 · 2026-05-26T23:44:47Z

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

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.
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.

tangletools

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 · 2026-05-26T23:44:47Z

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

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.
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.

tangletools

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.