feat(companion): add platform single-event passthrough helpers

src/companion/platformClients.test.ts

@@ -29,8 +29,10 @@ function createRuntimeMock(): {
   subscribeAgentTyping: ReturnType<typeof vi.fn>;
   subscribeContextWarning: ReturnType<typeof vi.fn>;
   subscribeEvents: ReturnType<typeof vi.fn>;
+  subscribeEvent: ReturnType<typeof vi.fn>;
   clearEventSubscriptions: ReturnType<typeof vi.fn>;
   listKnownEventNames: ReturnType<typeof vi.fn>;
+  waitForEvent: ReturnType<typeof vi.fn>;
   waitForAgentStream: ReturnType<typeof vi.fn>;
   waitForAgentTyping: ReturnType<typeof vi.fn>;
   waitForContextWarning: ReturnType<typeof vi.fn>;
@@ -65,8 +67,10 @@ function createRuntimeMock(): {
   const subscribeAgentTyping = vi.fn(() => () => undefined);
   const subscribeContextWarning = vi.fn(() => () => undefined);
   const subscribeEvents = vi.fn(() => () => undefined);
+  const subscribeEvent = vi.fn(() => () => undefined);
   const clearEventSubscriptions = vi.fn(() => undefined);
   const listKnownEventNames = vi.fn(() => ['agent.stream', 'agent.typing', 'context_warning']);
+  const waitForEvent = vi.fn(async () => ({ token: 'evented' }));
   const waitForAgentStream = vi.fn(async () => ({ token: 'streamed' }));
   const waitForAgentTyping = vi.fn(async () => ({ active: true }));
   const waitForContextWarning = vi.fn(async () => ({ thresholdPct: 75, estimatedPct: 90 }));
@@ -95,8 +99,10 @@ function createRuntimeMock(): {
     subscribeAgentTyping,
     subscribeContextWarning,
     subscribeEvents,
+    subscribeEvent,
     clearEventSubscriptions,
     listKnownEventNames,
+    waitForEvent,
     waitForAgentStream,
     waitForAgentTyping,
     waitForContextWarning,
@@ -129,8 +135,10 @@ function createRuntimeMock(): {
     subscribeAgentTyping,
     subscribeContextWarning,
     subscribeEvents,
+    subscribeEvent,
     clearEventSubscriptions,
     listKnownEventNames,
+    waitForEvent,
     waitForAgentStream,
     waitForAgentTyping,
     waitForContextWarning,
@@ -203,11 +211,14 @@ describe('platform companion clients', () => {
     const typingHandler = vi.fn();
     const warningHandler = vi.fn();
     const eventHandler = vi.fn();
+    const streamEventHandler = vi.fn();
 
     const unsubscribeStream = client.subscribeAgentStream(streamHandler);
     const unsubscribeTyping = client.subscribeAgentTyping(typingHandler);
     const unsubscribeWarning = client.subscribeContextWarning(warningHandler);
     const unsubscribeEvents = client.subscribeEvents(eventHandler);
+    const unsubscribeEvent = client.subscribeEvent('agent.stream', streamEventHandler);
+    const waitedEvent = await client.waitForEvent<{ token: string }>('agent.stream', { timeoutMs: 500 });
     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 });
@@ -217,10 +228,13 @@ describe('platform companion clients', () => {
     expect(mock.subscribeAgentTyping).toHaveBeenCalledWith(typingHandler);
     expect(mock.subscribeContextWarning).toHaveBeenCalledWith(warningHandler);
     expect(mock.subscribeEvents).toHaveBeenCalledWith(eventHandler);
+    expect(mock.subscribeEvent).toHaveBeenCalledWith('agent.stream', streamEventHandler);
+    expect(mock.waitForEvent).toHaveBeenCalledWith('agent.stream', { timeoutMs: 500 });
     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(waitedEvent).toEqual({ token: 'evented' });
     expect(awaited).toEqual({ token: 'streamed' });
     expect(waitedTyping).toEqual({ active: true });
     expect(waitedWarning).toEqual({ thresholdPct: 75, estimatedPct: 90 });
@@ -229,6 +243,7 @@ describe('platform companion clients', () => {
     unsubscribeTyping();
     unsubscribeWarning();
     unsubscribeEvents();
+    unsubscribeEvent();
   });
 
   it('platform clearEventSubscriptions forwards to runtime client', async () => {

src/companion/platformClients.ts

@@ -252,6 +252,13 @@ export class MacOSCompanionClient {
     return this.runtime.subscribeEvents(handler);
   }
 
+  subscribeEvent<TData = unknown>(
+    eventName: CompanionEventName | string,
+    handler: CompanionTypedEventHandler<TData>,
+  ): () => void {
+    return this.runtime.subscribeEvent(eventName, handler);
+  }
+
   clearEventSubscriptions(): void {
     this.runtime.clearEventSubscriptions();
   }
@@ -275,6 +282,17 @@ export class MacOSCompanionClient {
     return this.runtime.waitForAnyEvent(eventNames, options);
   }
 
+  waitForEvent<TData = unknown>(
+    eventName: CompanionEventName | string,
+    options?: {
+      timeoutMs?: number;
+      predicate?: CompanionEventPredicate<TData>;
+      signal?: AbortSignal;
+    },
+  ): Promise<TData> {
+    return this.runtime.waitForEvent(eventName, options);
+  }
+
   waitForAgentTyping<TData = unknown>(options?: {
     timeoutMs?: number;
     predicate?: CompanionEventPredicate<TData>;
@@ -472,6 +490,13 @@ export class IOSCompanionClient {
     return this.runtime.subscribeEvents(handler);
   }
 
+  subscribeEvent<TData = unknown>(
+    eventName: CompanionEventName | string,
+    handler: CompanionTypedEventHandler<TData>,
+  ): () => void {
+    return this.runtime.subscribeEvent(eventName, handler);
+  }
+
   clearEventSubscriptions(): void {
     this.runtime.clearEventSubscriptions();
   }
@@ -495,6 +520,17 @@ export class IOSCompanionClient {
     return this.runtime.waitForAnyEvent(eventNames, options);
   }
 
+  waitForEvent<TData = unknown>(
+    eventName: CompanionEventName | string,
+    options?: {
+      timeoutMs?: number;
+      predicate?: CompanionEventPredicate<TData>;
+      signal?: AbortSignal;
+    },
+  ): Promise<TData> {
+    return this.runtime.waitForEvent(eventName, options);
+  }
+
   waitForAgentTyping<TData = unknown>(options?: {
     timeoutMs?: number;
     predicate?: CompanionEventPredicate<TData>;
@@ -690,6 +726,13 @@ export class AndroidCompanionClient {
     return this.runtime.subscribeEvents(handler);
   }
 
+  subscribeEvent<TData = unknown>(
+    eventName: CompanionEventName | string,
+    handler: CompanionTypedEventHandler<TData>,
+  ): () => void {
+    return this.runtime.subscribeEvent(eventName, handler);
+  }
+
   clearEventSubscriptions(): void {
     this.runtime.clearEventSubscriptions();
   }
@@ -713,6 +756,17 @@ export class AndroidCompanionClient {
     return this.runtime.waitForAnyEvent(eventNames, options);
   }
 
+  waitForEvent<TData = unknown>(
+    eventName: CompanionEventName | string,
+    options?: {
+      timeoutMs?: number;
+      predicate?: CompanionEventPredicate<TData>;
+      signal?: AbortSignal;
+    },
+  ): Promise<TData> {
+    return this.runtime.waitForEvent(eventName, options);
+  }
+
   waitForAgentTyping<TData = unknown>(options?: {
     timeoutMs?: number;
     predicate?: CompanionEventPredicate<TData>;