test(gateway): a real gateway in front of a real protocol child, over loopback

[earakely-scale]

Summary

#153 binds a ToolContext per tool call inside the protocol, and #145 makes the gateway stamp the caller's role and session on each proxied call. Each was tested on its own side with the other faked. This adds the test that puts a real gateway in front of a real protocol child over loopback, in the integration-local tier:

• two MCP clients with different AgentEnv-Role headers reach the child's tools as two callers, each with the gateway's per-session key rather than the gateway's connection id, stable across calls on one session;
• a tool that never declared a ToolContext parameter keeps its schema and is served as before, with the caller still readable through ToolContext.current();
• a refusal returned by the child's on_tool_call reaches the client through the gateway as isError with its payload intact;
• a gateway /step call carries the role and no session; a client connecting to the child directly gets its header role and its own connection id;
• the gateway's and the protocol's wire names are the same constants.

Two protocol docstrings are corrected on the way, with no code change: the marker on the installed dispatch is read by the mount's own second-handler check, not by a downstream boot guard, and caller_from_request takes a _meta session whenever one is present, with or without a _meta role entry.

Testing

• tst/integration/env/gateway/role_forwarding_local_test.py with packages/agentenv-protocol/tests: 429 passed, clean under -W error::DeprecationWarning.

🤖 Generated with Claude Code

Confidence Score: 4/5

The PR appears safe to merge, with a non-blocking improvement needed to clean up servers after test failures.

Findings

1.  Failed tests leave servers running ▶

Fix with agent prompt

### Issue 1
tst/integration/env/gateway/role_forwarding_local_test.py:71-75
Both servers start before `_stack` enters its `try` block. If gateway setup raises, the child server stays open. An error during gateway shutdown also skips child shutdown. These leftover servers and tasks can add cleanup warnings and obscure the original test failure.

Register cleanup immediately after each server starts, using nested `try/finally` blocks or `AsyncExitStack`, so both servers close even when setup or teardown fails.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds a loopback integration test with a real gateway and protocol child.

• The gateway and protocol child now get tested together over loopback.
• Protocol docs clarify the tool marker and caller session rules.

Diagram

sequenceDiagram
  participant C as MCP clients
  participant G as Gateway
  participant P as Protocol child
  C->>G: Connect with separate roles
  G->>P: Call tool with role and session
  P-->>G: Tool result or refusal
  G-->>C: Return result
  C->>G: POST /step with role
  G->>P: Call tool with role, no session
  C->>P: Direct call with role header
  P-->>C: Role and child connection session

Loading

_{Reviews (1) · Last reviewed commit: "docs(protocol): say what the dispatch ma..." · Reviewed by Greptile}

[greptile-apps]

Failed tests leave servers running

Both servers start before _stack enters its try block. If gateway setup raises, the child server stays open. An error during gateway shutdown also skips child shutdown. These leftover servers and tasks can add cleanup warnings and obscure the original test failure.

Register cleanup immediately after each server starts, using nested try/finally blocks or AsyncExitStack, so both servers close even when setup or teardown fails.

Prompt To Fix With AI

This is a comment left during a code review.
Path: tst/integration/env/gateway/role_forwarding_local_test.py
Line: 71-75

Comment:
**Failed tests leave servers running**

Both servers start before `_stack` enters its `try` block. If gateway setup raises, the child server stays open. An error during gateway shutdown also skips child shutdown. These leftover servers and tasks can add cleanup warnings and obscure the original test failure.

Register cleanup immediately after each server starts, using nested `try/finally` blocks or `AsyncExitStack`, so both servers close even when setup or teardown fails.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.