@nority/bridge-sdk 0.1.0 → 0.2.1

package/README.md

@@ -68,18 +68,92 @@ const bridge = new NorityBridge({
   backendUrl: "wss://api.nority.ai/v1/bridge",
   dataDir: "./bridge-data",
   agent: new MyAdapter(),
-  onPairingToken: (info) => {
+  onPairingInfo: (info) => {
     console.log(`Pair: ${info.deeplinkUrl} (expires ${info.expiresAt})`);
   },
 });
 
 await bridge.start();
+// Bridge is now connected and handling conversations
 ```
 
-On first run, the SDK generates an Ed25519 identity, enters the pairing flow, and calls `onPairingToken` with a QR/deeplink URL. After the user approves in the Nority app, the bridge receives a durable credential and connects automatically.
+On first run, the SDK generates an Ed25519 identity, enters the pairing flow, and calls `onPairingInfo` with a QR/deeplink URL. `start()` blocks until the user approves in the Nority app and the bridge connects.
 
 On subsequent runs, the SDK loads the stored credential, mints a fresh JWT via challenge-response, reconnects, replays missed events, and resumes normal operation.
 
+## Layered API
+
+The SDK exposes three levels of abstraction. Most developers only need `NorityBridge`.
+
+### `NorityBridge` — managed (recommended)
+
+Handles everything: pairing, credential persistence, auth, transport, conversations. `start()` blocks until fully connected regardless of whether pairing was needed.
+
+```ts
+import { NorityBridge } from "@nority/bridge-sdk";
+
+const bridge = new NorityBridge({
+  backendUrl: "wss://api.nority.ai/v1/bridge",
+  dataDir: "./bridge-data",
+  agent: myAdapter,
+  onPairingInfo: (info) => console.log(`Scan: ${info.deeplinkUrl}`),
+});
+
+await bridge.start();   // blocks until connected
+await bridge.stop();    // graceful shutdown
+```
+
+### `PairingClient` — standalone pairing
+
+Use this when you want to control the pairing ceremony yourself — embed the QR in your own UI, store the credential in your own database, or skip pairing entirely with pre-provisioned credentials.
+
+```ts
+import { PairingClient } from "@nority/bridge-sdk";
+
+const pairing = new PairingClient({
+  backendUrl: "wss://api.nority.ai/v1/bridge",
+  dataDir: "./bridge-data",
+  onPairingInfo: (info) => renderQRCode(info.deeplinkUrl),
+});
+
+const result = await pairing.pair();  // blocks until user approves
+// result.credential — durable bridge credential
+// result.identity   — Ed25519 keypair
+// result.initialToken — first JWT (pass as seedJwt to BridgeConnection)
+```
+
+**Methods:**
+- `pair()` — performs the pairing ceremony. Resolves when the user approves. Single-flight (throws if called while already pairing).
+- `cancel()` — cancels in-progress pairing. Rejects the pending `pair()` promise. Idempotent.
+- `regenerateToken()` — closes the WebSocket, opens a new one, sends a fresh `pair_request`. Returns updated `PairingInfo`.
+- `getPairingInfo()` — returns current pairing info or `null`.
+
+### `BridgeConnection` — standalone connection
+
+Use this when you already have a credential (pre-provisioned from a dashboard, stored in your own secret manager, or obtained via `PairingClient`).
+
+```ts
+import { BridgeConnection } from "@nority/bridge-sdk";
+
+const connection = new BridgeConnection({
+  backendUrl: "wss://api.nority.ai/v1/bridge",
+  dataDir: "./bridge-data",
+  credential: process.env.BRIDGE_CREDENTIAL,
+  privateKeyPem: fs.readFileSync("./bridge-key.pem", "utf-8"),
+  agent: myAdapter,
+  seedJwt: cachedToken,  // optional — skip first challenge-response
+});
+
+await connection.connect();    // blocks until connected
+await connection.disconnect(); // graceful shutdown
+```
+
+**Methods:**
+- `connect()` — authenticates via challenge-response, opens authenticated WebSocket, sends replay request. Resolves when connected.
+- `disconnect()` — closes connection, stops reconnection, aborts active agent invocations. Idempotent.
+- `getState()` — returns current state (`idle | connecting | connected | reconnecting | blocked | failed | stopped`).
+- `createProactiveTurnFrame(conversationId, request)` — creates an `assistant_turn_start` frame for bridge-initiated turns.
+
 ## Key concepts
 
 | Concept | Description |
@@ -141,16 +215,56 @@ idle → pairing → connecting → connected
 
 ## Configuration
 
+### `BridgeConfig` (for `NorityBridge`)
+
 ```ts
 interface BridgeConfig {
-  backendUrl: string;            // Nority backend WebSocket URL
-  dataDir: string;               // Directory for durable state (identity, keys)
-  agent: AgentAdapter;           // Your adapter implementation
-  onPairingToken?: (info) => void;  // Called when pairing token is ready
-  logger?: BridgeLogger;         // Structured logging
-  webSocketFactory?: WebSocketFactory;  // Custom WebSocket creation
-  heartbeatIntervalMs?: number;  // Default: 15000
-  idleTimeoutMs?: number;        // Default: 45000
+  backendUrl: string;                          // Nority backend WebSocket URL
+  dataDir: string;                             // Directory for durable state (identity, keys)
+  agent: AgentAdapter;                         // Your adapter implementation
+  onPairingInfo?: (pairing: PairingInfo) => void; // Called when pairing token is ready
+  logger?: BridgeLogger;                       // Structured logging
+  webSocketFactory?: WebSocketFactory;         // Custom WebSocket creation
+  fetchImplementation?: typeof fetch;          // Custom fetch (for auth challenge-response)
+  clock?: () => Date;                          // Custom clock (for testing)
+  pairingTokenFactory?: () => string;          // Custom pairing token generator
+  backoffRandom?: () => number;                // Custom RNG for reconnect backoff jitter
+  heartbeatIntervalMs?: number;                // Default: 15000
+  idleTimeoutMs?: number;                      // Default: 45000
+}
+```
+
+### `PairingClientConfig`
+
+```ts
+interface PairingClientConfig {
+  backendUrl: string;
+  dataDir: string;
+  onPairingInfo?: (info: PairingInfo) => void;
+  logger?: BridgeLogger;
+  webSocketFactory?: WebSocketFactory;
+  clock?: () => Date;
+  pairingTokenFactory?: () => string;
+}
+```
+
+### `BridgeConnectionConfig`
+
+```ts
+interface BridgeConnectionConfig {
+  backendUrl: string;
+  dataDir: string;
+  credential: string;
+  privateKeyPem: string;
+  agent: AgentAdapter;
+  logger?: BridgeLogger;
+  seedJwt?: AccessTokenRecord;
+  fetchImplementation?: typeof fetch;
+  webSocketFactory?: WebSocketFactory;
+  clock?: () => Date;
+  backoffRandom?: () => number;
+  heartbeatIntervalMs?: number;
+  idleTimeoutMs?: number;
 }
 ```
 

package/dist/agent.d.ts

@@ -88,7 +88,7 @@ export interface BridgeConfig {
     backendUrl: string;
     dataDir: string;
     agent: AgentAdapter;
-    onPairingToken?: (pairing: PairingInfo) => void;
+    onPairingInfo?: (pairing: PairingInfo) => void;
     logger?: BridgeLogger;
     fetchImplementation?: typeof fetch;
     webSocketFactory?: WebSocketFactory;

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAIjE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC;AAE7C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAID,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvC;IACE,IAAI,EAAE,iBAAiB,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,MAAM,WAAW,YAAY;IAC3B,WAAW,CACT,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,aAAa,GACjB,aAAa,CAAC,UAAU,CAAC,CAAC;CAC9B;AAID,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACjD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAChD,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,YAAY,CAAC;IACpB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IAC/C,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,mBAAmB,CAAC,EAAE,OAAO,KAAK,CAAC;IACnC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,MAAM,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/bridge.d.ts

@@ -1,27 +1,25 @@
 import type { BridgeConfig, PairingInfo } from "./agent.js";
 import type { ProactiveTurnRequest } from "./runtime/proactive.js";
-import { type BridgeFrame } from "./protocol/frames.js";
+import type { BridgeFrame } from "./protocol/frames.js";
 /**
  * Bridge lifecycle states.
  */
 export type BridgeState = "idle" | "pairing" | "connecting" | "connected" | "reconnecting" | "blocked" | "failed" | "stopped";
 /**
- * NorityBridge is the main entry point for bridge implementations.
- * Manages pairing, auth refresh, reconnection, and durable bridge identity.
+ * NorityBridge is the managed entry point for bridge implementations.
+ * Composes PairingClient + BridgeConnection: if no stored credential,
+ * runs pairing first; otherwise connects directly.
+ *
+ * start() blocks until the bridge is fully connected — regardless of
+ * whether pairing was needed. The onPairingInfo callback fires during
+ * start() if pairing is required, enabling the caller to display a QR code.
  */
 export declare class NorityBridge {
     private readonly config;
-    private readonly logger;
     private readonly stateStore;
-    private readonly accessTokenManager;
-    private readonly conversationRuntime;
     private state;
-    private durableState;
-    private pairingInfo;
-    private pairingTimer;
-    private pairingSocket;
-    private transport;
-    private readonly pendingFrameTasks;
+    private pairingClient;
+    private connection;
     constructor(config: BridgeConfig);
     getState(): BridgeState;
     getPairingInfo(): PairingInfo | null;
@@ -29,16 +27,8 @@ export declare class NorityBridge {
     start(): Promise<void>;
     stop(): Promise<void>;
     regeneratePairingToken(): Promise<PairingInfo>;
-    private beginPairingFlow;
-    private restartPairingFlow;
-    private handlePairingMessage;
-    private ensureAuthenticatedTransport;
-    private handleTransportStateChange;
-    private getDurableState;
-    private clearPairingTimer;
+    private connectWithCredential;
+    private syncConnectionState;
     private setState;
-    private handleTransportFrame;
-    private trackFrameTask;
-    private sendTransportFrame;
 }
 //# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAgB,WAAW,EAAE,MAAM,YAAY,CAAC;AAW1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAMnE,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGrE;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,SAAS,GACT,YAAY,GACZ,WAAW,GACX,cAAc,GACd,SAAS,GACT,QAAQ,GACR,SAAS,CAAC;AASd;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA2B;IAC9D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,SAAS,CAAgD;IACjE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4B;gBAElD,MAAM,EAAE,YAAY;IAkBhC,QAAQ,IAAI,WAAW;IAIvB,cAAc,IAAI,WAAW,GAAG,IAAI;IAIpC,wBAAwB,CACtB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,oBAAoB,GAC5B,WAAW,CAAC,sBAAsB,CAAC;IAOhC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBrB,sBAAsB,IAAI,OAAO,CAAC,WAAW,CAAC;YAatC,gBAAgB;YAKhB,kBAAkB;YAkDlB,oBAAoB;YAuDpB,4BAA4B;IAqC1C,OAAO,CAAC,0BAA0B;IAqClC,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,QAAQ;YAIF,oBAAoB;YAYpB,cAAc;IAS5B,OAAO,CAAC,kBAAkB;CAQ3B"}
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,SAAS,GACT,YAAY,GACZ,WAAW,GACX,cAAc,GACd,SAAS,GACT,QAAQ,GACR,SAAS,CAAC;AAEd;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,UAAU,CAAiC;gBAEvC,MAAM,EAAE,YAAY;IAMhC,QAAQ,IAAI,WAAW;IAIvB,cAAc,IAAI,WAAW,GAAG,IAAI;IAIpC,wBAAwB,CACtB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,oBAAoB,GAC5B,WAAW,CAAC,sBAAsB,CAAC;IAShC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwCtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAcrB,sBAAsB,IAAI,OAAO,CAAC,WAAW,CAAC;YAStC,qBAAqB;IA4BnC,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,QAAQ;CAGjB"}

package/dist/bridge.js

@@ -1,311 +1,145 @@
 import { validateConfig } from "./config.js";
-import { createPairingExpiry, createPairingToken, createDeeplinkUrl, PAIRING_TOKEN_TTL_SECONDS, } from "./auth/pairing.js";
-import { BridgeAccessTokenManager } from "./auth/reconnect.js";
+import { PairingClient } from "./pairing/client.js";
+import { BridgeConnection } from "./connection.js";
 import { FileBridgeStateStore } from "./storage/state-store.js";
-import { ConversationRuntime } from "./conversation/runtime.js";
-import { AuthenticatedWebSocketTransport, } from "./transport/websocket.js";
-import { createFrame } from "./protocol/frames.js";
-import { getEd25519PublicKeyBase64 } from "./crypto/identity.js";
-const noopLogger = {
-    debug: () => { },
-    info: () => { },
-    warn: () => { },
-    error: () => { },
-};
 /**
- * NorityBridge is the main entry point for bridge implementations.
- * Manages pairing, auth refresh, reconnection, and durable bridge identity.
+ * NorityBridge is the managed entry point for bridge implementations.
+ * Composes PairingClient + BridgeConnection: if no stored credential,
+ * runs pairing first; otherwise connects directly.
+ *
+ * start() blocks until the bridge is fully connected — regardless of
+ * whether pairing was needed. The onPairingInfo callback fires during
+ * start() if pairing is required, enabling the caller to display a QR code.
  */
 export class NorityBridge {
     config;
-    logger;
     stateStore;
-    accessTokenManager;
-    conversationRuntime;
     state = "idle";
-    durableState = null;
-    pairingInfo = null;
-    pairingTimer = null;
-    pairingSocket = null;
-    transport = null;
-    pendingFrameTasks = new Set();
+    pairingClient = null;
+    connection = null;
     constructor(config) {
         validateConfig(config);
         this.config = config;
-        this.logger = config.logger ?? noopLogger;
         this.stateStore = new FileBridgeStateStore(config.dataDir);
-        this.accessTokenManager = new BridgeAccessTokenManager({
-            backendUrl: config.backendUrl,
-            fetchImplementation: config.fetchImplementation,
-            clock: config.clock,
-        });
-        this.conversationRuntime = new ConversationRuntime({
-            dataDir: config.dataDir,
-            agent: config.agent,
-            logger: this.logger,
-            clock: config.clock,
-        });
     }
     getState() {
         return this.state;
     }
     getPairingInfo() {
-        return this.pairingInfo === null ? null : { ...this.pairingInfo };
+        return this.pairingClient?.getPairingInfo() ?? null;
     }
     createProactiveTurnFrame(conversationId, request) {
-        return this.conversationRuntime.createProactiveTurnFrame(conversationId, request);
+        if (this.connection === null) {
+            throw new Error("NorityBridge.createProactiveTurnFrame: connection must exist");
+        }
+        return this.connection.createProactiveTurnFrame(conversationId, request);
     }
     async start() {
         if (this.state !== "idle" && this.state !== "stopped") {
             throw new Error(`NorityBridge.start: cannot start bridge in state ${this.state}`);
         }
-        this.durableState = await this.stateStore.loadOrCreateIdentity();
-        await this.conversationRuntime.loadPersistedConversations();
-        if (!this.durableState.bridgeCredential) {
+        const storedState = await this.stateStore.loadOrCreateIdentity();
+        if (storedState.bridgeCredential) {
+            await this.connectWithCredential(storedState);
+        }
+        else {
             this.setState("pairing");
-            await this.beginPairingFlow();
-            return;
+            this.pairingClient = new PairingClient({
+                backendUrl: this.config.backendUrl,
+                dataDir: this.config.dataDir,
+                onPairingInfo: this.config.onPairingInfo,
+                logger: this.config.logger,
+                webSocketFactory: this.config.webSocketFactory,
+                clock: this.config.clock,
+                pairingTokenFactory: this.config.pairingTokenFactory,
+            });
+            const result = await this.pairingClient.pair();
+            this.pairingClient = null;
+            await this.stateStore.save({
+                agentId: result.agentId,
+                bridgeCredential: result.credential,
+                privateKeyPem: result.identity.privateKeyPem,
+                publicKeyPem: result.identity.publicKeyPem,
+            });
+            await this.connectWithCredential({
+                agentId: result.agentId,
+                bridgeCredential: result.credential,
+                privateKeyPem: result.identity.privateKeyPem,
+                publicKeyPem: result.identity.publicKeyPem,
+            }, result.initialToken);
         }
-        await this.ensureAuthenticatedTransport(false);
     }
     async stop() {
-        this.clearPairingTimer();
-        const pairingSocket = this.pairingSocket;
-        this.pairingSocket = null;
-        if (pairingSocket !== null) {
-            pairingSocket.close(1000, "pairing stopped");
+        if (this.pairingClient !== null) {
+            this.pairingClient.cancel();
+            this.pairingClient = null;
         }
-        this.conversationRuntime.stop();
-        if (this.transport !== null) {
-            await this.transport.disconnect();
-            this.transport = null;
+        if (this.connection !== null) {
+            await this.connection.disconnect();
+            this.connection = null;
         }
-        await Promise.allSettled(Array.from(this.pendingFrameTasks));
         this.setState("stopped");
     }
     async regeneratePairingToken() {
-        if (this.state !== "pairing") {
+        if (this.state !== "pairing" || this.pairingClient === null) {
             throw new Error(`NorityBridge.regeneratePairingToken: bridge must be in pairing state, got ${this.state}`);
         }
-        await this.restartPairingFlow();
-        if (this.pairingInfo === null) {
-            throw new Error("NorityBridge.regeneratePairingToken: pairingInfo must exist");
-        }
-        return { ...this.pairingInfo };
-    }
-    async beginPairingFlow() {
-        const currentState = this.getDurableState();
-        await this.restartPairingFlow(currentState);
-    }
-    async restartPairingFlow(state = this.getDurableState()) {
-        const existingSocket = this.pairingSocket;
-        this.pairingSocket = null;
-        if (existingSocket !== null) {
-            existingSocket.close(1000, "pairing token rotated");
-        }
-        this.clearPairingTimer();
-        const token = this.config.pairingTokenFactory?.() ?? createPairingToken();
-        if (!token) {
-            throw new Error("NorityBridge.restartPairingFlow: pairing token must not be empty");
-        }
-        this.pairingInfo = {
-            token,
-            deeplinkUrl: createDeeplinkUrl(token),
-            expiresAt: createPairingExpiry({
-                clock: this.config.clock,
-                tokenTtlSeconds: PAIRING_TOKEN_TTL_SECONDS,
-            }),
-        };
-        this.config.onPairingToken?.({ ...this.pairingInfo });
-        this.pairingTimer = setTimeout(() => {
-            void this.restartPairingFlow(state);
-        }, PAIRING_TOKEN_TTL_SECONDS * 1000);
-        const webSocketFactory = this.config.webSocketFactory;
-        if (webSocketFactory === undefined) {
-            throw new Error("NorityBridge.restartPairingFlow: webSocketFactory is required for pairing");
-        }
-        const socket = webSocketFactory.create(this.config.backendUrl, {});
-        this.pairingSocket = socket;
-        await waitForOpen(socket);
-        socket.addEventListener("message", (event) => {
-            void this.handlePairingMessage(event.data);
+        return this.pairingClient.regenerateToken();
+    }
+    async connectWithCredential(storedState, seedJwt) {
+        if (!storedState.bridgeCredential) {
+            throw new Error("NorityBridge: bridgeCredential is required");
+        }
+        this.connection = new BridgeConnection({
+            backendUrl: this.config.backendUrl,
+            dataDir: this.config.dataDir,
+            credential: storedState.bridgeCredential,
+            privateKeyPem: storedState.privateKeyPem,
+            agent: this.config.agent,
+            seedJwt,
+            logger: this.config.logger,
+            fetchImplementation: this.config.fetchImplementation,
+            webSocketFactory: this.config.webSocketFactory,
+            clock: this.config.clock,
+            backoffRandom: this.config.backoffRandom,
+            heartbeatIntervalMs: this.config.heartbeatIntervalMs,
+            idleTimeoutMs: this.config.idleTimeoutMs,
         });
-        const pairRequest = createFrame("pair_request", {
-            pairing_token: token,
-            bridge_public_key: getEd25519PublicKeyBase64(state.publicKeyPem),
-        });
-        socket.send(JSON.stringify(pairRequest));
+        await this.connection.connect();
+        this.syncConnectionState();
     }
-    async handlePairingMessage(rawData) {
-        let frame;
-        try {
-            frame = JSON.parse(rawData);
-        }
-        catch (error) {
-            this.logger.warn("NorityBridge.handlePairingMessage: invalid JSON", error);
+    syncConnectionState() {
+        if (this.connection === null) {
             return;
         }
-        if (frame.type !== "paired") {
-            return;
-        }
-        const payload = frame.payload;
-        if (!payload.agent_id ||
-            !payload.bridge_credential ||
-            !payload.access_jwt ||
-            !payload.expires_at) {
-            throw new Error("NorityBridge.handlePairingMessage: paired payload missing required fields");
-        }
-        const currentState = this.getDurableState();
-        const nextState = {
-            ...currentState,
-            agentId: payload.agent_id,
-            bridgeCredential: payload.bridge_credential,
-        };
-        await this.stateStore.save(nextState);
-        this.durableState = nextState;
-        this.accessTokenManager.seed({
-            accessJwt: payload.access_jwt,
-            agentId: payload.agent_id,
-            expiresAt: payload.expires_at,
-        });
-        this.clearPairingTimer();
-        const pairingSocket = this.pairingSocket;
-        this.pairingSocket = null;
-        if (pairingSocket !== null) {
-            pairingSocket.close(1000, "pairing completed");
-        }
-        await this.ensureAuthenticatedTransport(false);
-    }
-    async ensureAuthenticatedTransport(forceRefresh) {
-        const currentState = this.getDurableState();
-        if (!currentState.bridgeCredential) {
-            throw new Error("NorityBridge.ensureAuthenticatedTransport: bridgeCredential is required");
-        }
-        if (this.transport === null) {
-            this.transport = new AuthenticatedWebSocketTransport({
-                backendUrl: this.config.backendUrl,
-                webSocketFactory: this.config.webSocketFactory,
-                heartbeatIntervalMs: this.config.heartbeatIntervalMs,
-                idleTimeoutMs: this.config.idleTimeoutMs,
-                random: this.config.backoffRandom,
-                clock: this.config.clock,
-                logger: this.logger,
-                onFrame: async (frame) => {
-                    await this.trackFrameTask(this.handleTransportFrame(frame));
-                },
-                onStateChange: (transportState) => {
-                    this.handleTransportStateChange(transportState);
-                },
-                getAccessToken: async (refreshRequested = false) => {
-                    const token = await this.accessTokenManager.getAccessToken({
-                        credential: currentState.bridgeCredential ?? "",
-                        privateKeyPem: currentState.privateKeyPem,
-                        forceRefresh: refreshRequested,
-                    });
-                    return token.accessJwt;
-                },
-            });
-        }
-        await this.transport.connect(forceRefresh);
-    }
-    handleTransportStateChange(transportState) {
-        switch (transportState) {
-            case "connecting":
-                this.setState("connecting");
-                break;
-            case "connected":
-                this.setState("connected");
-                if (this.transport !== null) {
-                    const replayRequest = this.conversationRuntime.createReplayRequestFrame();
-                    if (replayRequest !== null) {
-                        this.transport.send(replayRequest);
-                    }
-                }
-                break;
-            case "reconnecting":
-                this.setState("reconnecting");
-                break;
-            case "blocked":
-                this.setState("blocked");
-                break;
-            case "failed":
-                this.setState("failed");
-                break;
-            case "stopped":
-                if (this.state !== "stopped") {
-                    this.setState("stopped");
-                }
-                break;
-            case "idle":
-                break;
-            default:
-                throw new Error(`NorityBridge.handleTransportStateChange: unsupported transport state ${transportState}`);
-        }
-    }
-    getDurableState() {
-        if (this.durableState === null) {
-            throw new Error("NorityBridge: durable bridge state has not been loaded");
-        }
-        return this.durableState;
-    }
-    clearPairingTimer() {
-        if (this.pairingTimer !== null) {
-            clearTimeout(this.pairingTimer);
-            this.pairingTimer = null;
+        const connState = this.connection.getState();
+        const mapped = mapConnectionState(connState);
+        if (mapped !== null) {
+            this.setState(mapped);
         }
     }
     setState(nextState) {
         this.state = nextState;
     }
-    async handleTransportFrame(frame) {
-        if (this.transport === null) {
-            throw new Error("NorityBridge.handleTransportFrame: transport must exist while handling frames");
-        }
-        await this.conversationRuntime.handleFrame(frame, (outboundFrame) => {
-            this.sendTransportFrame(outboundFrame);
-        });
-    }
-    async trackFrameTask(task) {
-        this.pendingFrameTasks.add(task);
-        try {
-            await task;
-        }
-        finally {
-            this.pendingFrameTasks.delete(task);
-        }
-    }
-    sendTransportFrame(outboundFrame) {
-        if (this.transport === null) {
-            throw new Error("NorityBridge.sendTransportFrame: transport must exist while sending outbound frames");
-        }
-        this.transport.send(outboundFrame);
-    }
 }
-function waitForOpen(socket) {
-    if (socket.readyState === 1) {
-        return Promise.resolve();
+function mapConnectionState(state) {
+    switch (state) {
+        case "connecting":
+            return "connecting";
+        case "connected":
+            return "connected";
+        case "reconnecting":
+            return "reconnecting";
+        case "blocked":
+            return "blocked";
+        case "failed":
+            return "failed";
+        case "stopped":
+            return "stopped";
+        case "idle":
+            return null;
+        default:
+            return null;
     }
-    return new Promise((resolve, reject) => {
-        const handleOpen = () => {
-            cleanup();
-            resolve();
-        };
-        const handleError = () => {
-            cleanup();
-            reject(new Error("NorityBridge.waitForOpen: websocket error during pairing"));
-        };
-        const handleClose = () => {
-            cleanup();
-            reject(new Error("NorityBridge.waitForOpen: websocket closed before pairing socket opened"));
-        };
-        const cleanup = () => {
-            socket.removeEventListener("open", handleOpen);
-            socket.removeEventListener("error", handleError);
-            socket.removeEventListener("close", handleClose);
-        };
-        socket.addEventListener("open", handleOpen);
-        socket.addEventListener("error", handleError);
-        socket.addEventListener("close", handleClose);
-    });
 }
 //# sourceMappingURL=bridge.js.map