feat(companion): support default canvas session in platform clients

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

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",

src/companion/index.ts

@@ -44,6 +44,9 @@ export type {
   SharedStatusInput,
   HeartbeatStatusInput,
   PlatformBootstrapResult,
+  PlatformPutCanvasArtifactInput,
+  PlatformGetCanvasArtifactInput,
+  PlatformDeleteCanvasArtifactInput,
 } from './platformClients.js';
 export type {
   HeartbeatPublisher,

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();

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)',
+    );
+  });
 });

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<PutCanvasArtifactInput, 'sessionId'> {
+  sessionId?: string;
+}
+
+export interface PlatformGetCanvasArtifactInput extends Omit<GetCanvasArtifactInput, 'sessionId'> {
+  sessionId?: string;
+}
+
+export interface PlatformDeleteCanvasArtifactInput extends Omit<DeleteCanvasArtifactInput, 'sessionId'> {
+  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<void> {
@@ -139,24 +154,45 @@ export class MacOSCompanionClient {
     return this.runtime.listSystemNodes({ platform: 'macos', role: this.role });
   }
 
-  putCanvasArtifact(input: PutCanvasArtifactInput): Promise<CanvasPutResult> {
+  putCanvasArtifact(input: PlatformPutCanvasArtifactInput): Promise<CanvasPutResult> {
-    return this.runtime.putCanvasArtifact(input);
+    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<CanvasGetResult> {
+  getCanvasArtifact(input: PlatformGetCanvasArtifactInput): Promise<CanvasGetResult> {
-    return this.runtime.getCanvasArtifact(input);
+    return this.runtime.getCanvasArtifact({
+      sessionId: this.resolveSessionId(input.sessionId),
+      artifactId: input.artifactId,
+    });
   }
 
-  listCanvasArtifacts(sessionId: string): Promise<CanvasListResult> {
+  listCanvasArtifacts(sessionId?: string): Promise<CanvasListResult> {
-    return this.runtime.listCanvasArtifacts(sessionId);
+    return this.runtime.listCanvasArtifacts(this.resolveSessionId(sessionId));
   }
 
-  deleteCanvasArtifact(input: DeleteCanvasArtifactInput): Promise<CanvasDeleteResult> {
+  deleteCanvasArtifact(input: PlatformDeleteCanvasArtifactInput): Promise<CanvasDeleteResult> {
-    return this.runtime.deleteCanvasArtifact(input);
+    return this.runtime.deleteCanvasArtifact({
+      sessionId: this.resolveSessionId(input.sessionId),
+      artifactId: input.artifactId,
+    });
   }
 
-  clearCanvasArtifacts(sessionId: string): Promise<CanvasClearResult> {
+  clearCanvasArtifacts(sessionId?: string): Promise<CanvasClearResult> {
-    return this.runtime.clearCanvasArtifacts(sessionId);
+    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<void> {
@@ -248,24 +286,45 @@ export class IOSCompanionClient {
     return this.runtime.listSystemNodes({ platform: 'ios', role: this.role });
   }
 
-  putCanvasArtifact(input: PutCanvasArtifactInput): Promise<CanvasPutResult> {
+  putCanvasArtifact(input: PlatformPutCanvasArtifactInput): Promise<CanvasPutResult> {
-    return this.runtime.putCanvasArtifact(input);
+    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<CanvasGetResult> {
+  getCanvasArtifact(input: PlatformGetCanvasArtifactInput): Promise<CanvasGetResult> {
-    return this.runtime.getCanvasArtifact(input);
+    return this.runtime.getCanvasArtifact({
+      sessionId: this.resolveSessionId(input.sessionId),
+      artifactId: input.artifactId,
+    });
   }
 
-  listCanvasArtifacts(sessionId: string): Promise<CanvasListResult> {
+  listCanvasArtifacts(sessionId?: string): Promise<CanvasListResult> {
-    return this.runtime.listCanvasArtifacts(sessionId);
+    return this.runtime.listCanvasArtifacts(this.resolveSessionId(sessionId));
   }
 
-  deleteCanvasArtifact(input: DeleteCanvasArtifactInput): Promise<CanvasDeleteResult> {
+  deleteCanvasArtifact(input: PlatformDeleteCanvasArtifactInput): Promise<CanvasDeleteResult> {
-    return this.runtime.deleteCanvasArtifact(input);
+    return this.runtime.deleteCanvasArtifact({
+      sessionId: this.resolveSessionId(input.sessionId),
+      artifactId: input.artifactId,
+    });
   }
 
-  clearCanvasArtifacts(sessionId: string): Promise<CanvasClearResult> {
+  clearCanvasArtifacts(sessionId?: string): Promise<CanvasClearResult> {
-    return this.runtime.clearCanvasArtifacts(sessionId);
+    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<void> {
@@ -355,23 +416,44 @@ export class AndroidCompanionClient {
     return this.runtime.listSystemNodes({ platform: 'android', role: this.role });
   }
 
-  putCanvasArtifact(input: PutCanvasArtifactInput): Promise<CanvasPutResult> {
+  putCanvasArtifact(input: PlatformPutCanvasArtifactInput): Promise<CanvasPutResult> {
-    return this.runtime.putCanvasArtifact(input);
+    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<CanvasGetResult> {
+  getCanvasArtifact(input: PlatformGetCanvasArtifactInput): Promise<CanvasGetResult> {
-    return this.runtime.getCanvasArtifact(input);
+    return this.runtime.getCanvasArtifact({
+      sessionId: this.resolveSessionId(input.sessionId),
+      artifactId: input.artifactId,
+    });
   }
 
-  listCanvasArtifacts(sessionId: string): Promise<CanvasListResult> {
+  listCanvasArtifacts(sessionId?: string): Promise<CanvasListResult> {
-    return this.runtime.listCanvasArtifacts(sessionId);
+    return this.runtime.listCanvasArtifacts(this.resolveSessionId(sessionId));
   }
 
-  deleteCanvasArtifact(input: DeleteCanvasArtifactInput): Promise<CanvasDeleteResult> {
+  deleteCanvasArtifact(input: PlatformDeleteCanvasArtifactInput): Promise<CanvasDeleteResult> {
-    return this.runtime.deleteCanvasArtifact(input);
+    return this.runtime.deleteCanvasArtifact({
+      sessionId: this.resolveSessionId(input.sessionId),
+      artifactId: input.artifactId,
+    });
   }
 
-  clearCanvasArtifacts(sessionId: string): Promise<CanvasClearResult> {
+  clearCanvasArtifacts(sessionId?: string): Promise<CanvasClearResult> {
-    return this.runtime.clearCanvasArtifacts(sessionId);
+    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;
   }
 }