diff --git a/README.md b/README.md index f61db79..40ff2db 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 (`subscribeEvents`, `clearEventSubscriptions`, `listKnownEventNames`, `eventSubscriptionCount`, `subscribeAgentStream/Typing/ContextWarning`, `waitForAnyEvent`, `waitForAgentStream/Typing/ContextWarning`) + - stream passthrough helpers (`subscribeEvents`, `subscribeEvent`, `clearEventSubscriptions`, `listKnownEventNames`, `eventSubscriptionCount`, `subscribeAgentStream/Typing/ContextWarning`, `waitForEvent`, `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 01a9916..70a9247 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -686,6 +686,19 @@ ], "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" }, + "companion-platform-single-event-passthrough": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Added `subscribeEvent()` and `waitForEvent()` passthroughs on platform companion clients so wrappers expose full single-event subscription and waiting semantics from the runtime client.", + "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 cdf989b..f04e033 100644 --- a/src/companion/platformClients.test.ts +++ b/src/companion/platformClients.test.ts @@ -29,8 +29,10 @@ function createRuntimeMock(): { subscribeAgentTyping: ReturnType; subscribeContextWarning: ReturnType; subscribeEvents: ReturnType; + subscribeEvent: ReturnType; clearEventSubscriptions: ReturnType; listKnownEventNames: ReturnType; + waitForEvent: ReturnType; waitForAgentStream: ReturnType; waitForAgentTyping: ReturnType; waitForContextWarning: ReturnType; @@ -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 () => { diff --git a/src/companion/platformClients.ts b/src/companion/platformClients.ts index 36f5c68..8409996 100644 --- a/src/companion/platformClients.ts +++ b/src/companion/platformClients.ts @@ -252,6 +252,13 @@ export class MacOSCompanionClient { return this.runtime.subscribeEvents(handler); } + subscribeEvent( + eventName: CompanionEventName | string, + handler: CompanionTypedEventHandler, + ): () => 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( + eventName: CompanionEventName | string, + options?: { + timeoutMs?: number; + predicate?: CompanionEventPredicate; + signal?: AbortSignal; + }, + ): Promise { + return this.runtime.waitForEvent(eventName, options); + } + waitForAgentTyping(options?: { timeoutMs?: number; predicate?: CompanionEventPredicate; @@ -472,6 +490,13 @@ export class IOSCompanionClient { return this.runtime.subscribeEvents(handler); } + subscribeEvent( + eventName: CompanionEventName | string, + handler: CompanionTypedEventHandler, + ): () => 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( + eventName: CompanionEventName | string, + options?: { + timeoutMs?: number; + predicate?: CompanionEventPredicate; + signal?: AbortSignal; + }, + ): Promise { + return this.runtime.waitForEvent(eventName, options); + } + waitForAgentTyping(options?: { timeoutMs?: number; predicate?: CompanionEventPredicate; @@ -690,6 +726,13 @@ export class AndroidCompanionClient { return this.runtime.subscribeEvents(handler); } + subscribeEvent( + eventName: CompanionEventName | string, + handler: CompanionTypedEventHandler, + ): () => 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( + eventName: CompanionEventName | string, + options?: { + timeoutMs?: number; + predicate?: CompanionEventPredicate; + signal?: AbortSignal; + }, + ): Promise { + return this.runtime.waitForEvent(eventName, options); + } + waitForAgentTyping(options?: { timeoutMs?: number; predicate?: CompanionEventPredicate;