From 0eb81263492df2092c304f4dca576e832639a326 Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 16 Feb 2026 19:28:48 -0800 Subject: [PATCH] feat(companion): add generic platform event passthroughs --- README.md | 2 +- docs/plans/state.json | 13 ++++++++ src/companion/platformClients.test.ts | 15 +++++++++ src/companion/platformClients.ts | 47 +++++++++++++++++++++++++++ 4 files changed, 76 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8ffb3ab..0f4b43c 100644 --- a/README.md +++ b/README.md @@ -1200,7 +1200,7 @@ Companion runtime helper: - `createHeartbeatLoop()` convenience helper that returns a bound `CompanionHeartbeatLoop` - optional `defaultSessionId` for canvas helper calls so `sessionId` can be omitted per call - `dispose()` lifecycle helper for unified runtime teardown - - stream passthrough helpers (`subscribeAgentStream/Typing/ContextWarning`, `waitForAgentStream/Typing/ContextWarning`) + - stream passthrough helpers (`subscribeEvents`, `subscribeAgentStream/Typing/ContextWarning`, `waitForAnyEvent`, `waitForAgentStream/Typing/ContextWarning`) - `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, failure observability (`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 adafbce..b605f61 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -607,6 +607,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-platform-generic-event-passthrough": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Added generic event passthroughs on platform clients (`subscribeEvents`, `waitForAnyEvent`) to match runtime event API coverage at the platform wrapper layer.", + "files_modified": [ + "src/companion/platformClients.ts", + "src/companion/platformClients.test.ts", + "README.md", + "docs/plans/state.json" + ], + "test_status": "pnpm test:run src/companion/platformClients.test.ts src/companion/runtimeClient.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 f235d4f..6f61148 100644 --- a/src/companion/platformClients.test.ts +++ b/src/companion/platformClients.test.ts @@ -28,9 +28,11 @@ function createRuntimeMock(): { subscribeAgentStream: ReturnType; subscribeAgentTyping: ReturnType; subscribeContextWarning: ReturnType; + subscribeEvents: ReturnType; waitForAgentStream: ReturnType; waitForAgentTyping: ReturnType; waitForContextWarning: ReturnType; + waitForAnyEvent: ReturnType; } { const connect = vi.fn(async () => undefined); const disconnect = vi.fn(() => undefined); @@ -59,9 +61,11 @@ function createRuntimeMock(): { const subscribeAgentStream = vi.fn(() => () => undefined); const subscribeAgentTyping = vi.fn(() => () => undefined); const subscribeContextWarning = vi.fn(() => () => undefined); + const subscribeEvents = vi.fn(() => () => undefined); const waitForAgentStream = vi.fn(async () => ({ token: 'streamed' })); const waitForAgentTyping = vi.fn(async () => ({ active: true })); const waitForContextWarning = vi.fn(async () => ({ thresholdPct: 75, estimatedPct: 90 })); + const waitForAnyEvent = vi.fn(async () => ({ event: 'agent.stream', data: { token: 'any' } })); const runtime = { connect, @@ -84,9 +88,11 @@ function createRuntimeMock(): { subscribeAgentStream, subscribeAgentTyping, subscribeContextWarning, + subscribeEvents, waitForAgentStream, waitForAgentTyping, waitForContextWarning, + waitForAnyEvent, } as unknown as CompanionRuntimeClient; return { @@ -111,9 +117,11 @@ function createRuntimeMock(): { subscribeAgentStream, subscribeAgentTyping, subscribeContextWarning, + subscribeEvents, waitForAgentStream, waitForAgentTyping, waitForContextWarning, + waitForAnyEvent, }; } @@ -180,26 +188,33 @@ describe('platform companion clients', () => { const streamHandler = vi.fn(); const typingHandler = vi.fn(); const warningHandler = vi.fn(); + const eventHandler = vi.fn(); const unsubscribeStream = client.subscribeAgentStream(streamHandler); const unsubscribeTyping = client.subscribeAgentTyping(typingHandler); const unsubscribeWarning = client.subscribeContextWarning(warningHandler); + const unsubscribeEvents = client.subscribeEvents(eventHandler); const awaited = await client.waitForAgentStream<{ token: string }>({ timeoutMs: 500 }); const waitedTyping = await client.waitForAgentTyping<{ active: boolean }>({ timeoutMs: 500 }); const waitedWarning = await client.waitForContextWarning<{ thresholdPct: number; estimatedPct: number }>({ timeoutMs: 500 }); + const waitedAny = await client.waitForAnyEvent<{ token: string }>(['agent.stream'], { timeoutMs: 500 }); expect(mock.subscribeAgentStream).toHaveBeenCalledWith(streamHandler); expect(mock.subscribeAgentTyping).toHaveBeenCalledWith(typingHandler); expect(mock.subscribeContextWarning).toHaveBeenCalledWith(warningHandler); + expect(mock.subscribeEvents).toHaveBeenCalledWith(eventHandler); expect(mock.waitForAgentStream).toHaveBeenCalledWith({ timeoutMs: 500 }); expect(mock.waitForAgentTyping).toHaveBeenCalledWith({ timeoutMs: 500 }); expect(mock.waitForContextWarning).toHaveBeenCalledWith({ timeoutMs: 500 }); + expect(mock.waitForAnyEvent).toHaveBeenCalledWith(['agent.stream'], { timeoutMs: 500 }); expect(awaited).toEqual({ token: 'streamed' }); expect(waitedTyping).toEqual({ active: true }); expect(waitedWarning).toEqual({ thresholdPct: 75, estimatedPct: 90 }); + expect(waitedAny).toEqual({ event: 'agent.stream', data: { token: 'any' } }); unsubscribeStream(); unsubscribeTyping(); unsubscribeWarning(); + unsubscribeEvents(); }); it('macOS client forwards canvas methods to runtime client', async () => { diff --git a/src/companion/platformClients.ts b/src/companion/platformClients.ts index 428b67c..808e9bb 100644 --- a/src/companion/platformClients.ts +++ b/src/companion/platformClients.ts @@ -1,4 +1,6 @@ import type { + CompanionEventEnvelope, + CompanionEventHandler, CanvasClearResult, CanvasDeleteResult, CanvasGetResult, @@ -245,6 +247,21 @@ export class MacOSCompanionClient { return this.runtime.waitForAgentStream(options); } + subscribeEvents(handler: CompanionEventHandler): () => void { + return this.runtime.subscribeEvents(handler); + } + + waitForAnyEvent( + eventNames: readonly string[], + options?: { + timeoutMs?: number; + predicate?: (event: string, data: TData) => boolean; + signal?: AbortSignal; + }, + ): Promise> { + return this.runtime.waitForAnyEvent(eventNames, options); + } + waitForAgentTyping(options?: { timeoutMs?: number; predicate?: CompanionEventPredicate; @@ -438,6 +455,21 @@ export class IOSCompanionClient { return this.runtime.waitForAgentStream(options); } + subscribeEvents(handler: CompanionEventHandler): () => void { + return this.runtime.subscribeEvents(handler); + } + + waitForAnyEvent( + eventNames: readonly string[], + options?: { + timeoutMs?: number; + predicate?: (event: string, data: TData) => boolean; + signal?: AbortSignal; + }, + ): Promise> { + return this.runtime.waitForAnyEvent(eventNames, options); + } + waitForAgentTyping(options?: { timeoutMs?: number; predicate?: CompanionEventPredicate; @@ -629,6 +661,21 @@ export class AndroidCompanionClient { return this.runtime.waitForAgentStream(options); } + subscribeEvents(handler: CompanionEventHandler): () => void { + return this.runtime.subscribeEvents(handler); + } + + waitForAnyEvent( + eventNames: readonly string[], + options?: { + timeoutMs?: number; + predicate?: (event: string, data: TData) => boolean; + signal?: AbortSignal; + }, + ): Promise> { + return this.runtime.waitForAnyEvent(eventNames, options); + } + waitForAgentTyping(options?: { timeoutMs?: number; predicate?: CompanionEventPredicate;