From 95df7cd445ecd866dd82781f461d7c7bc4dffc4e Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 16 Feb 2026 23:28:54 -0800 Subject: [PATCH] feat(companion): allow platform disconnect code and reason --- README.md | 2 +- docs/plans/state.json | 14 ++++++++++++++ src/companion/platformClients.integration.test.ts | 12 +++++++++++- src/companion/platformClients.test.ts | 4 ++-- src/companion/platformClients.ts | 12 ++++++------ 5 files changed, 34 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5076da1..54bfe52 100644 --- a/README.md +++ b/README.md @@ -1199,7 +1199,7 @@ Companion runtime helper: - shared `publishHeartbeat()` helper for periodic `node.status.set` updates with safe defaults - `createHeartbeatLoop()` convenience helper that returns a bound `CompanionHeartbeatLoop` - optional `defaultSessionId` for canvas helper calls so `sessionId` can be omitted per call - - lifecycle passthroughs for connection state/teardown (`connected`, `dispose(code?, reason?)`) + - lifecycle passthroughs for connection state/teardown (`connected`, `disconnect(code?, reason?)`, `dispose(code?, reason?)`) - stream passthrough helpers (`subscribeEvents`, `subscribeEvent`, `clearEventSubscriptions`, `cancelPendingEventWaits`, `listKnownEventNames`, `eventSubscriptionCount`, `subscribeAgentStream/Typing/ContextWarning`, `waitForEvent`, `waitForAnyEvent`, `waitForAgentStream/Typing/ContextWarning`) - runtime observability/control passthroughs (`pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, `getPendingWorkSnapshot()`, `getEventSurfaceSnapshot()`, `getConnectionSnapshot()`, `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. diff --git a/docs/plans/state.json b/docs/plans/state.json index aad831a..21aa6b0 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -1210,6 +1210,20 @@ ], "test_status": "pnpm test:run src/companion/runtimeClient.test.ts src/companion/platformClients.test.ts src/companion/platformClients.integration.test.ts src/companion/heartbeatLoop.test.ts + pnpm typecheck passing" }, + "companion-platform-disconnect-params-parity": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Aligned platform wrappers with runtime lifecycle API by extending `disconnect()` to accept optional `code`/`reason` parameters, with unit/integration assertions confirming passthrough and snapshot metadata updates.", + "files_modified": [ + "src/companion/platformClients.ts", + "src/companion/platformClients.test.ts", + "src/companion/platformClients.integration.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/platformClients.integration.test.ts src/companion/heartbeatLoop.test.ts + pnpm typecheck passing" + }, "browser-tools-activation-clarity": { "status": "completed", "date": "2026-02-17", diff --git a/src/companion/platformClients.integration.test.ts b/src/companion/platformClients.integration.test.ts index 958c7b6..b1c018f 100644 --- a/src/companion/platformClients.integration.test.ts +++ b/src/companion/platformClients.integration.test.ts @@ -338,8 +338,18 @@ describe('platform clients integration', () => { expect(client.connected).toBe(false); await client.connect(); expect(client.connected).toBe(true); - client.disconnect(); + client.disconnect(4100, 'manual platform stop'); expect(client.connected).toBe(false); + expect(client.getConnectionSnapshot()).toEqual({ + connected: false, + eventSubscriptionCount: 0, + pendingRequestCount: 0, + pendingEventWaitCount: 0, + hasPendingWork: false, + idle: true, + lastDisconnectCode: 4100, + lastDisconnectReason: 'manual platform stop', + }); }); it('macOS companion wrapper registers and writes status with platform pinning', async () => { diff --git a/src/companion/platformClients.test.ts b/src/companion/platformClients.test.ts index 85d10c9..5dd65ac 100644 --- a/src/companion/platformClients.test.ts +++ b/src/companion/platformClients.test.ts @@ -225,14 +225,14 @@ describe('platform companion clients', () => { await client.setLocation({ latitude: 10, longitude: 20, source: 'manual' }); await client.registerPushToken({ token: 'a'.repeat(64), topic: 'dev.flynn.macos', environment: 'production' }); await client.listNodes(); - client.disconnect(); + client.disconnect(4100, 'manual stop'); expect(mock.connect).toHaveBeenCalledOnce(); expect(mock.registerNode).toHaveBeenCalledWith(expect.objectContaining({ nodeId: 'mac-node', role: 'companion' })); expect(mock.setNodeStatus).toHaveBeenCalledWith(expect.objectContaining({ platform: 'macos' })); expect(mock.setNodePushToken).toHaveBeenCalledWith(expect.objectContaining({ provider: 'apns', topic: 'dev.flynn.macos' })); expect(mock.listSystemNodes).toHaveBeenCalledWith({ platform: 'macos', role: 'companion' }); - expect(mock.disconnect).toHaveBeenCalledOnce(); + expect(mock.disconnect).toHaveBeenCalledWith(4100, 'manual stop'); }); it('iOS client uses ios platform status and APNs push', async () => { diff --git a/src/companion/platformClients.ts b/src/companion/platformClients.ts index aa1bfb1..f26a849 100644 --- a/src/companion/platformClients.ts +++ b/src/companion/platformClients.ts @@ -110,8 +110,8 @@ export class MacOSCompanionClient { return this.runtime.connected; } - disconnect(): void { - this.runtime.disconnect(); + disconnect(code?: number, reason?: string): void { + this.runtime.disconnect(code, reason); } dispose(code?: number, reason?: string): void { @@ -388,8 +388,8 @@ export class IOSCompanionClient { return this.runtime.connected; } - disconnect(): void { - this.runtime.disconnect(); + disconnect(code?: number, reason?: string): void { + this.runtime.disconnect(code, reason); } dispose(code?: number, reason?: string): void { @@ -666,8 +666,8 @@ export class AndroidCompanionClient { return this.runtime.connected; } - disconnect(): void { - this.runtime.disconnect(); + disconnect(code?: number, reason?: string): void { + this.runtime.disconnect(code, reason); } dispose(code?: number, reason?: string): void {