From 0a43abd5314e4d63ccb327399d049336f400a7bc Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 16 Feb 2026 19:08:13 -0800 Subject: [PATCH] feat(companion): add typed agent stream subscription helpers --- README.md | 2 +- docs/plans/state.json | 14 ++++++++++++++ src/companion/index.ts | 1 + src/companion/runtimeClient.test.ts | 28 ++++++++++++++++++++++++++++ src/companion/runtimeClient.ts | 18 ++++++++++++++++++ 5 files changed, 62 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6050550..fd28fd1 100644 --- a/README.md +++ b/README.md @@ -1190,7 +1190,7 @@ Methods: - `system.capabilities` returns gateway protocol and node policy snapshot. Companion runtime helper: -- `src/companion/runtimeClient.ts` provides a typed Node/WebSocket client for companion runtimes (macOS/iOS/Android workers) with wrappers for `node.register`, `node.capabilities.get`, `node.location.set/get`, `node.status.set`, `node.push_token.set`, `system.capabilities`, `system.nodes`, and canvas artifact RPCs (`canvas.put/get/list/delete/clear`), plus convenience helpers (`bootstrapNode`, optional `autoConnect`, `dispose()`) and event helpers (`subscribeEvents()`, `subscribeEvent()`, `waitForEvent()` with timeout/predicate/abort support, `clearEventSubscriptions()`). +- `src/companion/runtimeClient.ts` provides a typed Node/WebSocket client for companion runtimes (macOS/iOS/Android workers) with wrappers for `node.register`, `node.capabilities.get`, `node.location.set/get`, `node.status.set`, `node.push_token.set`, `system.capabilities`, `system.nodes`, and canvas artifact RPCs (`canvas.put/get/list/delete/clear`), plus convenience helpers (`bootstrapNode`, optional `autoConnect`, `dispose()`) and event helpers (`subscribeEvents()`, `subscribeEvent()`, `subscribeAgentStream()`, `subscribeAgentTyping()`, `waitForEvent()` with timeout/predicate/abort support, `clearEventSubscriptions()`). - `src/companion/platformClients.ts` provides platform-focused wrappers: - `MacOSCompanionClient` (`platform: "macos"`, APNs push registration) - `IOSCompanionClient` (`platform: "ios"`, APNs push registration) diff --git a/docs/plans/state.json b/docs/plans/state.json index 47ff4a5..1e59929 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -473,6 +473,20 @@ ], "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-runtime-typed-stream-subscriptions": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Added typed stream-event convenience subscriptions on `CompanionRuntimeClient` (`subscribeAgentStream`, `subscribeAgentTyping`) and exported canonical event-name constants.", + "files_modified": [ + "src/companion/runtimeClient.ts", + "src/companion/runtimeClient.test.ts", + "src/companion/index.ts", + "README.md", + "docs/plans/state.json" + ], + "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" + }, "browser-tools-activation-clarity": { "status": "completed", "date": "2026-02-17", diff --git a/src/companion/index.ts b/src/companion/index.ts index ce884cd..aa0bd1a 100644 --- a/src/companion/index.ts +++ b/src/companion/index.ts @@ -1,6 +1,7 @@ export { CompanionRuntimeClient, GatewayRpcError, + COMPANION_EVENT_NAMES, } from './runtimeClient.js'; export { MacOSCompanionClient, diff --git a/src/companion/runtimeClient.test.ts b/src/companion/runtimeClient.test.ts index f3e76c9..f911d35 100644 --- a/src/companion/runtimeClient.test.ts +++ b/src/companion/runtimeClient.test.ts @@ -196,6 +196,34 @@ describe('CompanionRuntimeClient', () => { expect(streamHandler).toHaveBeenCalledTimes(1); }); + it('supports subscribeAgentStream and subscribeAgentTyping helpers', () => { + const client = new CompanionRuntimeClient({ + url: 'ws://127.0.0.1:1', + }); + const streamHandler = vi.fn(); + const typingHandler = vi.fn(); + client.subscribeAgentStream(streamHandler); + client.subscribeAgentTyping(typingHandler); + + (client as unknown as { handleMessage: (raw: string) => void }).handleMessage( + JSON.stringify({ + id: 52, + event: 'agent.stream', + data: { token: 'x' }, + }), + ); + (client as unknown as { handleMessage: (raw: string) => void }).handleMessage( + JSON.stringify({ + id: 53, + event: 'agent.typing', + data: { active: true }, + }), + ); + + expect(streamHandler).toHaveBeenCalledWith({ token: 'x' }); + expect(typingHandler).toHaveBeenCalledWith({ active: true }); + }); + it('clears all event subscriptions', () => { const client = new CompanionRuntimeClient({ url: 'ws://127.0.0.1:1', diff --git a/src/companion/runtimeClient.ts b/src/companion/runtimeClient.ts index 2406c79..b662668 100644 --- a/src/companion/runtimeClient.ts +++ b/src/companion/runtimeClient.ts @@ -45,6 +45,12 @@ export type CompanionEventHandler = (event: string, data: unknown) => void; export type CompanionTypedEventHandler = (data: TData) => void; export type CompanionEventPredicate = (data: TData) => boolean; +export const COMPANION_EVENT_NAMES = { + agentStream: 'agent.stream', + agentTyping: 'agent.typing', + contextWarning: 'context_warning', +} as const; + export interface RegisterNodeInput { nodeId: string; role: string; @@ -385,6 +391,18 @@ export class CompanionRuntimeClient { }); } + subscribeAgentStream( + handler: CompanionTypedEventHandler, + ): () => void { + return this.subscribeEvent(COMPANION_EVENT_NAMES.agentStream, handler); + } + + subscribeAgentTyping( + handler: CompanionTypedEventHandler, + ): () => void { + return this.subscribeEvent(COMPANION_EVENT_NAMES.agentTyping, handler); + } + waitForEvent( eventName: string, options?: {