fix(core): use SdkError for duplicate extension; defer capability check pre-connect

- duplicate-ID guard now throws SdkError(ExtensionAlreadyRegistered) instead of plain Error
- _assertPeerCapability defers when peer capabilities are not yet populated, so strict-mode
  sendRequest before connect() surfaces NotConnected (from the underlying send) rather than
  a misleading CapabilityNotSupported

Author: felixweinberger

packages/client/src/client/client.ts

@@ -340,14 +340,15 @@ export class Client extends Protocol<ClientContext> {
             throw new SdkError(SdkErrorCode.AlreadyConnected, 'Cannot register extension after connecting to transport');
         }
         if (this._capabilities.extensions && Object.hasOwn(this._capabilities.extensions, id)) {
-            throw new Error(`Extension "${id}" is already registered`);
+            throw new SdkError(SdkErrorCode.ExtensionAlreadyRegistered, `Extension "${id}" is already registered`);
         }
         this._capabilities.extensions = { ...this._capabilities.extensions, [id]: settings };
         return new ExtensionHandle(
             this,
             id,
             settings,
             () => this._serverCapabilities?.extensions?.[id],
+            () => this._serverCapabilities !== undefined,
             () => this._enforceStrictCapabilities,
             opts?.peerSchema
         );

packages/core/src/errors/sdkErrors.ts

@@ -10,6 +10,7 @@ export enum SdkErrorCode {
     // State errors
     /** Transport is not connected */
     NotConnected = 'NOT_CONNECTED',
+    ExtensionAlreadyRegistered = 'EXTENSION_ALREADY_REGISTERED',
     /** Transport is already connected */
     AlreadyConnected = 'ALREADY_CONNECTED',
     /** Protocol is not initialized */

packages/core/src/shared/extensionHandle.ts

@@ -67,6 +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 _getPeerCapabilitiesPresent: () => boolean,
         private readonly _getEnforceStrictCapabilities: () => boolean,
         private readonly _peerSchema?: AnySchema
     ) {}
@@ -150,6 +151,10 @@ export class ExtensionHandle<Local extends JSONObject, Peer = JSONObject, Contex
     }
 
     private _assertPeerCapability(method: string): void {
+        // If peer capabilities are not yet populated (pre-connect), defer to the
+        // NotConnected error from the underlying send path rather than misreporting
+        // CapabilityNotSupported.
+        if (!this._getPeerCapabilitiesPresent()) return;
         if (this._getEnforceStrictCapabilities() && this._getPeerExtensionSettings() === undefined) {
             throw new SdkError(
                 SdkErrorCode.CapabilityNotSupported,

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

@@ -23,7 +23,7 @@ function makeMockHost(): MockHost {
     };
 }
 
-function makeHandle(opts: { peer?: JSONObject | undefined; strict?: boolean; peerSchema?: z.core.$ZodType }): {
+function makeHandle(opts: { peer?: JSONObject | undefined; peerPresent?: boolean; strict?: boolean; peerSchema?: z.core.$ZodType }): {
     host: MockHost;
     handle: ExtensionHandle<JSONObject, unknown, BaseContext>;
 } {
@@ -33,6 +33,7 @@ function makeHandle(opts: { peer?: JSONObject | undefined; strict?: boolean; pee
         'io.example/ui',
         { local: true },
         () => opts.peer,
+        () => opts.peerPresent ?? opts.peer !== undefined,
         () => opts.strict ?? false,
         opts.peerSchema
     );
@@ -70,7 +71,14 @@ 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,
+            () => true,
+            () => false
+        );
 
         expect(handle.getPeerSettings()).toBeUndefined();
         peer = { v: 1 };
@@ -102,15 +110,15 @@ describe('ExtensionHandle.sendRequest / sendNotification — peer gating', () =>
     const Result = z.object({ ok: z.boolean() });
 
     test('lax mode (default): sends even when peer did not advertise', async () => {
-        const { host, handle } = makeHandle({ peer: undefined, strict: false });
+        const { host, handle } = makeHandle({ peer: undefined, peerPresent: true, strict: false });
         await handle.sendRequest('ui/do', { x: 1 }, Result);
         expect(host.sendCustomRequest).toHaveBeenCalledWith('ui/do', { x: 1 }, Result, undefined);
         await handle.sendNotification('ui/ping', {});
         expect(host.sendCustomNotification).toHaveBeenCalledWith('ui/ping', {}, undefined);
     });
 
     test('strict mode: rejects with CapabilityNotSupported when peer did not advertise', async () => {
-        const { host, handle } = makeHandle({ peer: undefined, strict: true });
+        const { host, handle } = makeHandle({ peer: undefined, peerPresent: true, strict: true });
         await expect(handle.sendRequest('ui/do', {}, Result)).rejects.toSatisfy(
             (e: unknown) =>
                 e instanceof SdkError && e.code === SdkErrorCode.CapabilityNotSupported && /io\.example\/ui.*ui\/do/.test(e.message)
@@ -138,3 +146,11 @@ describe('ExtensionHandle — id and settings', () => {
         expect(handle.settings).toEqual({ local: true });
     });
 });
+
+describe('ExtensionHandle — pre-connect strict mode defers to NotConnected', () => {
+    test('does not throw CapabilityNotSupported before peer capabilities are known', async () => {
+        const { host, handle } = makeHandle({ peer: undefined, peerPresent: false, strict: true });
+        await handle.sendRequest('ui/do', {}, z.object({}));
+        expect(host.sendCustomRequest).toHaveBeenCalledOnce();
+    });
+});

packages/server/src/server/server.ts

@@ -254,14 +254,15 @@ export class Server extends Protocol<ServerContext> {
             throw new SdkError(SdkErrorCode.AlreadyConnected, 'Cannot register extension after connecting to transport');
         }
         if (this._capabilities.extensions && Object.hasOwn(this._capabilities.extensions, id)) {
-            throw new Error(`Extension "${id}" is already registered`);
+            throw new SdkError(SdkErrorCode.ExtensionAlreadyRegistered, `Extension "${id}" is already registered`);
         }
         this._capabilities.extensions = { ...this._capabilities.extensions, [id]: settings };
         return new ExtensionHandle(
             this,
             id,
             settings,
             () => this._clientCapabilities?.extensions?.[id],
+            () => this._clientCapabilities !== undefined,
             () => this._enforceStrictCapabilities,
             opts?.peerSchema
         );