From a76e3e03dc5c7fd6d19c05843b642ee6b879c65d Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 16 Feb 2026 19:24:54 -0800 Subject: [PATCH] feat(companion): complete platform stream helper parity --- README.md | 2 +- docs/plans/state.json | 13 +++++ src/companion/platformClients.test.ts | 34 ++++++++++- src/companion/platformClients.ts | 84 +++++++++++++++++++++++++++ 4 files changed, 130 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5ecf1b8..d49994d 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()`, `waitForAgentStream()`) + - stream passthrough helpers (`subscribeAgentStream/Typing/ContextWarning`, `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 c9981a0..ac2cfa3 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -567,6 +567,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-stream-helper-parity": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Extended platform wrapper event parity by adding passthroughs for typing/context warning stream subscriptions and wait helpers alongside existing stream-token helpers.", + "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 8e5f8ab..f235d4f 100644 --- a/src/companion/platformClients.test.ts +++ b/src/companion/platformClients.test.ts @@ -26,7 +26,11 @@ function createRuntimeMock(): { deleteCanvasArtifact: ReturnType; clearCanvasArtifacts: ReturnType; subscribeAgentStream: ReturnType; + subscribeAgentTyping: ReturnType; + subscribeContextWarning: ReturnType; waitForAgentStream: ReturnType; + waitForAgentTyping: ReturnType; + waitForContextWarning: ReturnType; } { const connect = vi.fn(async () => undefined); const disconnect = vi.fn(() => undefined); @@ -53,7 +57,11 @@ function createRuntimeMock(): { const deleteCanvasArtifact = vi.fn(async () => ({ deleted: true })); const clearCanvasArtifacts = vi.fn(async () => ({ cleared: 1 })); const subscribeAgentStream = vi.fn(() => () => undefined); + const subscribeAgentTyping = vi.fn(() => () => undefined); + const subscribeContextWarning = 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 runtime = { connect, @@ -74,7 +82,11 @@ function createRuntimeMock(): { deleteCanvasArtifact, clearCanvasArtifacts, subscribeAgentStream, + subscribeAgentTyping, + subscribeContextWarning, waitForAgentStream, + waitForAgentTyping, + waitForContextWarning, } as unknown as CompanionRuntimeClient; return { @@ -97,7 +109,11 @@ function createRuntimeMock(): { deleteCanvasArtifact, clearCanvasArtifacts, subscribeAgentStream, + subscribeAgentTyping, + subscribeContextWarning, waitForAgentStream, + waitForAgentTyping, + waitForContextWarning, }; } @@ -162,14 +178,28 @@ describe('platform companion clients', () => { const mock = createRuntimeMock(); const client = new AndroidCompanionClient({ runtime: mock.runtime, nodeId: 'android-node' }); const streamHandler = vi.fn(); + const typingHandler = vi.fn(); + const warningHandler = vi.fn(); - const unsubscribe = client.subscribeAgentStream(streamHandler); + const unsubscribeStream = client.subscribeAgentStream(streamHandler); + const unsubscribeTyping = client.subscribeAgentTyping(typingHandler); + const unsubscribeWarning = client.subscribeContextWarning(warningHandler); 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 }); expect(mock.subscribeAgentStream).toHaveBeenCalledWith(streamHandler); + expect(mock.subscribeAgentTyping).toHaveBeenCalledWith(typingHandler); + expect(mock.subscribeContextWarning).toHaveBeenCalledWith(warningHandler); expect(mock.waitForAgentStream).toHaveBeenCalledWith({ timeoutMs: 500 }); + expect(mock.waitForAgentTyping).toHaveBeenCalledWith({ timeoutMs: 500 }); + expect(mock.waitForContextWarning).toHaveBeenCalledWith({ timeoutMs: 500 }); expect(awaited).toEqual({ token: 'streamed' }); - unsubscribe(); + expect(waitedTyping).toEqual({ active: true }); + expect(waitedWarning).toEqual({ thresholdPct: 75, estimatedPct: 90 }); + unsubscribeStream(); + unsubscribeTyping(); + unsubscribeWarning(); }); it('macOS client forwards canvas methods to runtime client', async () => { diff --git a/src/companion/platformClients.ts b/src/companion/platformClients.ts index 0ebb515..428b67c 100644 --- a/src/companion/platformClients.ts +++ b/src/companion/platformClients.ts @@ -225,6 +225,18 @@ export class MacOSCompanionClient { return this.runtime.subscribeAgentStream(handler); } + subscribeAgentTyping( + handler: CompanionTypedEventHandler, + ): () => void { + return this.runtime.subscribeAgentTyping(handler); + } + + subscribeContextWarning( + handler: CompanionTypedEventHandler, + ): () => void { + return this.runtime.subscribeContextWarning(handler); + } + waitForAgentStream(options?: { timeoutMs?: number; predicate?: CompanionEventPredicate; @@ -233,6 +245,22 @@ export class MacOSCompanionClient { return this.runtime.waitForAgentStream(options); } + waitForAgentTyping(options?: { + timeoutMs?: number; + predicate?: CompanionEventPredicate; + signal?: AbortSignal; + }): Promise { + return this.runtime.waitForAgentTyping(options); + } + + waitForContextWarning(options?: { + timeoutMs?: number; + predicate?: CompanionEventPredicate; + signal?: AbortSignal; + }): Promise { + return this.runtime.waitForContextWarning(options); + } + private resolveSessionId(sessionId?: string): string { const resolved = sessionId ?? this.defaultSessionId; if (!resolved) { @@ -390,6 +418,18 @@ export class IOSCompanionClient { return this.runtime.subscribeAgentStream(handler); } + subscribeAgentTyping( + handler: CompanionTypedEventHandler, + ): () => void { + return this.runtime.subscribeAgentTyping(handler); + } + + subscribeContextWarning( + handler: CompanionTypedEventHandler, + ): () => void { + return this.runtime.subscribeContextWarning(handler); + } + waitForAgentStream(options?: { timeoutMs?: number; predicate?: CompanionEventPredicate; @@ -398,6 +438,22 @@ export class IOSCompanionClient { return this.runtime.waitForAgentStream(options); } + waitForAgentTyping(options?: { + timeoutMs?: number; + predicate?: CompanionEventPredicate; + signal?: AbortSignal; + }): Promise { + return this.runtime.waitForAgentTyping(options); + } + + waitForContextWarning(options?: { + timeoutMs?: number; + predicate?: CompanionEventPredicate; + signal?: AbortSignal; + }): Promise { + return this.runtime.waitForContextWarning(options); + } + private resolveSessionId(sessionId?: string): string { const resolved = sessionId ?? this.defaultSessionId; if (!resolved) { @@ -553,6 +609,18 @@ export class AndroidCompanionClient { return this.runtime.subscribeAgentStream(handler); } + subscribeAgentTyping( + handler: CompanionTypedEventHandler, + ): () => void { + return this.runtime.subscribeAgentTyping(handler); + } + + subscribeContextWarning( + handler: CompanionTypedEventHandler, + ): () => void { + return this.runtime.subscribeContextWarning(handler); + } + waitForAgentStream(options?: { timeoutMs?: number; predicate?: CompanionEventPredicate; @@ -561,6 +629,22 @@ export class AndroidCompanionClient { return this.runtime.waitForAgentStream(options); } + waitForAgentTyping(options?: { + timeoutMs?: number; + predicate?: CompanionEventPredicate; + signal?: AbortSignal; + }): Promise { + return this.runtime.waitForAgentTyping(options); + } + + waitForContextWarning(options?: { + timeoutMs?: number; + predicate?: CompanionEventPredicate; + signal?: AbortSignal; + }): Promise { + return this.runtime.waitForContextWarning(options); + } + private resolveSessionId(sessionId?: string): string { const resolved = sessionId ?? this.defaultSessionId; if (!resolved) {