From 156f3e2498611787a42d0819605532ec9470ffa9 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 16 Feb 2026 18:45:03 -0800 Subject: [PATCH] feat(companion): add waitForEvent runtime helper --- README.md | 2 +- docs/plans/state.json | 14 ++++++++++ src/companion/index.ts | 1 + src/companion/runtimeClient.test.ts | 42 +++++++++++++++++++++++++++++ src/companion/runtimeClient.ts | 37 +++++++++++++++++++++++++ 5 files changed, 95 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2d71f8b..0d7364d 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 event subscriptions (`subscribeEvents()`, `subscribeEvent()`). +- `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 helpers (`subscribeEvents()`, `subscribeEvent()`, `waitForEvent()`). - `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 1b4a095..b341c5f 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -327,6 +327,20 @@ ], "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" }, + "companion-runtime-wait-for-event-helper": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Added `waitForEvent()` helper to `CompanionRuntimeClient` for promise-based event awaiting with timeout and optional payload predicate filtering.", + "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 ff0efef..4ef8de5 100644 --- a/src/companion/index.ts +++ b/src/companion/index.ts @@ -13,6 +13,7 @@ export type { CompanionRuntimeClientOptions, CompanionEventHandler, CompanionTypedEventHandler, + CompanionEventPredicate, RegisterNodeInput, ListNodesInput, SetNodeStatusInput, diff --git a/src/companion/runtimeClient.test.ts b/src/companion/runtimeClient.test.ts index 9c9223a..dd45910 100644 --- a/src/companion/runtimeClient.test.ts +++ b/src/companion/runtimeClient.test.ts @@ -187,6 +187,48 @@ describe('CompanionRuntimeClient', () => { expect(streamHandler).toHaveBeenCalledTimes(1); }); + it('waitForEvent resolves using optional predicate filter', async () => { + const client = new CompanionRuntimeClient({ + url: 'ws://127.0.0.1:1', + }); + + const awaited = client.waitForEvent<{ seq: number }>('agent.stream', { + timeoutMs: 2000, + predicate: (data) => data.seq === 2, + }); + + (client as unknown as { handleMessage: (raw: string) => void }).handleMessage( + JSON.stringify({ + id: 48, + event: 'agent.stream', + data: { seq: 1 }, + }), + ); + (client as unknown as { handleMessage: (raw: string) => void }).handleMessage( + JSON.stringify({ + id: 49, + event: 'agent.stream', + data: { seq: 2 }, + }), + ); + + await expect(awaited).resolves.toEqual({ seq: 2 }); + }); + + it('waitForEvent rejects on timeout', async () => { + vi.useFakeTimers(); + const client = new CompanionRuntimeClient({ + url: 'ws://127.0.0.1:1', + }); + + const awaited = expect( + client.waitForEvent('agent.stream', { timeoutMs: 100 }), + ).rejects.toThrow('Timed out waiting for event agent.stream'); + await vi.advanceTimersByTimeAsync(100); + await awaited; + vi.useRealTimers(); + }); + 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 82a682d..72b8408 100644 --- a/src/companion/runtimeClient.ts +++ b/src/companion/runtimeClient.ts @@ -43,6 +43,7 @@ export interface CompanionRuntimeClientOptions { export type CompanionEventHandler = (event: string, data: unknown) => void; export type CompanionTypedEventHandler = (data: TData) => void; +export type CompanionEventPredicate = (data: TData) => boolean; export interface RegisterNodeInput { nodeId: string; @@ -365,6 +366,42 @@ export class CompanionRuntimeClient { }); } + waitForEvent( + eventName: string, + options?: { + timeoutMs?: number; + predicate?: CompanionEventPredicate; + }, + ): Promise { + const timeoutMs = options?.timeoutMs ?? this.requestTimeoutMs; + const predicate = options?.predicate; + + return new Promise((resolve, reject) => { + let settled = false; + const unsubscribe = this.subscribeEvent(eventName, (data) => { + if (predicate && !predicate(data)) { + return; + } + if (settled) { + return; + } + settled = true; + clearTimeout(timeout); + unsubscribe(); + resolve(data); + }); + + const timeout = setTimeout(() => { + if (settled) { + return; + } + settled = true; + unsubscribe(); + reject(new Error(`Timed out waiting for event ${eventName}`)); + }, timeoutMs); + }); + } + async call(method: string, params?: Record): Promise { if (!this.connected) { if (!this.autoConnect) {