core: a protocol can be registered per client, not just per process

Merged
H3
2mo ago
+175-12

The problem

CommunicationProtocol.communicationProtocols holds instances, and every UtcpClient in the process copies the same ones into its private map. So whatever state a protocol keeps is shared by every client.

For a credential cache that is exactly right. For connections it is not: a caller who creates a client per tenant, per user, or per pooled connection is not isolating anything — they all reach into one shared session cache — and one client's close() drains everyone's sessions. There is no way to opt out, which is why a consumer that needed isolation ended up reaching into the client's private _registeredCommProtocols map (the motivation for #48, closed in favour of doing this properly).

The change

CommunicationProtocol.communicationProtocolFactories — the same registry, for protocols whose state belongs to one client:

CommunicationProtocol.communicationProtocolFactories['mcp'] = () => new McpCommunicationProtocol();

UtcpClient.create calls the factory once per client, so each gets its own instance, its own connections, and its own teardown on close().

  • A factory wins over an instance of the same type, so a plugin migrates by moving its registration between the two maps and callers change nothing.
  • The instance map is untouched — same type, same semantics — so a consumer that reads an instance back out of it keeps working. @utcp/direct-call's decorator does exactly that, deliberately, and is unaffected.

Which plugins move

  • @utcp/mcp → factory. It holds live MCP sessions and, for stdio, child processes; those belong to the client that opened them.
  • @utcp/http stays an instance. Its OAuth token cache is meant to be reused across clients — making it per-client would re-fetch tokens for every client.
  • CLI / file / text / direct-call stay instances (no-op close(), or shared by design).

Note the behaviour this changes for MCP: two clients in one process that previously shared a session cache now each dial their own. That is the intended semantic — clients are isolated — and it is what the shared cache was quietly preventing.

Tests

Four in tests/utcp_client.test.ts, in the existing save/restore-the-registry style: each client gets its own instance from a factory; instance registration stays shared; a factory wins over an instance; and close() drains this client's instance while another client keeps working. Mutation-checked — dropping the per-client instantiation fails three of them.

Core client suite 12/12, MCP suites 78/78. (Running all 15 test files in one bun test process shows 5 failures in stdio/e2e suites — identical on dev without this change; they are a fixed-port/mock-server isolation artifact of the combined run, not a regression here.)

🤖 Generated with Claude Code


Summary by cubic

Adds per-client protocol factories so a protocol's connection state is isolated to one UtcpClient instead of shared process-wide. A new communicationProtocolFactories registry on CommunicationProtocol gives each client its own instance, and a factory wins over an instance of the same type, so a plugin migrates by moving its registration and callers change nothing. @utcp/mcp now registers as a factory: each client gets its own sessions, so two clients that previously shared a session cache now each dial their own. @utcp/http stays a shared instance because its OAuth token cache is meant to be reused.

Dependencies

  • @utcp/sdk bumps to 1.2.0; @utcp/mcp bumps to 1.2.0 and requires ^1.2.0.
  • Installing @utcp/mcp against an older SDK would throw on import because the new registry doesn't exist there.
  • Other plugins keep their ^1.1.x floor since none use the new registry.