core: a protocol can be registered per client, not just per process
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/httpstays 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/sdkbumps to 1.2.0;@utcp/mcpbumps to 1.2.0 and requires^1.2.0.- Installing
@utcp/mcpagainst an older SDK would throw on import because the new registry doesn't exist there. - Other plugins keep their
^1.1.xfloor since none use the new registry.