will/flynn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(companion): add direct disconnect metadata getters

Browse Source
This commit is contained in:
William Valentin
2026-02-16 23:32:50 -08:00
parent 6821e3779f
commit 809000b6c6
7 changed files with 83 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2 -2
View File
@@ -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 plus event-name/timeout validation and deterministic teardown cancellation including socket-close rejection, `waitForAnyEvent()` with event-list/timeout validation, `waitForAgentStream()`, `waitForAgentTyping()`, `waitForContextWarning()`, `clearEventSubscriptions()` returning cleared-subscription/cancelled-wait counts, `cancelPendingEventWaits()` returning cancelled waiter count, `listKnownEventNames()`, `eventSubscriptionCount`) plus in-flight observability via `pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, `getPendingWorkSnapshot()`, `getEventSurfaceSnapshot()`, and `getConnectionSnapshot()` (including `lastDisconnectCode`/`lastDisconnectReason`).
- `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 plus event-name/timeout validation and deterministic teardown cancellation including socket-close rejection, `waitForAnyEvent()` with event-list/timeout validation, `waitForAgentStream()`, `waitForAgentTyping()`, `waitForContextWarning()`, `clearEventSubscriptions()` returning cleared-subscription/cancelled-wait counts, `cancelPendingEventWaits()` returning cancelled waiter count, `listKnownEventNames()`, `eventSubscriptionCount`) plus in-flight observability via `pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, `lastDisconnectCode`, `lastDisconnectReason`, `getPendingWorkSnapshot()`, `getEventSurfaceSnapshot()`, and `getConnectionSnapshot()` (including disconnect metadata).
- `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`, `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()`)
- runtime observability/control passthroughs (`pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, `lastDisconnectCode`, `lastDisconnectReason`, `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.
## Canvas / A2UI Foundation
docs/plans/state.json
+17 -1
View File
@@ -1236,6 +1236,22 @@
],
"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-runtime-disconnect-metadata-direct-getters": {
"status": "completed",
"date": "2026-02-17",
"updated": "2026-02-17",
"summary": "Added direct runtime/platform observability getters for disconnect metadata (`lastDisconnectCode`, `lastDisconnectReason`) so companion callers can read lifecycle teardown details without building full connection snapshots.",
"files_modified": [
"src/companion/runtimeClient.ts",
"src/companion/runtimeClient.test.ts",
"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",
@@ -5034,7 +5050,7 @@
}
},
"overall_progress": {
"total_test_count": 1879,
"total_test_count": 1881,
"all_tests_passing": true,
"p0_completion": "3/3 (100%)",
"p1_completion": "4/4 (100%)",
src/companion/platformClients.integration.test.ts
+2
View File
@@ -340,6 +340,8 @@ describe('platform clients integration', () => {
expect(client.connected).toBe(true);
client.disconnect(4100, 'manual platform stop');
expect(client.connected).toBe(false);
expect(client.lastDisconnectCode).toBe(4100);
expect(client.lastDisconnectReason).toBe('manual platform stop');
expect(client.getConnectionSnapshot()).toEqual({
connected: false,
eventSubscriptionCount: 0,
src/companion/platformClients.test.ts
+20
View File
@@ -47,6 +47,8 @@ function createRuntimeMock(): {
pendingEventWaitCount: number;
hasPendingWork: boolean;
idle: boolean;
lastDisconnectCode: number | undefined;
lastDisconnectReason: string | undefined;
connected: boolean;
} {
const connect = vi.fn(async () => undefined);
@@ -112,6 +114,8 @@ function createRuntimeMock(): {
const pendingEventWaitCount = 1;
const hasPendingWork = true;
const idle = false;
const lastDisconnectCode = 1000;
const lastDisconnectReason = 'normal closure';
const connected = true;
const runtime = {
@@ -164,6 +168,12 @@ function createRuntimeMock(): {
get idle() {
return idle;
},
get lastDisconnectCode() {
return lastDisconnectCode;
},
get lastDisconnectReason() {
return lastDisconnectReason;
},
get connected() {
return connected;
},
@@ -210,6 +220,8 @@ function createRuntimeMock(): {
pendingEventWaitCount,
hasPendingWork,
idle,
lastDisconnectCode,
lastDisconnectReason,
connected,
};
}
@@ -394,6 +406,14 @@ describe('platform companion clients', () => {
expect(client.idle).toBe(mock.idle);
});
it('platform disconnect metadata getters forward runtime values', async () => {
const mock = createRuntimeMock();
const client = new IOSCompanionClient({ runtime: mock.runtime, nodeId: 'ios-node' });
expect(client.lastDisconnectCode).toBe(mock.lastDisconnectCode);
expect(client.lastDisconnectReason).toBe(mock.lastDisconnectReason);
});
it('platform waitForIdle forwards options to runtime client', async () => {
const mock = createRuntimeMock();
const client = new IOSCompanionClient({ runtime: mock.runtime, nodeId: 'ios-node' });
src/companion/platformClients.ts
+24
View File
@@ -300,6 +300,14 @@ export class MacOSCompanionClient {
return this.runtime.idle;
}
get lastDisconnectCode(): number | undefined {
return this.runtime.lastDisconnectCode;
}
get lastDisconnectReason(): string | undefined {
return this.runtime.lastDisconnectReason;
}
getPendingWorkSnapshot(): PendingWorkSnapshot {
return this.runtime.getPendingWorkSnapshot();
}
@@ -578,6 +586,14 @@ export class IOSCompanionClient {
return this.runtime.idle;
}
get lastDisconnectCode(): number | undefined {
return this.runtime.lastDisconnectCode;
}
get lastDisconnectReason(): string | undefined {
return this.runtime.lastDisconnectReason;
}
getPendingWorkSnapshot(): PendingWorkSnapshot {
return this.runtime.getPendingWorkSnapshot();
}
@@ -854,6 +870,14 @@ export class AndroidCompanionClient {
return this.runtime.idle;
}
get lastDisconnectCode(): number | undefined {
return this.runtime.lastDisconnectCode;
}
get lastDisconnectReason(): string | undefined {
return this.runtime.lastDisconnectReason;
}
getPendingWorkSnapshot(): PendingWorkSnapshot {
return this.runtime.getPendingWorkSnapshot();
}
src/companion/runtimeClient.test.ts
+2
View File
@@ -797,6 +797,8 @@ describe('CompanionRuntimeClient', () => {
lastDisconnectCode: 4100,
lastDisconnectReason: 'manual stop',
});
expect(client.lastDisconnectCode).toBe(4100);
expect(client.lastDisconnectReason).toBe('manual stop');
});
it('connection snapshot tracks transport close code and reason', async () => {
src/companion/runtimeClient.ts
+16 -8
View File
@@ -315,8 +315,8 @@ export class CompanionRuntimeClient {
private pending = new Map<number, PendingRequest>();
private readonly eventHandlers = new Set<CompanionEventHandler>();
private readonly pendingEventWaits = new Set<(error: Error) => void>();
private lastDisconnectCode: number | undefined;
private lastDisconnectReason: string | undefined;
private _lastDisconnectCode: number | undefined;
private _lastDisconnectReason: string | undefined;
constructor(options: CompanionRuntimeClientOptions) {
const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
@@ -354,6 +354,14 @@ export class CompanionRuntimeClient {
return !this.hasPendingWork;
}
get lastDisconnectCode(): number | undefined {
return this._lastDisconnectCode;
}
get lastDisconnectReason(): string | undefined {
return this._lastDisconnectReason;
}
getPendingWorkSnapshot(): PendingWorkSnapshot {
return {
pendingRequestCount: this.pendingRequestCount,
@@ -378,8 +386,8 @@ export class CompanionRuntimeClient {
pendingEventWaitCount: this.pendingEventWaitCount,
hasPendingWork: this.hasPendingWork,
idle: this.idle,
lastDisconnectCode: this.lastDisconnectCode,
lastDisconnectReason: this.lastDisconnectReason,
lastDisconnectCode: this._lastDisconnectCode,
lastDisconnectReason: this._lastDisconnectReason,
};
}
@@ -413,9 +421,9 @@ export class CompanionRuntimeClient {
this.ws.on('message', (raw) => this.handleMessage(raw.toString()));
this.ws.on('close', (code, reason) => {
if (this.ws === ws) {
this.lastDisconnectCode = code;
this._lastDisconnectCode = code;
const reasonText = reason?.toString().trim();
this.lastDisconnectReason = reasonText ? reasonText : undefined;
this._lastDisconnectReason = reasonText ? reasonText : undefined;
this.ws = null;
this.rejectAllPending(new Error('WebSocket closed'));
this.rejectEventWaits(new Error('WebSocket closed'));
@@ -454,8 +462,8 @@ export class CompanionRuntimeClient {
}
disconnect(code?: number, reason?: string): void {
this.lastDisconnectCode = code;
this.lastDisconnectReason = reason;
this._lastDisconnectCode = code;
this._lastDisconnectReason = reason;
if (!this.ws) {
this.rejectEventWaits(new Error('Disconnected'));
return;