feat(companion): add generic platform event passthroughs

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

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",

src/companion/platformClients.test.ts

@@ -28,9 +28,11 @@ function createRuntimeMock(): {
   subscribeAgentStream: ReturnType<typeof vi.fn>;
   subscribeAgentTyping: ReturnType<typeof vi.fn>;
   subscribeContextWarning: ReturnType<typeof vi.fn>;
+  subscribeEvents: ReturnType<typeof vi.fn>;
   waitForAgentStream: ReturnType<typeof vi.fn>;
   waitForAgentTyping: ReturnType<typeof vi.fn>;
   waitForContextWarning: ReturnType<typeof vi.fn>;
+  waitForAnyEvent: ReturnType<typeof vi.fn>;
 } {
   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 () => {

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<TData = unknown>(
+    eventNames: readonly string[],
+    options?: {
+      timeoutMs?: number;
+      predicate?: (event: string, data: TData) => boolean;
+      signal?: AbortSignal;
+    },
+  ): Promise<CompanionEventEnvelope<TData>> {
+    return this.runtime.waitForAnyEvent(eventNames, options);
+  }
+
   waitForAgentTyping<TData = unknown>(options?: {
     timeoutMs?: number;
     predicate?: CompanionEventPredicate<TData>;
@@ -438,6 +455,21 @@ export class IOSCompanionClient {
     return this.runtime.waitForAgentStream(options);
   }
 
+  subscribeEvents(handler: CompanionEventHandler): () => void {
+    return this.runtime.subscribeEvents(handler);
+  }
+
+  waitForAnyEvent<TData = unknown>(
+    eventNames: readonly string[],
+    options?: {
+      timeoutMs?: number;
+      predicate?: (event: string, data: TData) => boolean;
+      signal?: AbortSignal;
+    },
+  ): Promise<CompanionEventEnvelope<TData>> {
+    return this.runtime.waitForAnyEvent(eventNames, options);
+  }
+
   waitForAgentTyping<TData = unknown>(options?: {
     timeoutMs?: number;
     predicate?: CompanionEventPredicate<TData>;
@@ -629,6 +661,21 @@ export class AndroidCompanionClient {
     return this.runtime.waitForAgentStream(options);
   }
 
+  subscribeEvents(handler: CompanionEventHandler): () => void {
+    return this.runtime.subscribeEvents(handler);
+  }
+
+  waitForAnyEvent<TData = unknown>(
+    eventNames: readonly string[],
+    options?: {
+      timeoutMs?: number;
+      predicate?: (event: string, data: TData) => boolean;
+      signal?: AbortSignal;
+    },
+  ): Promise<CompanionEventEnvelope<TData>> {
+    return this.runtime.waitForAnyEvent(eventNames, options);
+  }
+
   waitForAgentTyping<TData = unknown>(options?: {
     timeoutMs?: number;
     predicate?: CompanionEventPredicate<TData>;