From 21a57c88b96660f21f9f79ce7a39fa5fac016384 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 16 Feb 2026 20:52:49 -0800 Subject: [PATCH] feat(companion): expose pending event wait observability --- README.md | 4 ++-- docs/plans/state.json | 15 +++++++++++++++ src/companion/platformClients.test.ts | 13 +++++++++++++ src/companion/platformClients.ts | 12 ++++++++++++ src/companion/runtimeClient.test.ts | 3 +++ src/companion/runtimeClient.ts | 4 ++++ 6 files changed, 49 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 01ec8ce..a1109ef 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, 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 RPC observability via `pendingRequestCount`. +- `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`) plus in-flight observability via `pendingRequestCount` and `pendingEventWaitCount`. - `src/companion/platformClients.ts` provides platform-focused wrappers: - `MacOSCompanionClient` (`platform: "macos"`, APNs push registration) - `IOSCompanionClient` (`platform: "ios"`, APNs push registration) @@ -1201,7 +1201,7 @@ Companion runtime helper: - optional `defaultSessionId` for canvas helper calls so `sessionId` can be omitted per call - lifecycle passthroughs for connection state/teardown (`connected`, `dispose(code?, reason?)`) - stream passthrough helpers (`subscribeEvents`, `subscribeEvent`, `clearEventSubscriptions`, `listKnownEventNames`, `eventSubscriptionCount`, `subscribeAgentStream/Typing/ContextWarning`, `waitForEvent`, `waitForAnyEvent`, `waitForAgentStream/Typing/ContextWarning`) - - runtime observability passthroughs (`pendingRequestCount`, `connected`) + - runtime observability passthroughs (`pendingRequestCount`, `pendingEventWaitCount`, `connected`) - `src/companion/heartbeatLoop.ts` provides `CompanionHeartbeatLoop` for periodic heartbeat scheduling (`publishHeartbeat`) with start/stop safety, optional interval jitter (`jitterRatio`) to spread load, `tickNow()` for manual sends, success/error hooks, loop observability (`successCount`, `lastSuccessAt`, `failureCount`, `lastFailure`, `getState()`), and optional auto-stop after repeated failures. ## Canvas / A2UI Foundation diff --git a/docs/plans/state.json b/docs/plans/state.json index 7930417..8269b3c 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -858,6 +858,21 @@ ], "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-pending-event-wait-observability": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Added runtime `pendingEventWaitCount` observability and platform passthrough getters so companion runtimes can inspect active waiter cardinality for `waitFor*` event flows.", + "files_modified": [ + "src/companion/runtimeClient.ts", + "src/companion/runtimeClient.test.ts", + "src/companion/platformClients.ts", + "src/companion/platformClients.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/platformClients.test.ts b/src/companion/platformClients.test.ts index efb9b2e..73c6ac6 100644 --- a/src/companion/platformClients.test.ts +++ b/src/companion/platformClients.test.ts @@ -39,6 +39,7 @@ function createRuntimeMock(): { waitForAnyEvent: ReturnType; eventSubscriptionCount: number; pendingRequestCount: number; + pendingEventWaitCount: number; connected: boolean; } { const connect = vi.fn(async () => undefined); @@ -79,6 +80,7 @@ function createRuntimeMock(): { const waitForAnyEvent = vi.fn(async () => ({ event: 'agent.stream', data: { token: 'any' } })); const eventSubscriptionCount = 3; const pendingRequestCount = 2; + const pendingEventWaitCount = 1; const connected = true; const runtime = { @@ -117,6 +119,9 @@ function createRuntimeMock(): { get pendingRequestCount() { return pendingRequestCount; }, + get pendingEventWaitCount() { + return pendingEventWaitCount; + }, get connected() { return connected; }, @@ -155,6 +160,7 @@ function createRuntimeMock(): { waitForAnyEvent, eventSubscriptionCount, pendingRequestCount, + pendingEventWaitCount, connected, }; } @@ -307,6 +313,13 @@ describe('platform companion clients', () => { expect(client.pendingRequestCount).toBe(mock.pendingRequestCount); }); + it('platform pendingEventWaitCount forwards runtime getter value', async () => { + const mock = createRuntimeMock(); + const client = new IOSCompanionClient({ runtime: mock.runtime, nodeId: 'ios-node' }); + + expect(client.pendingEventWaitCount).toBe(mock.pendingEventWaitCount); + }); + it('macOS client forwards canvas methods to runtime client', async () => { const mock = createRuntimeMock(); const client = new MacOSCompanionClient({ runtime: mock.runtime, nodeId: 'mac-node' }); diff --git a/src/companion/platformClients.ts b/src/companion/platformClients.ts index 82e030c..a2cfc0d 100644 --- a/src/companion/platformClients.ts +++ b/src/companion/platformClients.ts @@ -279,6 +279,10 @@ export class MacOSCompanionClient { return this.runtime.pendingRequestCount; } + get pendingEventWaitCount(): number { + return this.runtime.pendingEventWaitCount; + } + waitForAnyEvent( eventNames: readonly (CompanionEventName | string)[], options?: { @@ -525,6 +529,10 @@ export class IOSCompanionClient { return this.runtime.pendingRequestCount; } + get pendingEventWaitCount(): number { + return this.runtime.pendingEventWaitCount; + } + waitForAnyEvent( eventNames: readonly (CompanionEventName | string)[], options?: { @@ -769,6 +777,10 @@ export class AndroidCompanionClient { return this.runtime.pendingRequestCount; } + get pendingEventWaitCount(): number { + return this.runtime.pendingEventWaitCount; + } + waitForAnyEvent( eventNames: readonly (CompanionEventName | string)[], options?: { diff --git a/src/companion/runtimeClient.test.ts b/src/companion/runtimeClient.test.ts index 2e1128b..792c26b 100644 --- a/src/companion/runtimeClient.test.ts +++ b/src/companion/runtimeClient.test.ts @@ -305,11 +305,13 @@ describe('CompanionRuntimeClient', () => { const client = new CompanionRuntimeClient({ url: 'ws://127.0.0.1:1', }); + expect(client.pendingEventWaitCount).toBe(0); const awaited = client.waitForEvent<{ seq: number }>('agent.stream', { timeoutMs: 2000, predicate: (data) => data.seq === 2, }); + expect(client.pendingEventWaitCount).toBe(1); (client as unknown as { handleMessage: (raw: string) => void }).handleMessage( JSON.stringify({ @@ -327,6 +329,7 @@ describe('CompanionRuntimeClient', () => { ); await expect(awaited).resolves.toEqual({ seq: 2 }); + expect(client.pendingEventWaitCount).toBe(0); }); it('waitForEvent rejects on timeout', async () => { diff --git a/src/companion/runtimeClient.ts b/src/companion/runtimeClient.ts index 6c186c0..8cf1611 100644 --- a/src/companion/runtimeClient.ts +++ b/src/companion/runtimeClient.ts @@ -306,6 +306,10 @@ export class CompanionRuntimeClient { return this.pending.size; } + get pendingEventWaitCount(): number { + return this.pendingEventWaits.size; + } + async connect(): Promise { if (this.connected) { return;