Port Registrar Foundation

[TalZaccai]

agentServer hosts many app-agents in one process, and several of those agents open their own WebSocket / HTTP listeners for out-of-process clients (Chrome extension, VS Code extension, the Visual Studio C# plugin, the onboarding helper). Today every one of those listeners hard-codes its port. That has two practical consequences:

• Two TypeAgent installs on the same machine collide. The second instance can't bind, and there's no good story for telling its clients where to look.
• Changing a port is a multi-repo edit. The agent and every external client have to move in lockstep.

We want to flip the model: agents bind port = 0, the OS picks a free port, the agent registers that port with a central registrar, and external clients discover the port over a well-known channel on agentServer.

This PR is the foundation only — it builds the registrar, plumbs it through the SDK, stands up the discovery channel, and ships the matching client-side discovery helper. Per-agent migrations follow in PRs 2–5.

What this PR introduces

A shared PortRegistrar

The registrar is owned by the dispatcher package rather than agentServer itself, so any future host of the dispatcher (the desktop shell, a hypothetical web API) gets the same model for free. agentServer is just the first host that wires one up.

The registrar tracks (agentName, role) → port allocations, scoped by an opaque sessionContextId so we can clean up everything an agent registered when its session ends. Re-registering the same (agent, role) replaces the prior entry rather than stacking duplicates — this matches what an agent actually means when it re-binds (e.g. after a config change).

A new SDK surface for agents

SessionContext gains registerPort(port, role?) / releasePort(id) and exposes a stable sessionContextId. The same surface is mirrored in agent-rpc so out-of-process agents see exactly what in-process agents see.

AppAgentManager mints a sessionContextId once per initializeSessionContext, clears it on closeSessionContext, and a finally backstop calls releaseAllForSession so a partially-failed init can't leak allocations.

A discovery channel on agentServer

A new WS-RPC channel named "discovery" is multiplexed onto the same WebSocket as the existing agent-server channel. It exposes one read-only call:

lookupPort(agentName, role?) → { port: number | null }

That's the only operation. Mutation (registering ports) requires being the agent itself, in-process, via SessionContext.registerPort — there is no remote register/release on the wire. null means "no such allocation"; callers don't need try/catch around every probe.

agentServer also calls setAgentServerPort() once it's listening, so the host itself is discoverable under the agent name agent-server — useful for clients that bootstrap from a different known port.

A client-side discoverPort() helper

The symmetric counterpart to the discovery channel, exported via a narrow ./discovery subpath on @typeagent/agent-server-client:

discoverPort(agentName, role?, { url?, timeoutMs? })
  → { kind: "found", port } | { kind: "not-registered" } | { kind: "unreachable", error }

The tagged result is intentional — it lets callers distinguish "agent isn't loaded yet, retry" from "agentServer isn't running, fall back to a hardcoded default for back-compat" without parsing error strings.

The reason it's a separate subpath rather than living on the top-level agent-server-client entry: extensions and service workers can't ship fs / os / child_process / dispatcher RPC. The ./discovery subpath imports only agent-rpc, isomorphic-ws, and the small agent-server-protocol constants module. PRs 2–5 all reuse this same import.

Idle-shutdown safety

agentServer's idle-shutdown timer now bails out when registrar.hasActiveAllocations() is true, so cached extension clients can reconnect to a still-running server. The backstop in closeSessionContext ensures the registrar drains naturally on session close, so this guard never wedges shutdown indefinitely.

Origin-allowlist hook on webSocketChannelServer

webSocketChannelServer accepts an optional originAllowlist (case-insensitive, supports a trailing * for prefix-match like chrome-extension://*; native CLI clients with no Origin header are always allowed). The hook is in place so future hardening doesn't require another protocol change.

Constants instead of 8999 everywhere

AGENT_SERVER_DEFAULT_PORT = 8999 and AGENT_SERVER_DEFAULT_URL now live in agent-server-protocol. All the places that previously hard-coded 8999 (CLI commands, the shell, vscode-shell, the Visual Studio webview, the browser extension service worker, uriHandler, commandExecutor, agentServer/{stop,status}) now import the constant. Behaviorally identical; just removes a class of "I changed it in one place but not the other" bugs.

A wire-format change worth calling out

ContextParams on agent-rpc gains a required sessionContextId field. This is safe because rpc client and server always build and ship together within this monorepo, but it's worth flagging for anyone watching for compatibility-affecting changes.

Validation

• Full pnpm run build from ts/ — green.
• pnpm run jest-esm --testPathPattern="portRegistrar|sessionContext" — 27/27 passing (registrar + session lifecycle).
• pnpm --filter @typeagent/agent-server-client test — 4/4 passing for discoverPort. These spin up a real ws server speaking the agent-rpc channel framing and exercise found, not-registered, unreachable (server bound and immediately closed), and timeout (server accepts but never resolves) — the missing wire-protocol coverage for the discovery channel.
• Manual smoke: agentServer starts on the default port, idle-shutdown defers while an allocation is held, and releases the moment closeSessionContext runs.

Reading order for reviewers

The PR is four commits, each independently buildable and reviewable:

1. feat(dispatcher): add PortRegistrar class with unit tests — pure data structure + tests. Read this first to internalize the model; nothing else depends on the rest of the codebase.
2. refactor(dispatcher): integrate PortRegistrar into AppAgentManager + SDK — wires the registrar into the dispatcher's session lifecycle and exposes the agent-facing API. The interesting bits are the sessionContextId lifecycle in appAgentManager.ts and the matching surface on agent-rpc.
3. agentServer: add discovery channel + consolidate AGENT_SERVER_PORT — the host wiring. The discovery channel handler in server.ts is small (one RPC method); most of the diff size is the mechanical 8999 → constant replacement across CLI/shell/extensions.
4. agent-server-client: add discoverPort helper + wire-protocol tests — symmetric client of commit 3. Small standalone helper + 4 integration tests against a real ws server speaking the actual framing. Bootstraps Jest in the package using the standard repo convention.

Follow-up PRs

PR	Scope
2	Migrate code agent (and trivially localView) — first consumer of discoverPort
3	Migrate browser agent service worker
4	Migrate visualStudio host webview
5	Migrate onboarding-scaffolder + tighten originAllowlist on agentServer

[Copilot]

Pull request overview

Introduces the foundational infrastructure for dynamic, discoverable per-agent ports by adding an in-memory PortRegistrar to the dispatcher, exposing a port-registration API via SessionContext (including agent-rpc parity), and hosting a new read-only discovery WS-RPC channel on agentServer. The PR also centralizes the agent-server default port/URL constants to eliminate scattered 8999 literals and adds an Origin allowlist hook to the WebSocket channel server for future hardening.

Changes:

• Add PortRegistrar (with unit tests) and wire it through dispatcher initialization + AppAgentManager session lifecycle.
• Add port registration surface to SessionContext (and agent-rpc) and introduce a new discovery WS-RPC channel (lookupPort) on agent-server.
• Consolidate default agent-server port/URL constants and replace hard-coded 8999 usages across CLI/shell/extensions.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
ts/packages/vscode-shell/src/agentServerBridge.ts	Use shared default agent-server URL constant instead of hard-coded 8999.
ts/packages/utils/webSocketChannelServer/src/server.ts	Add optional originAllowlist support via ws verifyClient during upgrade.
ts/packages/uriHandler/src/index.ts	Default CLI port now uses AGENT_SERVER_DEFAULT_PORT.
ts/packages/shell/src/main/args.ts	Shell default connect port now uses AGENT_SERVER_DEFAULT_PORT.
ts/packages/dispatcher/dispatcher/test/sessionContext.spec.ts	Update tests for new createSessionContext(..., sessionContextId) signature and mock portRegistrar.
ts/packages/dispatcher/dispatcher/test/portRegistrar.spec.ts	New unit tests for PortRegistrar behavior (register/lookup/release semantics).
ts/packages/dispatcher/dispatcher/src/index.ts	Export PortRegistrar and related types from dispatcher package.
ts/packages/dispatcher/dispatcher/src/execute/sessionContext.ts	Add sessionContextId and implement SessionContext.registerPort().
ts/packages/dispatcher/dispatcher/src/context/portRegistrar.ts	New in-memory registrar implementation with session-scoped allocations.
ts/packages/dispatcher/dispatcher/src/context/commandHandlerContext.ts	Add registrar to context and dispatcher options; construct/share registrar.
ts/packages/dispatcher/dispatcher/src/context/appAgentManager.ts	Generate/manage sessionContextId, route legacy port APIs through registrar, and ensure backstop cleanup on failure/close.
ts/packages/commandExecutor/src/commandServer.ts	Default agent-server URL now uses AGENT_SERVER_DEFAULT_URL.
ts/packages/cli/src/slashCommands.ts	Use AGENT_SERVER_DEFAULT_PORT for shutdown default.
ts/packages/cli/src/commands/server/stop.ts	Use AGENT_SERVER_DEFAULT_PORT as default flag value.
ts/packages/cli/src/commands/server/status.ts	Use AGENT_SERVER_DEFAULT_PORT as default flag value.
ts/packages/cli/src/commands/run/translate.ts	Use AGENT_SERVER_DEFAULT_PORT as default flag value.
ts/packages/cli/src/commands/run/request.ts	Use AGENT_SERVER_DEFAULT_PORT as default flag value.
ts/packages/cli/src/commands/run/explain.ts	Use AGENT_SERVER_DEFAULT_PORT as default flag value.
ts/packages/cli/src/commands/replay.ts	Use AGENT_SERVER_DEFAULT_PORT as default flag value.
ts/packages/cli/src/commands/conversations/rename.ts	Use AGENT_SERVER_DEFAULT_PORT as default flag value.
ts/packages/cli/src/commands/conversations/list.ts	Use AGENT_SERVER_DEFAULT_PORT as default flag value.
ts/packages/cli/src/commands/conversations/delete.ts	Use AGENT_SERVER_DEFAULT_PORT as default flag value.
ts/packages/cli/src/commands/conversations/create.ts	Use AGENT_SERVER_DEFAULT_PORT as default flag value.
ts/packages/cli/src/commands/connect.ts	Use AGENT_SERVER_DEFAULT_PORT as default flag value.
ts/packages/agentServer/server/src/stop.ts	Use AGENT_SERVER_DEFAULT_PORT when --port absent.
ts/packages/agentServer/server/src/status.ts	Use AGENT_SERVER_DEFAULT_PORT when --port absent.
ts/packages/agentServer/server/src/server.ts	Create shared registrar for all conversations; add discovery channel; idle shutdown now considers active allocations.
ts/packages/agentServer/protocol/src/protocol.ts	Define discovery channel name + RPC type, and add default port/URL constants.
ts/packages/agentServer/protocol/src/index.ts	Re-export discovery + default port/URL constants.
ts/packages/agentServer/client/src/index.ts	Re-export AGENT_SERVER_DEFAULT_PORT/URL to clients.
ts/packages/agentServer/client/src/agentServerClient.ts	Default port parameters now use AGENT_SERVER_DEFAULT_PORT.
ts/packages/agentSdk/src/agentInterface.ts	Add sessionContextId + new registerPort() API; deprecate legacy port methods.
ts/packages/agents/visualStudio/host/webview/src/main.ts	Display default agent-server URL via shared constant.
ts/packages/agents/visualStudio/host/webview/src/dispatcherConnection.ts	Replace hard-coded default URL with shared constant.
ts/packages/agents/browser/src/extension/serviceWorker/dispatcherConnection.ts	Replace hard-coded default URL with shared constant.
ts/packages/agents/browser/src/agent/websiteMemory.mts	Update SessionContext mock to include registerPort + sessionContextId.
ts/packages/agentRpc/src/types.ts	Add registerPort/releasePort RPC methods and require sessionContextId in ContextParams.
ts/packages/agentRpc/src/server.ts	Plumb sessionContextId through SessionContext shim; add registerPort implementation for out-of-process agents.
ts/packages/agentRpc/src/client.ts	Implement dispatcher-side handlers for registerPort/releasePort and include sessionContextId in context params.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[robgruen]

Do we want the notion of a transient port (i.e. one that can come and go i.e. not guaranteed to be up)?

[robgruen]

This isn't the place for that, just asking here since it just came to me.

[robgruen]

Should this be an enum?

[robgruen]

Should this then be a singleton if we ever just want one of them?

[robgruen]

dang, this was ALL OVER THE PLACE!

[robgruen]

Should this thing implement an interface such that others can provide their own port registration mechanism? Couldn't hurt to define the interface and export it on the off chance.

[robgruen]

instead of a triple key, couldn't this be an object that itself is the key? Would be easier to extend if we add a fourth property.

[robgruen]

Probably need a way to ensure that agents only release their own ports.