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

feat(companion): add disconnect metadata to connection snapshots

Browse Source
This commit is contained in:
William Valentin
2026-02-16 23:28:01 -08:00
parent 44916fc9b2
commit 44b686da9c
6 changed files with 104 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1 -1
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()`.
- `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/platformClients.ts` provides platform-focused wrappers:
- `MacOSCompanionClient` (`platform: "macos"`, APNs push registration)
- `IOSCompanionClient` (`platform: "ios"`, APNs push registration)
docs/plans/state.json
+15
View File
@@ -1195,6 +1195,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-connection-snapshot-disconnect-metadata": {
"status": "completed",
"date": "2026-02-17",
"updated": "2026-02-17",
"summary": "Extended runtime/platform connection snapshots with disconnect metadata (`lastDisconnectCode`, `lastDisconnectReason`) captured on both manual `disconnect()` and transport close events for clearer companion lifecycle diagnostics.",
"files_modified": [
"src/companion/runtimeClient.ts",
"src/companion/runtimeClient.test.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",
src/companion/platformClients.integration.test.ts
+6
View File
@@ -271,6 +271,8 @@ describe('platform clients integration', () => {
pendingEventWaitCount: 0,
hasPendingWork: false,
idle: true,
lastDisconnectCode: undefined,
lastDisconnectReason: undefined,
});
const unsubscribe = client.subscribeEvents(() => undefined);
@@ -283,6 +285,8 @@ describe('platform clients integration', () => {
pendingEventWaitCount: 1,
hasPendingWork: true,
idle: false,
lastDisconnectCode: undefined,
lastDisconnectReason: undefined,
});
client.clearEventSubscriptions();
@@ -294,6 +298,8 @@ describe('platform clients integration', () => {
pendingEventWaitCount: 0,
hasPendingWork: false,
idle: true,
lastDisconnectCode: undefined,
lastDisconnectReason: undefined,
});
unsubscribe();
src/companion/platformClients.test.ts
+4
View File
@@ -100,6 +100,8 @@ function createRuntimeMock(): {
pendingEventWaitCount: 1,
hasPendingWork: true,
idle: false,
lastDisconnectCode: 1000,
lastDisconnectReason: 'normal closure',
}));
const waitForAgentStream = vi.fn(async () => ({ token: 'streamed' }));
const waitForAgentTyping = vi.fn(async () => ({ active: true }));
@@ -443,6 +445,8 @@ describe('platform companion clients', () => {
pendingEventWaitCount: 1,
hasPendingWork: true,
idle: false,
lastDisconnectCode: 1000,
lastDisconnectReason: 'normal closure',
});
});
src/companion/runtimeClient.test.ts
+66
View File
@@ -762,6 +762,8 @@ describe('CompanionRuntimeClient', () => {
pendingEventWaitCount: 1,
hasPendingWork: true,
idle: false,
lastDisconnectCode: undefined,
lastDisconnectReason: undefined,
});
client.clearEventSubscriptions();
@@ -773,6 +775,70 @@ describe('CompanionRuntimeClient', () => {
pendingEventWaitCount: 0,
hasPendingWork: false,
idle: true,
lastDisconnectCode: undefined,
lastDisconnectReason: undefined,
});
});
it('connection snapshot tracks manual disconnect code and reason', () => {
const client = new CompanionRuntimeClient({
url: 'ws://127.0.0.1:1',
});
client.disconnect(4100, 'manual stop');
expect(client.getConnectionSnapshot()).toEqual({
connected: false,
eventSubscriptionCount: 0,
pendingRequestCount: 0,
pendingEventWaitCount: 0,
hasPendingWork: false,
idle: true,
lastDisconnectCode: 4100,
lastDisconnectReason: 'manual stop',
});
});
it('connection snapshot tracks transport close code and reason', async () => {
class FakeWebSocket extends EventEmitter {
readyState: number = WebSocket.CONNECTING;
constructor() {
super();
queueMicrotask(() => {
this.readyState = WebSocket.OPEN;
this.emit('open');
});
}
send(_payload: string, callback?: (error?: Error) => void): void {
callback?.();
}
close(_code?: number, _reason?: string): void {
this.readyState = WebSocket.CLOSED;
this.emit('close', 4001, Buffer.from('transport closed'));
}
}
const client = new CompanionRuntimeClient({
url: 'ws://127.0.0.1:1',
websocketFactory: () => new FakeWebSocket() as unknown as WebSocket,
});
await client.connect();
const ws = (client as unknown as { ws: WebSocket | null }).ws;
ws?.close();
expect(client.getConnectionSnapshot()).toEqual({
connected: false,
eventSubscriptionCount: 0,
pendingRequestCount: 0,
pendingEventWaitCount: 0,
hasPendingWork: false,
idle: true,
lastDisconnectCode: 4001,
lastDisconnectReason: 'transport closed',
});
});
src/companion/runtimeClient.ts
+12 -1
View File
@@ -66,6 +66,8 @@ export interface ConnectionSnapshot {
pendingEventWaitCount: number;
hasPendingWork: boolean;
idle: boolean;
lastDisconnectCode?: number;
lastDisconnectReason?: string;
}
export interface ClearEventSubscriptionsResult {
@@ -313,6 +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;
constructor(options: CompanionRuntimeClientOptions) {
const requestTimeoutMs = options.requestTimeoutMs ?? 15_000;
@@ -374,6 +378,8 @@ export class CompanionRuntimeClient {
pendingEventWaitCount: this.pendingEventWaitCount,
hasPendingWork: this.hasPendingWork,
idle: this.idle,
lastDisconnectCode: this.lastDisconnectCode,
lastDisconnectReason: this.lastDisconnectReason,
};
}
@@ -405,7 +411,10 @@ export class CompanionRuntimeClient {
settled = true;
this.ws = ws;
this.ws.on('message', (raw) => this.handleMessage(raw.toString()));
this.ws.on('close', () => {
this.ws.on('close', (code, reason) => {
this.lastDisconnectCode = code;
const reasonText = reason?.toString().trim();
this.lastDisconnectReason = reasonText ? reasonText : undefined;
if (this.ws === ws) {
this.ws = null;
}
@@ -445,6 +454,8 @@ export class CompanionRuntimeClient {
}
disconnect(code?: number, reason?: string): void {
this.lastDisconnectCode = code;
this.lastDisconnectReason = reason;
if (!this.ws) {
this.rejectEventWaits(new Error('Disconnected'));
return;