diff --git a/README.md b/README.md index b7bc379..a230645 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()`, `waitForIdle()` for pending-work drain synchronization) and event helpers (`subscribeEvents()`, `subscribeEvent()`, `subscribeAgentStream()`, `subscribeAgentTyping()`, `subscribeContextWarning()`, `waitForEvent()` with timeout/predicate/abort support, non-empty event-name validation, and deterministic teardown cancellation (including socket-close rejection), `waitForAnyEvent()` (with non-empty event-name-list validation), `waitForAgentStream()`, `waitForAgentTyping()`, `waitForContextWarning()`, `clearEventSubscriptions()`, `listKnownEventNames()`, `eventSubscriptionCount`) plus in-flight observability via `pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, and `getPendingWorkSnapshot()`. +- `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()`, `waitForIdle()` for pending-work drain synchronization) and event helpers (`subscribeEvents()`, `subscribeEvent()`, `subscribeAgentStream()`, `subscribeAgentTyping()`, `subscribeContextWarning()`, `waitForEvent()` with timeout/predicate/abort support, non-empty event-name validation, and deterministic teardown cancellation (including socket-close rejection), `waitForAnyEvent()` (with non-empty event-name-list validation), `waitForAgentStream()`, `waitForAgentTyping()`, `waitForContextWarning()`, `clearEventSubscriptions()`, `listKnownEventNames()`, `eventSubscriptionCount`) plus in-flight observability via `pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, and `getPendingWorkSnapshot()`. - `src/companion/platformClients.ts` provides platform-focused wrappers: - `MacOSCompanionClient` (`platform: "macos"`, APNs push registration) - `IOSCompanionClient` (`platform: "ios"`, APNs push registration) @@ -1201,7 +1201,7 @@ Companion runtime helper: - optional `defaultSessionId` for canvas helper calls so `sessionId` can be omitted per call - lifecycle passthroughs for connection state/teardown (`connected`, `dispose(code?, reason?)`) - stream passthrough helpers (`subscribeEvents`, `subscribeEvent`, `clearEventSubscriptions`, `listKnownEventNames`, `eventSubscriptionCount`, `subscribeAgentStream/Typing/ContextWarning`, `waitForEvent`, `waitForAnyEvent`, `waitForAgentStream/Typing/ContextWarning`) - - runtime observability/control passthroughs (`pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `getPendingWorkSnapshot()`, `connected`, `waitForIdle()`) + - runtime observability/control passthroughs (`pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, `getPendingWorkSnapshot()`, `connected`, `waitForIdle()`) - `src/companion/heartbeatLoop.ts` provides `CompanionHeartbeatLoop` for periodic heartbeat scheduling (`publishHeartbeat`) with start/stop safety, optional interval jitter (`jitterRatio`) to spread load (with safe normalization for invalid random samples), `tickNow()` for manual sends, success/error hooks, loop observability (`successCount`, `lastSuccessAt`, `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 7d5dff1..64656f8 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -1012,6 +1012,21 @@ ], "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" }, + "companion-runtime-idle-alias-observability": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Added runtime `idle` convenience alias (`!hasPendingWork`) with platform passthrough getters for clearer readiness checks in companion app code.", + "files_modified": [ + "src/companion/runtimeClient.ts", + "src/companion/runtimeClient.test.ts", + "src/companion/platformClients.ts", + "src/companion/platformClients.test.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/platformClients.test.ts b/src/companion/platformClients.test.ts index b8fab46..6e5e4cd 100644 --- a/src/companion/platformClients.test.ts +++ b/src/companion/platformClients.test.ts @@ -43,6 +43,7 @@ function createRuntimeMock(): { pendingRequestCount: number; pendingEventWaitCount: number; hasPendingWork: boolean; + idle: boolean; connected: boolean; } { const connect = vi.fn(async () => undefined); @@ -91,6 +92,7 @@ function createRuntimeMock(): { const pendingRequestCount = 2; const pendingEventWaitCount = 1; const hasPendingWork = true; + const idle = false; const connected = true; const runtime = { @@ -137,6 +139,9 @@ function createRuntimeMock(): { get hasPendingWork() { return hasPendingWork; }, + get idle() { + return idle; + }, get connected() { return connected; }, @@ -179,6 +184,7 @@ function createRuntimeMock(): { pendingRequestCount, pendingEventWaitCount, hasPendingWork, + idle, connected, }; } @@ -345,6 +351,13 @@ describe('platform companion clients', () => { expect(client.hasPendingWork).toBe(mock.hasPendingWork); }); + it('platform idle forwards runtime getter value', async () => { + const mock = createRuntimeMock(); + const client = new IOSCompanionClient({ runtime: mock.runtime, nodeId: 'ios-node' }); + + expect(client.idle).toBe(mock.idle); + }); + it('platform waitForIdle forwards options to runtime client', async () => { const mock = createRuntimeMock(); const client = new IOSCompanionClient({ runtime: mock.runtime, nodeId: 'ios-node' }); diff --git a/src/companion/platformClients.ts b/src/companion/platformClients.ts index 53c4fa4..43c218e 100644 --- a/src/companion/platformClients.ts +++ b/src/companion/platformClients.ts @@ -289,6 +289,10 @@ export class MacOSCompanionClient { return this.runtime.hasPendingWork; } + get idle(): boolean { + return this.runtime.idle; + } + getPendingWorkSnapshot(): PendingWorkSnapshot { return this.runtime.getPendingWorkSnapshot(); } @@ -551,6 +555,10 @@ export class IOSCompanionClient { return this.runtime.hasPendingWork; } + get idle(): boolean { + return this.runtime.idle; + } + getPendingWorkSnapshot(): PendingWorkSnapshot { return this.runtime.getPendingWorkSnapshot(); } @@ -811,6 +819,10 @@ export class AndroidCompanionClient { return this.runtime.hasPendingWork; } + get idle(): boolean { + return this.runtime.idle; + } + getPendingWorkSnapshot(): PendingWorkSnapshot { return this.runtime.getPendingWorkSnapshot(); } diff --git a/src/companion/runtimeClient.test.ts b/src/companion/runtimeClient.test.ts index 1dd01c4..5b70189 100644 --- a/src/companion/runtimeClient.test.ts +++ b/src/companion/runtimeClient.test.ts @@ -632,15 +632,18 @@ describe('CompanionRuntimeClient', () => { await client.connect(); expect(client.pendingRequestCount).toBe(0); expect(client.hasPendingWork).toBe(false); + expect(client.idle).toBe(true); const pending = client.call('system.capabilities'); expect(client.pendingRequestCount).toBe(1); expect(client.hasPendingWork).toBe(true); + expect(client.idle).toBe(false); client.disconnect(); await expect(pending).rejects.toThrow('Disconnected'); expect(client.pendingRequestCount).toBe(0); expect(client.hasPendingWork).toBe(false); + expect(client.idle).toBe(true); }); it('returns pending work snapshot', async () => { diff --git a/src/companion/runtimeClient.ts b/src/companion/runtimeClient.ts index bbfb313..c470feb 100644 --- a/src/companion/runtimeClient.ts +++ b/src/companion/runtimeClient.ts @@ -326,6 +326,10 @@ export class CompanionRuntimeClient { return this.pendingRequestCount > 0 || this.pendingEventWaitCount > 0; } + get idle(): boolean { + return !this.hasPendingWork; + } + getPendingWorkSnapshot(): PendingWorkSnapshot { return { pendingRequestCount: this.pendingRequestCount,