diff --git a/README.md b/README.md index 94e23b4..434a5f4 100644 --- a/README.md +++ b/README.md @@ -1197,6 +1197,7 @@ Companion runtime helper: - `AndroidCompanionClient` (`platform: "android"`, FCM push registration) - shared `bootstrap()` helper (`register` + `getCapabilities`) for startup handshakes - shared `publishHeartbeat()` helper for periodic `node.status.set` updates with safe defaults + - optional `defaultSessionId` for canvas helper calls so `sessionId` can be omitted per call - `src/companion/heartbeatLoop.ts` provides `CompanionHeartbeatLoop` for periodic heartbeat scheduling (`publishHeartbeat`) with start/stop safety and error hooks. ## Canvas / A2UI Foundation diff --git a/docs/plans/state.json b/docs/plans/state.json index 8aaba63..b805496 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -271,6 +271,21 @@ ], "test_status": "pnpm test:run src/companion/heartbeatLoop.test.ts src/companion/platformClients.test.ts + pnpm typecheck passing" }, + "companion-platform-default-canvas-session": { + "status": "completed", + "date": "2026-02-17", + "updated": "2026-02-17", + "summary": "Added optional `defaultSessionId` to platform companion clients so canvas helper methods can omit per-call session IDs, while preserving explicit-session overrides and clear validation errors when no session is available.", + "files_modified": [ + "src/companion/platformClients.ts", + "src/companion/platformClients.test.ts", + "src/companion/platformClients.integration.test.ts", + "src/companion/index.ts", + "README.md", + "docs/plans/state.json" + ], + "test_status": "pnpm test:run src/companion/platformClients.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 0bc7c37..e68af16 100644 --- a/src/companion/index.ts +++ b/src/companion/index.ts @@ -44,6 +44,9 @@ export type { SharedStatusInput, HeartbeatStatusInput, PlatformBootstrapResult, + PlatformPutCanvasArtifactInput, + PlatformGetCanvasArtifactInput, + PlatformDeleteCanvasArtifactInput, } from './platformClients.js'; export type { HeartbeatPublisher, diff --git a/src/companion/platformClients.integration.test.ts b/src/companion/platformClients.integration.test.ts index f4521dc..37f0c5e 100644 --- a/src/companion/platformClients.integration.test.ts +++ b/src/companion/platformClients.integration.test.ts @@ -196,15 +196,17 @@ describe('platform clients integration', () => { } const runtime = createRuntime(); - const client = new MacOSCompanionClient({ runtime, nodeId: 'macos-canvas-e2e' }); + const client = new MacOSCompanionClient({ + runtime, + nodeId: 'macos-canvas-e2e', + defaultSessionId: 'ws:platform-canvas-e2e', + }); await client.connect(); try { await client.register(); - const sessionId = 'ws:platform-canvas-e2e'; const put = await client.putCanvasArtifact({ - sessionId, artifactId: 'mac-art-1', type: 'note', content: { text: 'hello from platform wrapper' }, @@ -212,16 +214,16 @@ describe('platform clients integration', () => { expect(put.upserted).toBe(true); expect(put.artifact.id).toBe('mac-art-1'); - const list = await client.listCanvasArtifacts(sessionId); + const list = await client.listCanvasArtifacts(); expect(list.artifacts.some((artifact) => artifact.id === 'mac-art-1')).toBe(true); - const get = await client.getCanvasArtifact({ sessionId, artifactId: 'mac-art-1' }); + const get = await client.getCanvasArtifact({ artifactId: 'mac-art-1' }); expect(get.artifact.id).toBe('mac-art-1'); - const del = await client.deleteCanvasArtifact({ sessionId, artifactId: 'mac-art-1' }); + const del = await client.deleteCanvasArtifact({ artifactId: 'mac-art-1' }); expect(del.deleted).toBe(true); - const clear = await client.clearCanvasArtifacts(sessionId); + const clear = await client.clearCanvasArtifacts(); expect(clear.cleared).toBe(0); } finally { client.disconnect(); diff --git a/src/companion/platformClients.test.ts b/src/companion/platformClients.test.ts index 78e248a..4807d05 100644 --- a/src/companion/platformClients.test.ts +++ b/src/companion/platformClients.test.ts @@ -183,4 +183,44 @@ describe('platform companion clients', () => { }), ); }); + + it('uses defaultSessionId for canvas operations when sessionId is omitted', async () => { + const mock = createRuntimeMock(); + const client = new IOSCompanionClient({ + runtime: mock.runtime, + nodeId: 'ios-node', + defaultSessionId: 'ws:default-canvas', + }); + + await client.putCanvasArtifact({ + type: 'markdown', + content: { body: 'default session' }, + }); + await client.listCanvasArtifacts(); + await client.getCanvasArtifact({ artifactId: 'a1' }); + await client.deleteCanvasArtifact({ artifactId: 'a1' }); + await client.clearCanvasArtifacts(); + + expect(mock.putCanvasArtifact).toHaveBeenCalledWith({ + sessionId: 'ws:default-canvas', + type: 'markdown', + content: { body: 'default session' }, + artifactId: undefined, + title: undefined, + metadata: undefined, + }); + expect(mock.listCanvasArtifacts).toHaveBeenCalledWith('ws:default-canvas'); + expect(mock.getCanvasArtifact).toHaveBeenCalledWith({ sessionId: 'ws:default-canvas', artifactId: 'a1' }); + expect(mock.deleteCanvasArtifact).toHaveBeenCalledWith({ sessionId: 'ws:default-canvas', artifactId: 'a1' }); + expect(mock.clearCanvasArtifacts).toHaveBeenCalledWith('ws:default-canvas'); + }); + + it('throws when canvas sessionId is missing and no defaultSessionId is configured', async () => { + const mock = createRuntimeMock(); + const client = new MacOSCompanionClient({ runtime: mock.runtime, nodeId: 'mac-node' }); + + expect(() => client.listCanvasArtifacts()).toThrow( + 'sessionId is required (provide one or configure defaultSessionId)', + ); + }); }); diff --git a/src/companion/platformClients.ts b/src/companion/platformClients.ts index d784444..9ab0bcd 100644 --- a/src/companion/platformClients.ts +++ b/src/companion/platformClients.ts @@ -25,6 +25,7 @@ export interface PlatformClientOptions { role?: string; capabilities?: string[]; protocolVersion?: number; + defaultSessionId?: string; } export interface RegisterPushTokenInput { @@ -51,12 +52,25 @@ export interface PlatformBootstrapResult { capabilities: NodeCapabilitiesResult; } +export interface PlatformPutCanvasArtifactInput extends Omit { + sessionId?: string; +} + +export interface PlatformGetCanvasArtifactInput extends Omit { + sessionId?: string; +} + +export interface PlatformDeleteCanvasArtifactInput extends Omit { + sessionId?: string; +} + export class MacOSCompanionClient { private readonly runtime: CompanionRuntimeClient; private readonly nodeId: string; private readonly role: string; private readonly capabilities: string[]; private readonly protocolVersion?: number; + private readonly defaultSessionId?: string; constructor(options: PlatformClientOptions) { this.runtime = options.runtime; @@ -64,6 +78,7 @@ export class MacOSCompanionClient { this.role = options.role ?? 'companion'; this.capabilities = options.capabilities ?? ['ui.canvas', 'node.location.write', 'node.push.register']; this.protocolVersion = options.protocolVersion; + this.defaultSessionId = options.defaultSessionId; } connect(): Promise { @@ -139,24 +154,45 @@ export class MacOSCompanionClient { return this.runtime.listSystemNodes({ platform: 'macos', role: this.role }); } - putCanvasArtifact(input: PutCanvasArtifactInput): Promise { - return this.runtime.putCanvasArtifact(input); + putCanvasArtifact(input: PlatformPutCanvasArtifactInput): Promise { + return this.runtime.putCanvasArtifact({ + sessionId: this.resolveSessionId(input.sessionId), + artifactId: input.artifactId, + type: input.type, + title: input.title, + content: input.content, + metadata: input.metadata, + }); } - getCanvasArtifact(input: GetCanvasArtifactInput): Promise { - return this.runtime.getCanvasArtifact(input); + getCanvasArtifact(input: PlatformGetCanvasArtifactInput): Promise { + return this.runtime.getCanvasArtifact({ + sessionId: this.resolveSessionId(input.sessionId), + artifactId: input.artifactId, + }); } - listCanvasArtifacts(sessionId: string): Promise { - return this.runtime.listCanvasArtifacts(sessionId); + listCanvasArtifacts(sessionId?: string): Promise { + return this.runtime.listCanvasArtifacts(this.resolveSessionId(sessionId)); } - deleteCanvasArtifact(input: DeleteCanvasArtifactInput): Promise { - return this.runtime.deleteCanvasArtifact(input); + deleteCanvasArtifact(input: PlatformDeleteCanvasArtifactInput): Promise { + return this.runtime.deleteCanvasArtifact({ + sessionId: this.resolveSessionId(input.sessionId), + artifactId: input.artifactId, + }); } - clearCanvasArtifacts(sessionId: string): Promise { - return this.runtime.clearCanvasArtifacts(sessionId); + clearCanvasArtifacts(sessionId?: string): Promise { + return this.runtime.clearCanvasArtifacts(this.resolveSessionId(sessionId)); + } + + private resolveSessionId(sessionId?: string): string { + const resolved = sessionId ?? this.defaultSessionId; + if (!resolved) { + throw new Error('sessionId is required (provide one or configure defaultSessionId)'); + } + return resolved; } } @@ -166,6 +202,7 @@ export class IOSCompanionClient { private readonly role: string; private readonly capabilities: string[]; private readonly protocolVersion?: number; + private readonly defaultSessionId?: string; constructor(options: PlatformClientOptions) { this.runtime = options.runtime; @@ -173,6 +210,7 @@ export class IOSCompanionClient { this.role = options.role ?? 'companion'; this.capabilities = options.capabilities ?? ['node.location.write', 'node.push.register']; this.protocolVersion = options.protocolVersion; + this.defaultSessionId = options.defaultSessionId; } connect(): Promise { @@ -248,24 +286,45 @@ export class IOSCompanionClient { return this.runtime.listSystemNodes({ platform: 'ios', role: this.role }); } - putCanvasArtifact(input: PutCanvasArtifactInput): Promise { - return this.runtime.putCanvasArtifact(input); + putCanvasArtifact(input: PlatformPutCanvasArtifactInput): Promise { + return this.runtime.putCanvasArtifact({ + sessionId: this.resolveSessionId(input.sessionId), + artifactId: input.artifactId, + type: input.type, + title: input.title, + content: input.content, + metadata: input.metadata, + }); } - getCanvasArtifact(input: GetCanvasArtifactInput): Promise { - return this.runtime.getCanvasArtifact(input); + getCanvasArtifact(input: PlatformGetCanvasArtifactInput): Promise { + return this.runtime.getCanvasArtifact({ + sessionId: this.resolveSessionId(input.sessionId), + artifactId: input.artifactId, + }); } - listCanvasArtifacts(sessionId: string): Promise { - return this.runtime.listCanvasArtifacts(sessionId); + listCanvasArtifacts(sessionId?: string): Promise { + return this.runtime.listCanvasArtifacts(this.resolveSessionId(sessionId)); } - deleteCanvasArtifact(input: DeleteCanvasArtifactInput): Promise { - return this.runtime.deleteCanvasArtifact(input); + deleteCanvasArtifact(input: PlatformDeleteCanvasArtifactInput): Promise { + return this.runtime.deleteCanvasArtifact({ + sessionId: this.resolveSessionId(input.sessionId), + artifactId: input.artifactId, + }); } - clearCanvasArtifacts(sessionId: string): Promise { - return this.runtime.clearCanvasArtifacts(sessionId); + clearCanvasArtifacts(sessionId?: string): Promise { + return this.runtime.clearCanvasArtifacts(this.resolveSessionId(sessionId)); + } + + private resolveSessionId(sessionId?: string): string { + const resolved = sessionId ?? this.defaultSessionId; + if (!resolved) { + throw new Error('sessionId is required (provide one or configure defaultSessionId)'); + } + return resolved; } } @@ -275,6 +334,7 @@ export class AndroidCompanionClient { private readonly role: string; private readonly capabilities: string[]; private readonly protocolVersion?: number; + private readonly defaultSessionId?: string; constructor(options: PlatformClientOptions) { this.runtime = options.runtime; @@ -282,6 +342,7 @@ export class AndroidCompanionClient { this.role = options.role ?? 'companion'; this.capabilities = options.capabilities ?? ['node.location.write', 'node.push.register']; this.protocolVersion = options.protocolVersion; + this.defaultSessionId = options.defaultSessionId; } connect(): Promise { @@ -355,23 +416,44 @@ export class AndroidCompanionClient { return this.runtime.listSystemNodes({ platform: 'android', role: this.role }); } - putCanvasArtifact(input: PutCanvasArtifactInput): Promise { - return this.runtime.putCanvasArtifact(input); + putCanvasArtifact(input: PlatformPutCanvasArtifactInput): Promise { + return this.runtime.putCanvasArtifact({ + sessionId: this.resolveSessionId(input.sessionId), + artifactId: input.artifactId, + type: input.type, + title: input.title, + content: input.content, + metadata: input.metadata, + }); } - getCanvasArtifact(input: GetCanvasArtifactInput): Promise { - return this.runtime.getCanvasArtifact(input); + getCanvasArtifact(input: PlatformGetCanvasArtifactInput): Promise { + return this.runtime.getCanvasArtifact({ + sessionId: this.resolveSessionId(input.sessionId), + artifactId: input.artifactId, + }); } - listCanvasArtifacts(sessionId: string): Promise { - return this.runtime.listCanvasArtifacts(sessionId); + listCanvasArtifacts(sessionId?: string): Promise { + return this.runtime.listCanvasArtifacts(this.resolveSessionId(sessionId)); } - deleteCanvasArtifact(input: DeleteCanvasArtifactInput): Promise { - return this.runtime.deleteCanvasArtifact(input); + deleteCanvasArtifact(input: PlatformDeleteCanvasArtifactInput): Promise { + return this.runtime.deleteCanvasArtifact({ + sessionId: this.resolveSessionId(input.sessionId), + artifactId: input.artifactId, + }); } - clearCanvasArtifacts(sessionId: string): Promise { - return this.runtime.clearCanvasArtifacts(sessionId); + clearCanvasArtifacts(sessionId?: string): Promise { + return this.runtime.clearCanvasArtifacts(this.resolveSessionId(sessionId)); + } + + private resolveSessionId(sessionId?: string): string { + const resolved = sessionId ?? this.defaultSessionId; + if (!resolved) { + throw new Error('sessionId is required (provide one or configure defaultSessionId)'); + } + return resolved; } }