Skip to content

feat(gateway): a composed card states each child's environment_name, which lookups by name read (FD-5376) - #557

Merged
earakely-scale merged 3 commits into
mainfrom
edgararakelyan/fd-5376-gateway-card-environment-name
Nov 9, 2026
Merged

earakely-scale merged 3 commits into
mainfrom
edgararakelyan/fd-5376-gateway-card-environment-name

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

FD-5376, decision 2a of the site routing over the protocol design note.

The gateway now states each child env's environment_name on its entry in children_environments, and every lookup by name reads it. Until now, the environment name appeared only inside the child's URL path, /svc/<name>/. DeployedEnv.child_env matched on the child card's own name, so a server or website whose card is named differently from its environment name was missed by loads, snapshots and clock sync. Site routing parsed the path instead. SDK-built envs serve their environment name as their card name, so they never hit this.

What changes

  • Protocol: EnvironmentCard gains an optional environment_name, documented in the README.
    • ChildEnv carries it, and known_as gives the name a lookup uses: environment_name, else the card's name.
    • child_named and find_child look children up by it.
  • Gateway: _rewrite_child_card sets environment_name on each child, resolved from the route's backend (route_environment_name), so MCP servers foo and mcp-foo stay apart.
    • An MCP server's key is its route mcp-<name>, so the prefix comes off.
    • A website's or a computer's key is its own name, kept as is even when it starts with mcp-.
  • Readers use the stated name:
    • DeployedEnv.child_env;
    • website_child, which checks a website's route;
    • legacy_protocol.card_servers, which names the servers that snapshots, clock sync and apply_server_config list;
    • build_mcp_cli;
    • sites._served_as, which picks and names routed sites.
  • Older records: a card from a gateway that states no environment_name resolves exactly as before, by the card's name and the URL path.

Test plan

  • Unit:

    • the gateway's composed card states the right name for an MCP server, a website, a computer, and a computer named mcp-…;
    • known_as, child_named and find_child;
    • child_env finds a child whose card is named otherwise, and tells a website from an MCP server by route;
    • card_servers names servers by the stated name;
    • deployed_sites(services=...) picks a website by the stated name rather than its path;
    • older cards still resolve.
  • The full unit tier and the protocol tests pass locally, apart from the one Windows disk-recipe test that fails on this Mac without these changes.

  • CI green at 4c17c89: all 34 checks, the slow integration tier among them.

  • Integration, in CI's slow tier (af450dc, passed; all 34 checks green): the existing multi env computers e2e (test_a_computer_in_a_multi_env_is_served_through_its_gateway_under_its_name_and_torn_down_with_it) already deploys items, the shop website whose card is named webitems, and the desktop. It now also asserts that the gateway's card states items, shop and desktop, that child_env("shop", mcp=False) finds the website, that card_servers lists shop as a website and no webitems, and that the snapshot keeps it as shop. That adds no deploy. The foo / mcp-foo collision stays covered by unit tests: a deploy can't hold both items servers, which share a tool name.

  • VM e2e and chaos, comparing base eb2ce63 with this head. One multi env serves the items image under three environment names, items, mcp-items and stock, beside a website whose card is named webitems and served as shop. Each server's one fixed tool name is renamed, because a gateway refuses duplicate tool names.

    Check This head Base
    Stated names on the gateway's card items, mcp-items, stock, shop none
    child_env("shop") /svc/shop not found
    card_servers for the website shop, a website webitems, counted as an MCP server
    Snapshot names the website shop webitems
    Loads into stock, then two loads at once into mcp-items and items each lands only on its own server same
    docker restart the stock server, then load works same
    Reset, teardown every server empty, clean same

    On e236aaf, before the round-1 fix, the real gateway stated environment_name: mcp-items for both the items and mcp-items children, so child_env("items") found nothing. That was Greptile's P1, and 4c17c89 fixes it.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge; the added integration checks match the deployed website and snapshot behavior.

Summary

The gateway now states each child’s environment_name. Name-based lookups use it while keeping the fallback for older cards.

  • Gateway cards state the registered name of each child environment.
  • Child lookups and server lists use the name stated by the gateway.
  • Website filters use the name the gateway gives each site.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Backend[Child card] --> Gateway[Gateway adds environment_name]
  Gateway --> Card[Composed card]
  Card --> Lookup[Name-based lookup]
  Card --> Servers[Server listing]
  Servers --> Snapshot[Snapshot uses registered name]
Loading

Reviews (11) · Last reviewed commit: "test(gateway): the multi env e2e asserts..." · Reviewed by Greptile

…which lookups by name read (FD-5376)

The gateway sets environment_name on each entry of children_environments: an
MCP server's key without its mcp- prefix, a website's or a computer's key
itself. EnvironmentCard gains the optional field; ChildEnv carries it, and
known_as (the stated name, else the card's own) is what child_named,
find_child, DeployedEnv.child_env, website_child, legacy_protocol's server
listing, the MCP CLI builder and site routing's _served_as look children up
by. A server or website whose card is named apart from its environment name
is no longer missed by loads, snapshots and clock sync; a card from a gateway
that states none resolves as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale requested a review from a team as a code owner November 9, 2026 07:08
Comment thread src/agent_env/env/gateway/gateway.py Resolved
earakely-scale and others added 2 commits November 8, 2026 23:25
… so mcp-foo and mcp-mcp-foo stay apart

The gateway named a route by whether its key, or the key without mcp-, was an
internal MCP server's name, so with MCP servers foo and mcp-foo both routes,
mcp-foo and mcp-mcp-foo, were named mcp-foo. route_environment_name now asks
the route's backend: of the two readings, the MCP server mcp-<name> or a child
env under its own name, the one whose internal MCP endpoint is under the
route's base address wins, else the one on its host, as a server whose card is
on another port than its MCP endpoint is. With neither, an mcp- key is an MCP
server's route, as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ent_name, by which its website is found, listed and snapshotted

The shop website's card is named webitems, so the deploy that already serves it beside items and the desktop
checks the gateway's card names it shop, child_env finds it, card_servers lists it as a website and the
snapshot keeps it as shop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit 2e8cfee into main Nov 9, 2026
37 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/fd-5376-gateway-card-environment-name branch November 9, 2026 16:43
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.

1 participant