From b53f66c6cd2f9e0a210a346e42a74b196c10f228 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 16 Feb 2026 18:43:50 -0800 Subject: [PATCH] feat(companion): add filtered runtime event subscription helper --- README.md | 2 +- docs/plans/state.json | 14 +++++++++++ src/companion/index.ts | 1 + src/companion/runtimeClient.test.ts | 36 +++++++++++++++++++++++++++++ src/companion/runtimeClient.ts | 13 +++++++++++ 5 files changed, 65 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0e8dbb1..2d71f8b 100644 --- a/README.md +++ b/README.md @@ -1190,7 +1190,7 @@ Methods: - `system.capabilities` returns gateway protocol and node policy snapshot. Companion runtime helper: -- `src/companion/runtimeClient.ts` provides a typed Node/WebSocket client for companion runtimes (macOS/iOS/Android workers) with wrappers for `node.register`, `node.capabilities.get`, `node.location.set/get`, `node.status.set`, `node.push_token.set`, `system.capabilities`, `system.nodes`, and canvas artifact RPCs (`canvas.put/get/list/delete/clear`), plus optional `autoConnect` mode and `subscribeEvents()` for gateway stream events. +- `src/companion/runtimeClient.ts` provides a typed Node/WebSocket client for companion runtimes (macOS/iOS/Android workers) with wrappers for `node.register`, `node.capabilities.get`, `node.location.set/get`, `node.status.set`, `node.push_token.set`, `system.capabilities`, `system.nodes`, and canvas artifact RPCs (`canvas.put/get/list/delete/clear`), plus optional `autoConnect` mode and event subscriptions (`subscribeEvents()`, `subscribeEvent()`). - `src/companion/platformClients.ts` provides platform-focused wrappers: - `MacOSCompanionClient` (`platform: "macos"`, APNs push registration) - `IOSCompanionClient` (`platform: "ios"`, APNs push registration) diff --git a/docs/plans/state.json b/docs/plans/state.json index 708d900..1b4a095 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -313,6 +313,20 @@ ], "test_status": "pnpm test:run src/companion/runtimeClient.test.ts src/companion/platformClients.test.ts src/companion/platformClients.integration.test.ts + pnpm typecheck passing" }, + "companion-runtime-filtered-event-helper": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Added typed `subscribeEvent(eventName, handler)` helper to `CompanionRuntimeClient` for filtered event consumption on top of generic `subscribeEvents`, including unsubscribe behavior tests.", + "files_modified": [ + "src/companion/runtimeClient.ts", + "src/companion/runtimeClient.test.ts", + "src/companion/index.ts", + "README.md", + "docs/plans/state.json" + ], + "test_status": "pnpm test:run src/companion/runtimeClient.test.ts src/companion/platformClients.test.ts src/companion/platformClients.integration.test.ts src/companion/heartbeatLoop.test.ts + pnpm typecheck passing" + }, "browser-tools-activation-clarity": { "status": "completed", "date": "2026-02-17", diff --git a/src/companion/index.ts b/src/companion/index.ts index 2795ca3..ff0efef 100644 --- a/src/companion/index.ts +++ b/src/companion/index.ts @@ -12,6 +12,7 @@ export { CompanionHeartbeatLoop } from './heartbeatLoop.js'; export type { CompanionRuntimeClientOptions, CompanionEventHandler, + CompanionTypedEventHandler, RegisterNodeInput, ListNodesInput, SetNodeStatusInput, diff --git a/src/companion/runtimeClient.test.ts b/src/companion/runtimeClient.test.ts index bb674df..9c9223a 100644 --- a/src/companion/runtimeClient.test.ts +++ b/src/companion/runtimeClient.test.ts @@ -151,6 +151,42 @@ describe('CompanionRuntimeClient', () => { expect(goodHandler).toHaveBeenCalledWith('agent.stream', { token: 'safe' }); }); + it('supports filtered subscribeEvent helper', () => { + const client = new CompanionRuntimeClient({ + url: 'ws://127.0.0.1:1', + }); + const streamHandler = vi.fn(); + const unsubscribe = client.subscribeEvent<{ token: string }>('agent.stream', streamHandler); + + (client as unknown as { handleMessage: (raw: string) => void }).handleMessage( + JSON.stringify({ + id: 45, + event: 'agent.stream', + data: { token: 'first' }, + }), + ); + (client as unknown as { handleMessage: (raw: string) => void }).handleMessage( + JSON.stringify({ + id: 46, + event: 'agent.typing', + data: { active: true }, + }), + ); + + expect(streamHandler).toHaveBeenCalledTimes(1); + expect(streamHandler).toHaveBeenCalledWith({ token: 'first' }); + + unsubscribe(); + (client as unknown as { handleMessage: (raw: string) => void }).handleMessage( + JSON.stringify({ + id: 47, + event: 'agent.stream', + data: { token: 'second' }, + }), + ); + expect(streamHandler).toHaveBeenCalledTimes(1); + }); + it('connects and performs node registration + capability discovery', async () => { if (!LISTEN_ALLOWED) { return; diff --git a/src/companion/runtimeClient.ts b/src/companion/runtimeClient.ts index ce40fa9..82a682d 100644 --- a/src/companion/runtimeClient.ts +++ b/src/companion/runtimeClient.ts @@ -42,6 +42,7 @@ export interface CompanionRuntimeClientOptions { } export type CompanionEventHandler = (event: string, data: unknown) => void; +export type CompanionTypedEventHandler = (data: TData) => void; export interface RegisterNodeInput { nodeId: string; @@ -352,6 +353,18 @@ export class CompanionRuntimeClient { }; } + subscribeEvent( + eventName: string, + handler: CompanionTypedEventHandler, + ): () => void { + return this.subscribeEvents((event, data) => { + if (event !== eventName) { + return; + } + handler(data as TData); + }); + } + async call(method: string, params?: Record): Promise { if (!this.connected) { if (!this.autoConnect) {