fix(gateway): servers sharing a tool name fail the deploy, naming the clash, instead of serving part of their tools

[earakely-scale]

If two servers behind a gateway serve the same tool name, the deploy now fails and names the tool and both servers. Before, it passed, and the env served a partial tool set.

Why

The gateway registered each server's tools in turn and raised on the first name it had already registered. Everything registered before that point stayed registered. Here is a multi of three items servers on main (items, stock, ledger), each registering list_items:

• the gateway listed items_add_item, list_items and stock_add_item, and none of ledger's tools;
• the deploy passed: readiness only reads the card, and the tools probe after it only logs;
• the real error, Duplicate tool name 'list_items': already registered from 'items', cannot register from 'stock', appeared only in the gateway container's log, and every /step and new MCP session hit it again.

An agent on that env sees some servers' tools and not others, and the run fails for reasons that look unrelated.

What

• All or nothing. Discovery lists every server's tools first and checks names across all of them, and across the gateway's own list_website_urls, before it registers any proxy. On a clash it registers nothing. A server that fails to list also leaves nothing registered now, where before the servers listed ahead of it kept their tools.

  • get_time keeps its rule: a backing server's tool of that name wins, and the clock refuses to arm over it.

• The gateway reports the clash. GET /state gains tool_name_clashes, a map from each clashing name to its sources, e.g. {"list_items": ["items", "stock"]}; it is empty when nothing clashes. /step answers 503 naming the clash. Servers' names don't change during a deploy, so neither does a clash: it is recorded once, and not rediscovered on each request.

  • The gateway logs it once at startup, without a traceback, and stays up to report it. A gateway that exits on startup would leave the deploy waiting out its readiness timeout.

• The deploy refuses it. Once the card is served, both deploy paths (VM and Modal containers) read /state and raise DeployRefused:

  The env's MCP servers serve duplicate tool names, which an agent couldn't tell apart, so its gateway serves none of their tools: 'list_items' from 'items' and 'stock'. Rename the tools, or deploy those servers in separate envs

  A gateway whose /state can't be read, or that doesn't report clashes (an image built before this change), is let through as before.

• A chain stops at a refused deploy. Every member would refuse it the same way, so _run raises DeployRefused at once instead of deploying again on the next member.

• A failed local deploy removes its work folder. When a failed or cancelled deploy terminates the VM it created, a sandbox on this machine now also loses its work folder. The run's teardown removes it for recorded sandboxes, but a deploy that fails is never recorded. The new slow test found this; any local gateway deploy that failed after creating its sandbox left the folder behind.

• The protocol README says names must also differ across the servers behind one gateway, and that {environment_name} keeps them apart.

Rollout

The provider check ships with the release. The gateway side reaches remote deploys only once the default gateway env is re-put in dev and prod. Until then, remote deploys behave as today: the old image doesn't report clashes, so the check lets them through. Local bundle runs build the gateway from the installed package, so they get both sides at once.

Before the re-put, env_deploy_tools_probe ... status=missing in the hub and worker logs would show any prod multi that hits a clash today. Such a multi runs on a partial tool set now and will be refused after the re-put. Synthetic servers prefix their tools with their service name, so a clash would take the same server deployed twice under different env names.

Tests

Unit tier and the protocol suite: 7,518 passed. New:

• gateway: a multi of three servers where two share list_items registers no tool, and the clash names the tool and both servers; three sources and several names are all named; a clash is raised again without listing the servers again; /state reports it and /step answers 503 naming it; with no clash, /state reports {} and every tool is registered; a backing list_website_urls clashes with the gateway's own, which stays registered; a backing get_time still wins over an armed clock with no clash; a server that fails to list leaves no tool of the servers listed before it; a clash at startup is logged once, without a traceback, and the gateway stays up;
• provider: a /state reporting a clash is refused with that message; one reporting none, without the field, or that can't be read lets the deploy through; a container deploy whose gateway reports a clash raises DeployRefused through a two-member chain, without trying the second, and terminates every container it made; the VM deploy reads /state at the gateway URL; a failed deploy removes a local VM's work folder, and leaves a remote one's alone;
• chain: _run stops at DeployRefused and closes the attempt.

Slow tier (run_bundle_built_envs_test.py):

• new: a multi of two items servers that both register list_items fails at its deploy step with the tool and both servers named, and leaves no sandbox work folder;
• the composed-universe test's multi holds three items servers, which share list_items too. That deploy now fails, so those servers prefix it with their environment_name, and the comment saying the verifier can't use MCP is gone.

Live check

From this machine, with agent-env run on two bundles: a multi of two items servers sharing list_items, and the same multi with the name prefixed per server, plus a verifier that adds and lists an item on each server through the gateway.

• local: the clashing multi failed at its deploy step in 26.7 s with the message above. No sandbox or work folder was left.
• Modal, through the container gateway: the clashing multi was refused in 30.2 s. The other multi passed its check in 32.7 s, with both servers' tools served, and the run tore down its 6 sandboxes. Afterwards the Modal app had no sandbox from either run.

Chaos

20 minutes of random cases on each of two fresh Linux VMs, running this branch from a clean clone with the local provider: Ubuntu 24.04 on amd64 (t3.large) and Ubuntu 22.04 on arm64 (t4g.large). After every case, the VM had to have no agent-env-local-* container, network or volume, and no sandbox work folder.

• Cases: two servers sharing list_items (2-way), three sharing it (3-way), a server registering list_website_urls in a multi with a website, a no-clash multi checked through the gateway, the same with one server sleeping 5–25 s before it serves, SIGINT or SIGTERM at a random 2–40 s, and three runs at once.
• Result: 54 of 54 checks passed on each VM.
  • Every clashing deploy (13 on amd64, 17 on arm64) failed at its deploy step with DeployRefused, naming every tool and server.
  • Every no-clash multi served both servers' tools, including those whose server was still asleep when the gateway started.
  • Every signal mid-run exited 130 or 143.
  • No case left anything behind, and no log held a traceback.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no new actionable defects were found.

Summary

The gateway checks all discovered tool names before registering proxies. It reports clashes through /state and /step, and both deploy paths refuse a reported clash.

• The gateway checks all tool names before it registers server tools.
• Deploys stop when the gateway reports duplicate tool names.
• Failed local VM deploys remove their work folder.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[List every backing server's tools] --> B{Names clash?}
  B -->|No| C[Build all proxies]
  C --> D[Register tools]
  B -->|Yes| E[Cache clash; register no backing tools]
  E --> F[Report clash through /state]
  F --> G[Deploy raises DeployRefused]
  G --> H[Close attempt and stop provider chain]

Loading

_{Reviews (2) · Last reviewed commit: "Merge main (v0.9.1319) into gateway-dupl..." · Reviewed by Greptile}