From 490ca7def92639e78f5e4247f003c959cd293601 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 16 Feb 2026 19:43:32 -0800 Subject: [PATCH] feat(companion): validate event wait helper input names --- README.md | 2 +- docs/plans/state.json | 13 +++++++++++++ src/companion/runtimeClient.test.ts | 12 ++++++++++++ src/companion/runtimeClient.ts | 6 ++++++ 4 files changed, 32 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c0dd68e..7855936 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 convenience helpers (`bootstrapNode`, optional `autoConnect`, `dispose()`) and event helpers (`subscribeEvents()`, `subscribeEvent()`, `subscribeAgentStream()`, `subscribeAgentTyping()`, `subscribeContextWarning()`, `waitForEvent()` with timeout/predicate/abort support and deterministic teardown cancellation (including socket-close rejection), `waitForAnyEvent()`, `waitForAgentStream()`, `waitForAgentTyping()`, `waitForContextWarning()`, `clearEventSubscriptions()`, `listKnownEventNames()`, `eventSubscriptionCount`). +- `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 convenience helpers (`bootstrapNode`, optional `autoConnect`, `dispose()`) and event helpers (`subscribeEvents()`, `subscribeEvent()`, `subscribeAgentStream()`, `subscribeAgentTyping()`, `subscribeContextWarning()`, `waitForEvent()` with timeout/predicate/abort support, non-empty event-name validation, and deterministic teardown cancellation (including socket-close rejection), `waitForAnyEvent()` (with non-empty event-name-list validation), `waitForAgentStream()`, `waitForAgentTyping()`, `waitForContextWarning()`, `clearEventSubscriptions()`, `listKnownEventNames()`, `eventSubscriptionCount`). - `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 1230449..12cc5a6 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -796,6 +796,19 @@ ], "test_status": "pnpm test:run src/companion/runtimeClient.test.ts src/companion/platformClients.test.ts src/companion/heartbeatLoop.test.ts src/companion/platformClients.integration.test.ts + pnpm typecheck passing" }, + "companion-runtime-event-name-input-validation": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Added runtime input validation for event wait helpers so `waitForEvent()` rejects empty event names and `waitForAnyEvent()` rejects lists containing empty names.", + "files_modified": [ + "src/companion/runtimeClient.ts", + "src/companion/runtimeClient.test.ts", + "README.md", + "docs/plans/state.json" + ], + "test_status": "pnpm test:run src/companion/runtimeClient.test.ts src/companion/platformClients.test.ts src/companion/heartbeatLoop.test.ts src/companion/platformClients.integration.test.ts + pnpm typecheck passing" + }, "browser-tools-activation-clarity": { "status": "completed", "date": "2026-02-17", diff --git a/src/companion/runtimeClient.test.ts b/src/companion/runtimeClient.test.ts index 650e257..991818e 100644 --- a/src/companion/runtimeClient.test.ts +++ b/src/companion/runtimeClient.test.ts @@ -343,6 +343,15 @@ describe('CompanionRuntimeClient', () => { vi.useRealTimers(); }); + it('waitForEvent validates eventName input', () => { + const client = new CompanionRuntimeClient({ + url: 'ws://127.0.0.1:1', + }); + + expect(() => client.waitForEvent('')).toThrow('eventName must be a non-empty string'); + expect(() => client.waitForEvent(' ')).toThrow('eventName must be a non-empty string'); + }); + it('waitForEvent supports AbortSignal cancellation', async () => { const client = new CompanionRuntimeClient({ url: 'ws://127.0.0.1:1', @@ -573,6 +582,9 @@ describe('CompanionRuntimeClient', () => { expect(() => client.waitForAnyEvent([])).toThrow( 'eventNames must contain at least one event name', ); + expect(() => client.waitForAnyEvent(['agent.stream', ' '])).toThrow( + 'eventNames must not contain empty values', + ); }); it('connects and performs node registration + capability discovery', async () => { diff --git a/src/companion/runtimeClient.ts b/src/companion/runtimeClient.ts index 7968767..053528d 100644 --- a/src/companion/runtimeClient.ts +++ b/src/companion/runtimeClient.ts @@ -437,6 +437,9 @@ export class CompanionRuntimeClient { signal?: AbortSignal; }, ): Promise { + if (eventName.trim().length === 0) { + throw new Error('eventName must be a non-empty string'); + } const timeoutMs = options?.timeoutMs ?? this.requestTimeoutMs; const predicate = options?.predicate; const signal = options?.signal; @@ -502,6 +505,9 @@ export class CompanionRuntimeClient { if (eventNames.length === 0) { throw new Error('eventNames must contain at least one event name'); } + if (eventNames.some((eventName) => eventName.trim().length === 0)) { + throw new Error('eventNames must not contain empty values'); + } const eventNameSet = new Set(eventNames); const timeoutMs = options?.timeoutMs ?? this.requestTimeoutMs; const predicate = options?.predicate;