fix(core): pass enforceStrictCapabilities as getter; document registerCapabilities/extension ordering

ExtensionHandle now reads enforceStrictCapabilities via a getter (matching
the existing _getPeerExtensionSettings pattern), so a future setter on the
host would be observed. JSDoc on extension() notes that a later
registerCapabilities({extensions:{id:...}}) overwrites the wire value while
handle.settings reflects the original call.

Author: felixweinberger

packages/client/src/client/client.ts

@@ -320,6 +320,10 @@ export class Client extends Protocol<ClientContext> {
      * during `initialize`. Must be called before {@linkcode connect}. After connecting,
      * {@linkcode ExtensionHandle.getPeerSettings | handle.getPeerSettings()} returns the server's
      * `capabilities.extensions[id]` blob (validated against `peerSchema` if provided).
+     *
+     * Note: a later {@linkcode registerCapabilities} call that includes `extensions[id]` will
+     * overwrite the wire value declared here; the returned handle's `settings` reflects what
+     * was passed to this call, not subsequent overwrites.
      */
     public extension<L extends JSONObject>(id: string, settings: L): ExtensionHandle<L, JSONObject, ClientContext>;
     public extension<L extends JSONObject, P extends AnySchema>(
@@ -344,7 +348,7 @@ export class Client extends Protocol<ClientContext> {
             id,
             settings,
             () => this._serverCapabilities?.extensions?.[id],
-            this._enforceStrictCapabilities,
+            () => this._enforceStrictCapabilities,
             opts?.peerSchema
         );
     }

packages/core/src/shared/extensionHandle.ts

@@ -67,7 +67,7 @@ export class ExtensionHandle<Local extends JSONObject, Peer = JSONObject, Contex
         /** The local settings object advertised in `capabilities.extensions[id]`. */
         public readonly settings: Local,
         private readonly _getPeerExtensionSettings: () => JSONObject | undefined,
-        private readonly _enforceStrictCapabilities: boolean,
+        private readonly _getEnforceStrictCapabilities: () => boolean,
         private readonly _peerSchema?: AnySchema
     ) {}
 
@@ -150,7 +150,7 @@ export class ExtensionHandle<Local extends JSONObject, Peer = JSONObject, Contex
     }
 
     private _assertPeerCapability(method: string): void {
-        if (this._enforceStrictCapabilities && this._getPeerExtensionSettings() === undefined) {
+        if (this._getEnforceStrictCapabilities() && this._getPeerExtensionSettings() === undefined) {
             throw new SdkError(
                 SdkErrorCode.CapabilityNotSupported,
                 `Peer does not support extension "${this.id}" (required for ${method})`

packages/core/test/shared/extensionHandle.test.ts

@@ -33,7 +33,7 @@ function makeHandle(opts: { peer?: JSONObject | undefined; strict?: boolean; pee
         'io.example/ui',
         { local: true },
         () => opts.peer,
-        opts.strict ?? false,
+        () => opts.strict ?? false,
         opts.peerSchema
     );
     return { host, handle };
@@ -70,7 +70,7 @@ describe('ExtensionHandle.getPeerSettings', () => {
         let peer: JSONObject | undefined;
         const getter = vi.fn(() => peer);
         const host = makeMockHost() as unknown as ExtensionHost<BaseContext>;
-        const handle = new ExtensionHandle(host, 'io.example/ui', {}, getter, false);
+        const handle = new ExtensionHandle(host, 'io.example/ui', {}, getter, () => false);
 
         expect(handle.getPeerSettings()).toBeUndefined();
         peer = { v: 1 };

packages/server/src/server/server.ts

@@ -234,6 +234,10 @@ export class Server extends Protocol<ServerContext> {
      * in the `initialize` result. Must be called before {@linkcode connect}. After connecting,
      * {@linkcode ExtensionHandle.getPeerSettings | handle.getPeerSettings()} returns the client's
      * `capabilities.extensions[id]` blob (validated against `peerSchema` if provided).
+     *
+     * Note: a later {@linkcode registerCapabilities} call that includes `extensions[id]` will
+     * overwrite the wire value declared here; the returned handle's `settings` reflects what
+     * was passed to this call, not subsequent overwrites.
      */
     public extension<L extends JSONObject>(id: string, settings: L): ExtensionHandle<L, JSONObject, ServerContext>;
     public extension<L extends JSONObject, P extends AnySchema>(
@@ -258,7 +262,7 @@ export class Server extends Protocol<ServerContext> {
             id,
             settings,
             () => this._clientCapabilities?.extensions?.[id],
-            this._enforceStrictCapabilities,
+            () => this._enforceStrictCapabilities,
             opts?.peerSchema
         );
     }