[FrostGod]

Summary

The TypeScript SDK now sends exec, interactive exec, and port-forward calls straight to the gateway replica that owns the sandbox's supervisor session, as the CLI already does. Behind an edge proxy with replica routing enabled, this skips the relay hop through a peer replica; without one, the header is ignored and behavior is unchanged.

Related Issue

Part of #4223 (the "Every SDK asks for the owner and sends the replica hint, like the CLI" item, TypeScript portion). Rust is #4790, Go is #4852; Python follows in a separate PR.

Changes

• execStream, execInteractive, and forward already call GetSandbox first; that call now also asks for the owner, so no round trip is added.
• New private routing.ts: sends x-openshell-replica on those streams and retries once without it when Envoy reports the owner's route has no ready endpoints (same rule as the CLI). Interactive and forward input is held until response headers arrive, so a retry only resends the start/init frame.
• Calls are unchanged when the gateway reports no owner.

Release Notes

TypeScript SDK exec and port-forward calls now take the direct route to the sandbox's owner replica when replica routing is enabled.

Testing

• Checks appropriate to the affected code and behavior pass (mise run sdk:ts:ci: codegen, proto lint, Biome, type check, tests, coverage, build)
• Unit tests added/updated (HTTP/2 mock gateway with a trailers-only proxy rejection: routing to the owner, no hint without an owner, one unrouted retry for exec/interactive/forward without losing stdin, no retry on gateway errors, retry rule)
• E2E tests added/updated (if applicable). Manual check on a local k3s VM (Ubuntu 26.04, Landlock-capable kernel) with Envoy Gateway and two StatefulSet replicas, using a real sandbox and supervisor session: exec, interactive exec with stdin, and forward round trips all landed on the owner replica (unhinted baseline split 6/4), still succeeded via unrouted retry and peer relay when the owner's route had no endpoints, and followed the owner to the other replica after a gateway restart.

Note: forward() on main sends workspaceScope in TcpForwardInit, which only has a workspace field, so the gateway rejects it with "workspace name is required". That is pre-existing and not changed here; the forward round trips above were run with that field patched locally.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.