feat: pluggable client transport with a plain WebSocket option

[mm-zacharydavison]

🧑‍🦱 @masudahiroto & @yuma2024 : I want to use use-ai for Cordless UI, so we can also be users of the library and contribute / test it.
But Cordless is a Go application, so cannot run Socket.IO for transport, so I added support for plain WebSocket transport, and an abstraction for transport.

Please check it.

Summary

UseAIClient builds its own Socket.IO socket today, so a Socket.IO server is the only server it can reach. This PR gives the client a transport seam and ships two transports.

• SocketIOTransport keeps today's behaviour. It is the default.
• WebSocketTransport carries AG-UI events as JSON text frames over a plain WebSocket. Use it to reach a server that does not serve Socket.IO. That server does not have to be Node.

Nothing existing changes. new UseAIClient(url) still works. A UseAIProvider given serverUrl still connects over Socket.IO.

Client

• UseAITransport has five members: connect, disconnect, send, on, connected.
• UseAIClient takes string | UseAITransport.
• UseAIConfig is a discriminated union: give UseAIProvider exactly one of serverUrl or transport. The provider reads transport once, on the first render, so an inline object does not reconnect the client on every render. UseAIContextValue.serverUrl becomes optional.
• WebSocketTransport reconnects through partysocket, with the same limits as Socket.IO: indefinite, one second doubling to ten.
• The transport-upgrade logging and connect_error stay inside SocketIOTransport. Both are specific to Socket.IO.

Server

• transport?: 'socketio' | 'websocket' (default 'socketio'). The server runs one listener. With 'websocket', it does not create a Socket.IO server; it accepts WebSocket upgrades at /.
• Both runtime adapters take a RuntimeListener union. Bun uses Bun.serve's own upgrade. Node uses ws in noServer mode.
• ClientSession.socket narrows from Socket to ClientConnection (id, connected, emit). A Socket.IO socket satisfies it structurally, so FeedbackPlugin and WorkflowsPlugin are unchanged.
• The Docker image reads TRANSPORT.

Framing

Upstream, the client sends each UseAIClientMessage as one frame, with nothing around it. Downstream, the server sends one AG-UI event per frame. agents and config travel as AG-UI CUSTOM events. The client ignores an event type or a custom name it does not know. See docs/websocket-protocol.md.

Tests

• client.test.ts runs table-driven over both transports: 64 tests, up from 29. Each harness drives its transport at the wire level.
• SocketIOTransport.test.ts keeps the socket.io-client module mock and covers connect_error, the io() options and upgrade logging.
• WebSocketTransport.test.ts covers framing, CUSTOM routing, unknown names, malformed frames, connected, reconnection, and disconnect() stopping it.
• websocket-transport.integration.test.ts drives a real WebSocketTransport against a real transport: 'websocket' server through prompt → tool call → tool result → RUN_FINISHED, on both the Bun and Node adapters. It also checks that a default server refuses a plain WebSocket.

bun run test and bun run build pass. apps/example passes suggestions.e2e with real API calls. tool-approval.e2e and dynamic-tool-registration.e2e fail identically on main, so they are pre-existing.

Dependencies

packages/client adds partysocket. packages/server adds ws as a dependency and @meetsmore-oss/use-ai-client as a devDependency, so the integration test imports the real transport rather than a stub.

Not in this PR

No version bump or release. The change is additive, so a minor bump fits when you release.

🤖 Generated with Claude Code

[mm-zacharydavison]

Simplification pass in 6970d43, net -271 lines on the branch.

• UseAITransport is now onEvent(AGUIEvent) + onConnectionChange. The five Socket.IO-shaped channels, handlerRegistry.ts and UseAITransportEventName are gone. SocketIOTransport presents its legacy agents/config events as AG-UI CUSTOM, so a third-party transport only has to deliver AG-UI events.
• Server: ClientConnection is the whole per-connection boundary. SocketIOClientConnection / WebSocketClientConnection own their protocol details and server.ts has one acceptConnection.
• Bun adapter: { path, upgrade, websocket } per listener, connection kept on ws.data, no tri-state return, no WeakMap. Named SocketIOListener / WebSocketListener types replace the infer gymnastics.
• Dropped SocketIOTransportOptions (nothing used it), the unused client.serverUrl getter, the duplicated test fakes, the 5 s negative test, and the per-message session lookup.