feat(cli): support custom WebSocket query params in collaboration config (SD-2543) (#2799)

* feat(cli): support custom WebSocket query params in collaboration config

SD-2543: Adds an optional `params` field to the CLI collaboration config,
forwarded as query parameters on the y-websocket URL and as `parameters`
on the Hocuspocus provider. Validates that values are strings and rejects
the reserved `token` key (set automatically from `tokenEnv`). The field
is omitted from the public collaboration summary since it may contain
identifying metadata.

* fix(cli): preserve params on session rehydration and fingerprint nested fields

Follow-up to SD-2543 addressing two correctness bugs surfaced in review:

1. normalizeWebSocketProfile in context.ts dropped params when rehydrating
   persisted collab metadata from disk, so the reconnect reopened without
   the user-supplied query params.

2. profileToFingerprint in session-pool.ts used JSON.stringify's array
   replacer as a sort helper, but that filter applies at every depth and
   silently stripped nested objects. Two profiles differing only in params
   hashed identically, causing the pool to reuse the wrong session.

Replaces the fingerprint helper with a recursive stable-stringify and adds
params validation/preservation to the context normalizer. Adds mocked
runtime tests covering the y-websocket and hocuspocus provider handoffs,
the params+token merge order, and fingerprint key-order independence.

* docs(document-engine): document collaboration params field

Adds a "Forward custom WebSocket query parameters" section to the SDK guide
covering the new `params` field: scope (y-websocket and Hocuspocus only,
not Liveblocks), the string-only shape, and the reserved `token` key.

* fix(cli): handle object schemas without explicit properties

The CLI's JSON schema validator crashed on `type: 'object'` schemas that
omitted the `properties` map (e.g. schemas that only declare
`additionalProperties`). `Object.entries(schema.properties)` threw
`Cannot convert undefined or null to object` before reaching the
downstream parser.

Default `schema.properties` to `{}` in both the request and response
validators so these schemas pass through to the layer that can actually
validate their contents. Exposed by SD-2543's collaboration.params
schema, which is the first schema in the repo to use this shape.

Author: caio-pizzol

apps/cli/src/__tests__/lib/context.test.ts

@@ -102,6 +102,68 @@ describe('normalizeContextMetadata', () => {
       expect(result.collaboration).toBeUndefined();
     });
 
+    test('preserves websocket params on rehydration', () => {
+      const metadata = makeMetadata({
+        sessionType: 'collab',
+        collaboration: {
+          providerType: 'y-websocket',
+          url: 'ws://localhost:4000',
+          documentId: 'test-doc',
+          params: { customAttributions: 'agent_id:abc', region: 'us-east-1' },
+        } as any,
+      });
+      const result = normalizeContextMetadata(metadata);
+      expect(result.sessionType).toBe('collab');
+      expect(result.collaboration).toMatchObject({
+        params: { customAttributions: 'agent_id:abc', region: 'us-east-1' },
+      });
+    });
+
+    test('preserves websocket profile when params is absent', () => {
+      const metadata = makeMetadata({
+        sessionType: 'collab',
+        collaboration: {
+          providerType: 'y-websocket',
+          url: 'ws://localhost:4000',
+          documentId: 'test-doc',
+        },
+      });
+      const result = normalizeContextMetadata(metadata);
+      expect(result.sessionType).toBe('collab');
+      expect(result.collaboration).toBeDefined();
+      expect((result.collaboration as any).params).toBeUndefined();
+    });
+
+    test('rejects websocket profile with non-object params', () => {
+      const metadata = makeMetadata({
+        sessionType: 'collab',
+        collaboration: {
+          providerType: 'y-websocket',
+          url: 'ws://localhost:4000',
+          documentId: 'test-doc',
+          params: 'not-an-object',
+        } as any,
+      });
+      const result = normalizeContextMetadata(metadata);
+      expect(result.sessionType).toBe('local');
+      expect(result.collaboration).toBeUndefined();
+    });
+
+    test('rejects websocket profile with non-string param values', () => {
+      const metadata = makeMetadata({
+        sessionType: 'collab',
+        collaboration: {
+          providerType: 'y-websocket',
+          url: 'ws://localhost:4000',
+          documentId: 'test-doc',
+          params: { count: 42 },
+        } as any,
+      });
+      const result = normalizeContextMetadata(metadata);
+      expect(result.sessionType).toBe('local');
+      expect(result.collaboration).toBeUndefined();
+    });
+
     test('preserves Liveblocks collab profile with publicApiKey', () => {
       const metadata = makeMetadata({
         sessionType: 'collab',

apps/cli/src/__tests__/lib/validate-type-spec.test.ts

@@ -142,3 +142,23 @@ describe('doc.find select schema — accepts canonical and shorthand forms', ()
     expect(() => validateValueAgainstTypeSpec({ type: 'text' }, schema, 'select')).toThrow(CliError);
   });
 });
+
+describe('validateValueAgainstTypeSpec – object without explicit properties', () => {
+  // type: 'object' schemas that use additionalProperties (or nothing at all)
+  // must not crash the validator when `properties` is absent.
+  const schema = {
+    type: 'object',
+    additionalProperties: { type: 'string' },
+  } as unknown as CliTypeSpec;
+
+  test('accepts any object when properties is absent', () => {
+    expect(() => validateValueAgainstTypeSpec({ foo: 'bar' }, schema, 'params')).not.toThrow();
+    expect(() => validateValueAgainstTypeSpec({}, schema, 'params')).not.toThrow();
+  });
+
+  test('still rejects non-object values', () => {
+    expect(() => validateValueAgainstTypeSpec('nope', schema, 'params')).toThrow(CliError);
+    expect(() => validateValueAgainstTypeSpec(42, schema, 'params')).toThrow(CliError);
+    expect(() => validateValueAgainstTypeSpec(null, schema, 'params')).toThrow(CliError);
+  });
+});

apps/cli/src/cli/operation-params.ts

@@ -987,6 +987,12 @@ const CLI_ONLY_METADATA: Record<CliOnlyOperationId, CliOperationMetadata> = {
                   description: 'Room/document identifier. Defaults to session ID if omitted.',
                 },
                 tokenEnv: { type: 'string', description: 'Environment variable name containing the auth token.' },
+                params: {
+                  type: 'object',
+                  description:
+                    'Custom query parameters appended to the WebSocket URL. Values must be strings. Reserved keys: token.',
+                  additionalProperties: { type: 'string' },
+                },
                 syncTimeoutMs: { type: 'number', description: 'Max time (ms) to wait for initial sync.' },
                 onMissing: {
                   type: 'string',

apps/cli/src/host/session-pool.test.ts

@@ -119,6 +119,31 @@ describe('InMemorySessionPool', () => {
       expect(openCollabCalls.length).toBe(2);
     });
 
+    test('discards collab session when params differ', async () => {
+      const { pool, openCollabCalls } = createPool();
+
+      const profileA = { ...COLLAB_PROFILE, params: { region: 'us' } };
+      await pool.acquire('s1', { ...COLLAB_METADATA, collaboration: profileA }, TEST_IO);
+
+      const profileB = { ...COLLAB_PROFILE, params: { region: 'eu' } };
+      await pool.acquire('s1', { ...COLLAB_METADATA, collaboration: profileB }, TEST_IO);
+
+      expect(openCollabCalls.length).toBe(2);
+    });
+
+    test('reuses collab session when params match (key order independent)', async () => {
+      const { pool, openCollabCalls } = createPool();
+
+      const profileA = { ...COLLAB_PROFILE, params: { region: 'us', tier: 'pro' } };
+      const first = await pool.acquire('s1', { ...COLLAB_METADATA, collaboration: profileA }, TEST_IO);
+      first.dispose();
+
+      const profileB = { ...COLLAB_PROFILE, params: { tier: 'pro', region: 'us' } };
+      await pool.acquire('s1', { ...COLLAB_METADATA, collaboration: profileB }, TEST_IO);
+
+      expect(openCollabCalls.length).toBe(1);
+    });
+
     test('reuses collab session when fingerprint matches', async () => {
       const { pool, openCollabCalls } = createPool();
 

apps/cli/src/host/session-pool.ts

@@ -74,12 +74,24 @@ export interface SessionPool {
 }
 
 // ---------------------------------------------------------------------------
-// Collab fingerprint (preserved from old pool)
+// Collab fingerprint
 // ---------------------------------------------------------------------------
 
+// Stable stringify that sorts keys at every depth so nested objects (e.g.
+// `params`) contribute to the hash. JSON.stringify's array replacer is a
+// single global allow-list applied at all depths, which silently strips
+// unlisted nested keys.
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const entries = Object.keys(value as Record<string, unknown>)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${stableStringify((value as Record<string, unknown>)[key])}`);
+  return `{${entries.join(',')}}`;
+}
+
 function profileToFingerprint(profile: CollaborationProfile): string {
-  const sortedJson = JSON.stringify(profile, Object.keys(profile).sort());
-  return createHash('sha256').update(sortedJson).digest('hex');
+  return createHash('sha256').update(stableStringify(profile)).digest('hex');
 }
 
 // ---------------------------------------------------------------------------

apps/cli/src/lib/collaboration/__tests__/parse.test.ts

@@ -80,12 +80,65 @@ describe('parseCollaborationInput — websocket', () => {
     );
   });
 
-  test('rejects params field', () => {
-    expect(() => parseCollaborationInput({ providerType: 'y-websocket', url: 'ws://x', params: {} })).toThrow(
-      'collaboration.params is not supported',
+  test('accepts params field with string values', () => {
+    const input = parseCollaborationInput({
+      providerType: 'y-websocket',
+      url: 'ws://x',
+      params: { customAttributions: 'agent_id:abc', region: 'us-east-1' },
+    });
+    expect(input).toMatchObject({
+      params: { customAttributions: 'agent_id:abc', region: 'us-east-1' },
+    });
+  });
+
+  test('omits params when not provided', () => {
+    const input = parseCollaborationInput({
+      providerType: 'y-websocket',
+      url: 'ws://x',
+    }) as WebSocketCollaborationInput;
+    expect(input.params).toBeUndefined();
+  });
+
+  test('rejects non-object params', () => {
+    expect(() =>
+      parseCollaborationInput({ providerType: 'y-websocket', url: 'ws://x', params: 'not-an-object' }),
+    ).toThrow('collaboration.params must be an object of string key-value pairs');
+    expect(() => parseCollaborationInput({ providerType: 'y-websocket', url: 'ws://x', params: ['a', 'b'] })).toThrow(
+      'collaboration.params must be an object of string key-value pairs',
     );
   });
 
+  test('rejects non-string param values', () => {
+    expect(() =>
+      parseCollaborationInput({ providerType: 'y-websocket', url: 'ws://x', params: { count: 42 } }),
+    ).toThrow('collaboration.params.count must be a string');
+    expect(() =>
+      parseCollaborationInput({ providerType: 'y-websocket', url: 'ws://x', params: { flag: true } }),
+    ).toThrow('collaboration.params.flag must be a string');
+    expect(() =>
+      parseCollaborationInput({ providerType: 'y-websocket', url: 'ws://x', params: { nested: { a: 'b' } } }),
+    ).toThrow('collaboration.params.nested must be a string');
+  });
+
+  test('rejects reserved token key in params', () => {
+    expect(() =>
+      parseCollaborationInput({
+        providerType: 'y-websocket',
+        url: 'ws://x',
+        params: { token: 'secret' },
+      }),
+    ).toThrow('collaboration.params.token is reserved');
+  });
+
+  test('accepts params with hocuspocus provider', () => {
+    const input = parseCollaborationInput({
+      providerType: 'hocuspocus',
+      url: 'ws://x',
+      params: { workspaceId: 'ws_123' },
+    });
+    expect(input).toMatchObject({ providerType: 'hocuspocus', params: { workspaceId: 'ws_123' } });
+  });
+
   test('rejects Liveblocks-only fields on websocket providers', () => {
     expect(() => parseCollaborationInput({ providerType: 'y-websocket', url: 'ws://x', roomId: 'room' })).toThrow(
       'collaboration.roomId is not supported for websocket',
@@ -236,6 +289,17 @@ describe('parseCollaborationInput — liveblocks', () => {
     ).toThrow('collaboration.headers is not supported');
   });
 
+  test('rejects params field', () => {
+    expect(() =>
+      parseCollaborationInput({
+        providerType: 'liveblocks',
+        roomId: 'room',
+        publicApiKey: 'pk_xxx',
+        params: { foo: 'bar' },
+      }),
+    ).toThrow('collaboration.params is not supported for Liveblocks');
+  });
+
   test('rejects unknown keys', () => {
     expect(() =>
       parseCollaborationInput({
@@ -272,6 +336,19 @@ describe('resolveCollaborationProfile', () => {
     expect(profile.documentId).toBe('explicit-doc');
   });
 
+  test('websocket: params pass through to profile', () => {
+    const input = parseCollaborationInput({
+      providerType: 'y-websocket',
+      url: 'ws://localhost:4000',
+      params: { customAttributions: 'agent_id:abc' },
+    });
+    const profile = resolveCollaborationProfile(input, 'session');
+    expect(profile).toMatchObject({
+      providerType: 'y-websocket',
+      params: { customAttributions: 'agent_id:abc' },
+    });
+  });
+
   test('liveblocks: roomId maps to documentId directly', () => {
     const input = parseCollaborationInput({
       providerType: 'liveblocks',
@@ -302,6 +379,16 @@ describe('toPublicCollaborationSummary', () => {
     });
   });
 
+  test('websocket: omits params (may contain identifying metadata)', () => {
+    const summary = toPublicCollaborationSummary({
+      providerType: 'y-websocket',
+      url: 'ws://localhost:4000',
+      documentId: 'doc-1',
+      params: { userId: 'secret-user-id' },
+    });
+    expect(summary).not.toHaveProperty('params');
+  });
+
   test('liveblocks: excludes auth config', () => {
     const summary = toPublicCollaborationSummary({
       providerType: 'liveblocks',