feat(companion): return clearEventSubscriptions result counts

src/companion/index.ts

@@ -16,6 +16,7 @@ export type {
   PendingWorkSnapshot,
   EventSurfaceSnapshot,
   ConnectionSnapshot,
+  ClearEventSubscriptionsResult,
   CompanionEventHandler,
   CompanionTypedEventHandler,
   CompanionEventName,

src/companion/platformClients.test.ts

@@ -78,7 +78,7 @@ function createRuntimeMock(): {
   const subscribeContextWarning = vi.fn(() => () => undefined);
   const subscribeEvents = vi.fn(() => () => undefined);
   const subscribeEvent = vi.fn(() => () => undefined);
-  const clearEventSubscriptions = vi.fn(() => undefined);
+  const clearEventSubscriptions = vi.fn(() => ({ clearedSubscriptions: 1, cancelledWaits: 0 }));
   const cancelPendingEventWaits = vi.fn(() => 1);
   const listKnownEventNames = vi.fn(() => ['agent.stream', 'agent.typing', 'context_warning']);
   const waitForEvent = vi.fn(async () => ({ token: 'evented' }));
@@ -331,9 +331,10 @@ describe('platform companion clients', () => {
     const mock = createRuntimeMock();
     const client = new IOSCompanionClient({ runtime: mock.runtime, nodeId: 'ios-node' });
 
-    client.clearEventSubscriptions();
+    const result = client.clearEventSubscriptions();
 
     expect(mock.clearEventSubscriptions).toHaveBeenCalledOnce();
+    expect(result).toEqual({ clearedSubscriptions: 1, cancelledWaits: 0 });
   });
 
   it('platform cancelPendingEventWaits forwards to runtime client', async () => {

src/companion/platformClients.ts

@@ -1,6 +1,7 @@
 import type {
   CompanionEventName,
   CompanionEventEnvelope,
+  ClearEventSubscriptionsResult,
   EventSurfaceSnapshot,
   ConnectionSnapshot,
   CompanionEventHandler,
@@ -267,8 +268,8 @@ export class MacOSCompanionClient {
     return this.runtime.subscribeEvent(eventName, handler);
   }
 
-  clearEventSubscriptions(): void {
-    this.runtime.clearEventSubscriptions();
+  clearEventSubscriptions(): ClearEventSubscriptionsResult {
+    return this.runtime.clearEventSubscriptions();
   }
 
   cancelPendingEventWaits(reason?: string): number {
@@ -545,8 +546,8 @@ export class IOSCompanionClient {
     return this.runtime.subscribeEvent(eventName, handler);
   }
 
-  clearEventSubscriptions(): void {
-    this.runtime.clearEventSubscriptions();
+  clearEventSubscriptions(): ClearEventSubscriptionsResult {
+    return this.runtime.clearEventSubscriptions();
   }
 
   cancelPendingEventWaits(reason?: string): number {
@@ -821,8 +822,8 @@ export class AndroidCompanionClient {
     return this.runtime.subscribeEvent(eventName, handler);
   }
 
-  clearEventSubscriptions(): void {
-    this.runtime.clearEventSubscriptions();
+  clearEventSubscriptions(): ClearEventSubscriptionsResult {
+    return this.runtime.clearEventSubscriptions();
   }
 
   cancelPendingEventWaits(reason?: string): number {

src/companion/runtimeClient.test.ts

@@ -267,7 +267,7 @@ describe('CompanionRuntimeClient', () => {
     const handlerB = vi.fn();
     client.subscribeEvents(handlerA);
     client.subscribeEvent('agent.stream', handlerB);
-    client.clearEventSubscriptions();
+    const clearResult = client.clearEventSubscriptions();
 
     (client as unknown as { handleMessage: (raw: string) => void }).handleMessage(
       JSON.stringify({
@@ -279,6 +279,10 @@ describe('CompanionRuntimeClient', () => {
 
     expect(handlerA).not.toHaveBeenCalled();
     expect(handlerB).not.toHaveBeenCalled();
+    expect(clearResult).toEqual({
+      clearedSubscriptions: 2,
+      cancelledWaits: 0,
+    });
   });
 
   it('dispose clears subscriptions and is safe to call repeatedly', () => {
@@ -385,7 +389,10 @@ describe('CompanionRuntimeClient', () => {
     const awaited = expect(
       client.waitForEvent('agent.stream', { timeoutMs: 10_000 }),
     ).rejects.toThrow('Event subscriptions cleared');
-    client.clearEventSubscriptions();
+    expect(client.clearEventSubscriptions()).toEqual({
+      clearedSubscriptions: 1,
+      cancelledWaits: 1,
+    });
     await awaited;
   });
 

src/companion/runtimeClient.ts

@@ -68,6 +68,11 @@ export interface ConnectionSnapshot {
   idle: boolean;
 }
 
+export interface ClearEventSubscriptionsResult {
+  clearedSubscriptions: number;
+  cancelledWaits: number;
+}
+
 export type CompanionEventHandler = (event: string, data: unknown) => void;
 export type CompanionTypedEventHandler<TData = unknown> = (data: TData) => void;
 export type CompanionEventPredicate<TData = unknown> = (data: TData) => boolean;
@@ -464,9 +469,14 @@ export class CompanionRuntimeClient {
     };
   }
 
-  clearEventSubscriptions(): void {
+  clearEventSubscriptions(): ClearEventSubscriptionsResult {
+    const clearedSubscriptions = this.eventHandlers.size;
     this.eventHandlers.clear();
-    this.rejectEventWaits(new Error('Event subscriptions cleared'));
+    const cancelledWaits = this.rejectEventWaits(new Error('Event subscriptions cleared'));
+    return {
+      clearedSubscriptions,
+      cancelledWaits,
+    };
   }
 
   cancelPendingEventWaits(reason = 'Event waits cancelled'): number {