diff --git a/README.md b/README.md index a230645..d6706cf 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()`, `waitForIdle()` for pending-work drain synchronization) 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`) plus in-flight observability via `pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, and `getPendingWorkSnapshot()`. +- `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()`, `waitForIdle()` for pending-work drain synchronization) and event helpers (`subscribeEvents()`, `subscribeEvent()`, `subscribeAgentStream()`, `subscribeAgentTyping()`, `subscribeContextWarning()`, `waitForEvent()` with timeout/predicate/abort support plus event-name/timeout validation and deterministic teardown cancellation including socket-close rejection, `waitForAnyEvent()` with event-list/timeout validation, `waitForAgentStream()`, `waitForAgentTyping()`, `waitForContextWarning()`, `clearEventSubscriptions()`, `listKnownEventNames()`, `eventSubscriptionCount`) plus in-flight observability via `pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, and `getPendingWorkSnapshot()`. - `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 64656f8..8f9460c 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -1027,6 +1027,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-timeout-validation": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Added explicit `timeoutMs` validation (`> 0`) for `waitForEvent()` and `waitForAnyEvent()` to ensure deterministic option guardrails across runtime event wait helpers.", + "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 5b70189..0364b24 100644 --- a/src/companion/runtimeClient.test.ts +++ b/src/companion/runtimeClient.test.ts @@ -359,6 +359,9 @@ describe('CompanionRuntimeClient', () => { expect(() => client.waitForEvent(123 as unknown as string)).toThrow( 'eventName must be a non-empty string', ); + expect(() => client.waitForEvent('agent.stream', { timeoutMs: 0 })).toThrow( + 'timeoutMs must be a positive number', + ); }); it('waitForEvent supports AbortSignal cancellation', async () => { @@ -600,6 +603,9 @@ describe('CompanionRuntimeClient', () => { expect(() => client.waitForAnyEvent(['agent.stream', 123 as unknown as string])).toThrow( 'eventNames must not contain empty values', ); + expect(() => client.waitForAnyEvent(['agent.stream'], { timeoutMs: 0 })).toThrow( + 'timeoutMs must be a positive number', + ); }); it('tracks pendingRequestCount for in-flight RPCs', async () => { diff --git a/src/companion/runtimeClient.ts b/src/companion/runtimeClient.ts index c470feb..ae8adb2 100644 --- a/src/companion/runtimeClient.ts +++ b/src/companion/runtimeClient.ts @@ -477,6 +477,9 @@ export class CompanionRuntimeClient { throw new Error('eventName must be a non-empty string'); } const timeoutMs = options?.timeoutMs ?? this.requestTimeoutMs; + if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) { + throw new Error('timeoutMs must be a positive number'); + } const predicate = options?.predicate; const signal = options?.signal; @@ -550,6 +553,9 @@ export class CompanionRuntimeClient { } const eventNameSet = new Set(eventNames); const timeoutMs = options?.timeoutMs ?? this.requestTimeoutMs; + if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) { + throw new Error('timeoutMs must be a positive number'); + } const predicate = options?.predicate; const signal = options?.signal;