@datagrout/conduit 0.2.0 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@ Production-ready MCP client with mTLS identity, OAuth 2.1, semantic discovery, a
 ## Installation
 
 ```bash
-npm install @datagrout/conduit
+npm install @datagrout/conduit@0.4.0
 ```
 
 ## Quick Start
@@ -158,8 +158,58 @@ const client = new Client({ url });
 
 // JSONRPC — lightweight, stateless, same tools and auth
 const client = new Client({ url, transport: 'jsonrpc' });
+
+// WebSocket — bidirectional push
+const client = new Client({
+  url: 'wss://gateway.datagrout.ai/servers/{uuid}/ws',
+  transport: 'websocket',
+});
 ```
 
+### WebSocket transport
+
+The WebSocket transport uses the `datagrout-jsonrpc.v1` subprotocol over a single persistent `wss://` connection. Concurrent requests are multiplexed; responses correlated by JSON-RPC `id` via `Map<string, { resolve, reject }>`.
+
+```typescript
+import { Client } from '@datagrout/conduit';
+
+const client = new Client({
+  url: 'wss://gateway.datagrout.ai/servers/{uuid}/ws',
+  auth: { bearer: 'your-token' },
+  transport: 'websocket',
+});
+await client.connect();
+
+// Subscribe to server-pushed events
+const sub = await client.subscribe('agents.my-agent-id.events');
+
+for await (const event of sub) {
+  console.log(event.event, event.data);
+}
+
+await client.unsubscribe(sub.id);
+await client.disconnect();
+```
+
+You can also call `await sub.recv()` for one-event-at-a-time consumption:
+
+```typescript
+const event = await sub.recv();
+console.log(event.event, event.data);
+```
+
+Supported topics:
+
+| Topic | Fires when |
+|-------|-----------|
+| `agents.<agent_id>.events` | Agent lifecycle events (plan started, IC completed, grounding failed, …) |
+| `tools.<tool_name>.results` | A specific tool call completes |
+| `tasks.<task_id>.*` | Long-running background task transitions |
+| `flows.<flow_id>.*` | `flow.into` progress and completion |
+| `governor.<server_uuid>` | Governor percept events (file change, schedule, webhook) |
+
+**Reconnection**: after a disconnect, calls raise `NotInitializedError`. Re-call `connect()` and re-subscribe — subscriptions do not survive reconnects in v0.4.
+
 ## API Reference
 
 ### Client Options
@@ -168,7 +218,7 @@ const client = new Client({ url, transport: 'jsonrpc' });
 new Client(options: {
   url: string;
   auth?: { bearer?: string; apiKey?: string; clientCredentials?: {...} };
-  transport?: 'mcp' | 'jsonrpc';
+  transport?: 'mcp' | 'jsonrpc' | 'websocket';
   useIntelligentInterface?: boolean;
   identity?: ConduitIdentity;
   identityAuto?: boolean;

package/dist/index.d.mts

@@ -256,6 +256,7 @@ interface GuideState {
 }
 interface AuthConfig {
     bearer?: string;
+    apiKey?: string;
     basic?: {
         username: string;
         password: string;
@@ -321,7 +322,7 @@ interface ClientOptions {
      * @default false
      */
     disableMtls?: boolean;
-    transport?: 'mcp' | 'jsonrpc';
+    transport?: 'mcp' | 'jsonrpc' | 'websocket';
     timeout?: number;
     /**
      * Maximum number of automatic retries on "server not initialized" errors.
@@ -461,6 +462,136 @@ interface MCPPrompt {
     }>;
 }
 
+/**
+ * Base transport interface
+ */
+
+declare abstract class Transport {
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract listTools(options?: any): Promise<MCPTool[]>;
+    abstract callTool(name: string, args: Record<string, any>, options?: any): Promise<any>;
+    abstract listResources(options?: any): Promise<MCPResource[]>;
+    abstract readResource(uri: string, options?: any): Promise<any>;
+    abstract listPrompts(options?: any): Promise<MCPPrompt[]>;
+    abstract getPrompt(name: string, args?: Record<string, any>, options?: any): Promise<any>;
+}
+
+/**
+ * WebSocket transport for `datagrout-jsonrpc.v1`.
+ *
+ * Recommended for any client that needs bidirectional push (server-initiated
+ * notifications) without a polling loop. A single `wss://` connection is
+ * multiplexed for all in-flight requests; concurrent calls are correlated by
+ * JSON-RPC `id` with no head-of-line blocking.
+ *
+ * @example
+ * ```ts
+ * const client = new Client({
+ *   url: 'wss://gateway.datagrout.ai/servers/<uuid>/ws',
+ *   transport: 'websocket',
+ *   auth: { bearer: 'your-token' },
+ * });
+ * await client.connect();
+ *
+ * // Push subscription
+ * const sub = await client.subscribe('agents.my-agent-id.events');
+ * for await (const event of sub) {
+ *   console.log(event.event, event.data);
+ * }
+ * await client.unsubscribe(sub.id);
+ * ```
+ *
+ * @module
+ */
+
+declare const SUBPROTOCOL = "datagrout-jsonrpc.v1";
+/** A single server-pushed notification. */
+interface SubscriptionEvent {
+    /** The subscription id this event belongs to. */
+    subscription: string;
+    /** Server-named event slug (e.g. `"agent.thought"`). */
+    event: string;
+    /** Free-form payload from the server. */
+    data: unknown;
+}
+/**
+ * Handle for an active server-push subscription.
+ *
+ * Consume events with {@link Subscription.recv} or an async-for loop:
+ * ```ts
+ * for await (const event of sub) {
+ *   handle(event);
+ * }
+ * ```
+ */
+declare class Subscription {
+    readonly id: string;
+    readonly topic: string;
+    private _queue;
+    private _waiters;
+    private _rejecters;
+    private _closed;
+    constructor(id: string, topic: string);
+    /**
+     * Wait for the next event from this subscription.
+     *
+     * @throws When the subscription has been closed.
+     */
+    recv(): Promise<SubscriptionEvent>;
+    [Symbol.asyncIterator](): AsyncGenerator<SubscriptionEvent>;
+    _enqueue(event: SubscriptionEvent): void;
+    _close(): void;
+}
+/**
+ * JSON-RPC 2.0 over WebSocket transport (`datagrout-jsonrpc.v1`).
+ *
+ * Multiplexes any number of in-flight requests on one socket and routes
+ * server-pushed notifications back to {@link Subscription} queues.
+ */
+declare class WsTransport extends Transport {
+    private readonly _url;
+    private readonly _auth?;
+    private _ws;
+    private _nextId;
+    private readonly _pending;
+    private readonly _pendingSubscribe;
+    private readonly _subscriptions;
+    constructor(url: string, auth?: AuthConfig, _timeout?: number, _identity?: ConduitIdentity);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Open a server-side push subscription for `topic`.
+     *
+     * @param topic - Dotted namespace topic, e.g.
+     *   `"agents.my-agent-id.events"` or `"tasks.task-123.*"`.
+     * @returns A {@link Subscription} handle whose async-for loop delivers events.
+     */
+    subscribe(topic: string): Promise<Subscription>;
+    /**
+     * Cancel a server-side subscription.
+     *
+     * The local {@link Subscription} queue is closed immediately.
+     *
+     * @param subscriptionId - The `id` field from the {@link Subscription}
+     *   returned by {@link subscribe}.
+     */
+    unsubscribe(subscriptionId: string): Promise<void>;
+    listTools(options?: any): Promise<MCPTool[]>;
+    callTool(name: string, args: Record<string, any>, _options?: any): Promise<any>;
+    listResources(_options?: any): Promise<MCPResource[]>;
+    readResource(uri: string, _options?: any): Promise<any>;
+    listPrompts(_options?: any): Promise<MCPPrompt[]>;
+    getPrompt(name: string, args?: Record<string, any>, _options?: any): Promise<any>;
+    private _mintId;
+    private _requireConnected;
+    private _send;
+    private _request;
+    private _handleMessage;
+    private _routeNotification;
+    private _failAll;
+}
+
 /**
  * Prism namespace — data transformation, charting, rendering, and export.
  */
@@ -842,6 +973,33 @@ declare class Client {
      * @param args - Template argument values.
      */
     getPrompt(name: string, args?: Record<string, any>, options?: any): Promise<any>;
+    /**
+     * Subscribe to a server-push topic (WebSocket transport only).
+     *
+     * Requires `transport: 'websocket'` when constructing the client.
+     *
+     * @param topic - Dotted namespace topic, e.g.
+     *   `"agents.my-agent-id.events"` or `"tasks.task-123.*"`.
+     * @returns A {@link Subscription} handle. Consume events with
+     *   {@link Subscription.recv} or an `for await` loop.
+     *
+     * @example
+     * ```ts
+     * const sub = await client.subscribe('agents.my-agent-id.events');
+     * for await (const event of sub) {
+     *   console.log(event.event, event.data);
+     * }
+     * await client.unsubscribe(sub.id);
+     * ```
+     */
+    subscribe(topic: string): Promise<Subscription>;
+    /**
+     * Cancel a server-side push subscription.
+     *
+     * @param subscriptionId - The `id` from the {@link Subscription} returned
+     *   by {@link subscribe}.
+     */
+    unsubscribe(subscriptionId: string): Promise<void>;
     private warnIfNotDg;
     /**
      * Semantically discover tools relevant to a goal or query.
@@ -1223,6 +1381,6 @@ declare class InvalidConfigError extends ConduitError {
  * DataGrout Conduit SDK for TypeScript/JavaScript
  */
 
-declare const version = "0.1.0";
+declare const version = "0.4.0";
 
-export { type AuthConfig, AuthError, type Byok, type ChartOptions, Client, type ClientOptions, ConduitError, ConduitIdentity, type ConstrainOptions, type CreditEstimate, DEFAULT_IDENTITY_DIR, DG_CA_URL, DG_SUBSTRATE_ENDPOINT, type DiscoverOptions, type DiscoverResult, type FlowOptions, type ForgetOptions, type GuideOptions, type GuideRequestOptions, type GuideState, GuidedSession, InvalidConfigError, type Keypair, type MCPPrompt, type MCPResource, type MCPTool, type MtlsConfig, NetworkError, NotInitializedError, OAuthTokenProvider, type PerformOptions, type PerformResult, type PlanOptions, type PrismFocusOptions, type QueryCellOptions, type RateLimit, RateLimitError, type RateLimitStatus, type Receipt, type ReflectOptions, type RefractOptions, type RegisteredIdentity, type RegistrationOptions, type RememberOptions, type RenewalOptions, type RotationOptions, type SavedPaths, ServerError, type ToolInfo, type ToolMeta, deriveTokenEndpoint, extractMeta, fetchDgCaCert, fetchWithIdentity, generateKeypair, isDgUrl, refreshCaCert, registerIdentity, rotateIdentity, saveIdentity, version };
+export { type AuthConfig, AuthError, type Byok, type ChartOptions, Client, type ClientOptions, ConduitError, ConduitIdentity, type ConstrainOptions, type CreditEstimate, DEFAULT_IDENTITY_DIR, DG_CA_URL, DG_SUBSTRATE_ENDPOINT, type DiscoverOptions, type DiscoverResult, type FlowOptions, type ForgetOptions, type GuideOptions, type GuideRequestOptions, type GuideState, GuidedSession, InvalidConfigError, type Keypair, type MCPPrompt, type MCPResource, type MCPTool, type MtlsConfig, NetworkError, NotInitializedError, OAuthTokenProvider, type PerformOptions, type PerformResult, type PlanOptions, type PrismFocusOptions, type QueryCellOptions, type RateLimit, RateLimitError, type RateLimitStatus, type Receipt, type ReflectOptions, type RefractOptions, type RegisteredIdentity, type RegistrationOptions, type RememberOptions, type RenewalOptions, type RotationOptions, type SavedPaths, ServerError, Subscription, type SubscriptionEvent, type ToolInfo, type ToolMeta, SUBPROTOCOL as WS_SUBPROTOCOL, WsTransport, deriveTokenEndpoint, extractMeta, fetchDgCaCert, fetchWithIdentity, generateKeypair, isDgUrl, refreshCaCert, registerIdentity, rotateIdentity, saveIdentity, version };

package/dist/index.d.ts

@@ -256,6 +256,7 @@ interface GuideState {
 }
 interface AuthConfig {
     bearer?: string;
+    apiKey?: string;
     basic?: {
         username: string;
         password: string;
@@ -321,7 +322,7 @@ interface ClientOptions {
      * @default false
      */
     disableMtls?: boolean;
-    transport?: 'mcp' | 'jsonrpc';
+    transport?: 'mcp' | 'jsonrpc' | 'websocket';
     timeout?: number;
     /**
      * Maximum number of automatic retries on "server not initialized" errors.
@@ -461,6 +462,136 @@ interface MCPPrompt {
     }>;
 }
 
+/**
+ * Base transport interface
+ */
+
+declare abstract class Transport {
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract listTools(options?: any): Promise<MCPTool[]>;
+    abstract callTool(name: string, args: Record<string, any>, options?: any): Promise<any>;
+    abstract listResources(options?: any): Promise<MCPResource[]>;
+    abstract readResource(uri: string, options?: any): Promise<any>;
+    abstract listPrompts(options?: any): Promise<MCPPrompt[]>;
+    abstract getPrompt(name: string, args?: Record<string, any>, options?: any): Promise<any>;
+}
+
+/**
+ * WebSocket transport for `datagrout-jsonrpc.v1`.
+ *
+ * Recommended for any client that needs bidirectional push (server-initiated
+ * notifications) without a polling loop. A single `wss://` connection is
+ * multiplexed for all in-flight requests; concurrent calls are correlated by
+ * JSON-RPC `id` with no head-of-line blocking.
+ *
+ * @example
+ * ```ts
+ * const client = new Client({
+ *   url: 'wss://gateway.datagrout.ai/servers/<uuid>/ws',
+ *   transport: 'websocket',
+ *   auth: { bearer: 'your-token' },
+ * });
+ * await client.connect();
+ *
+ * // Push subscription
+ * const sub = await client.subscribe('agents.my-agent-id.events');
+ * for await (const event of sub) {
+ *   console.log(event.event, event.data);
+ * }
+ * await client.unsubscribe(sub.id);
+ * ```
+ *
+ * @module
+ */
+
+declare const SUBPROTOCOL = "datagrout-jsonrpc.v1";
+/** A single server-pushed notification. */
+interface SubscriptionEvent {
+    /** The subscription id this event belongs to. */
+    subscription: string;
+    /** Server-named event slug (e.g. `"agent.thought"`). */
+    event: string;
+    /** Free-form payload from the server. */
+    data: unknown;
+}
+/**
+ * Handle for an active server-push subscription.
+ *
+ * Consume events with {@link Subscription.recv} or an async-for loop:
+ * ```ts
+ * for await (const event of sub) {
+ *   handle(event);
+ * }
+ * ```
+ */
+declare class Subscription {
+    readonly id: string;
+    readonly topic: string;
+    private _queue;
+    private _waiters;
+    private _rejecters;
+    private _closed;
+    constructor(id: string, topic: string);
+    /**
+     * Wait for the next event from this subscription.
+     *
+     * @throws When the subscription has been closed.
+     */
+    recv(): Promise<SubscriptionEvent>;
+    [Symbol.asyncIterator](): AsyncGenerator<SubscriptionEvent>;
+    _enqueue(event: SubscriptionEvent): void;
+    _close(): void;
+}
+/**
+ * JSON-RPC 2.0 over WebSocket transport (`datagrout-jsonrpc.v1`).
+ *
+ * Multiplexes any number of in-flight requests on one socket and routes
+ * server-pushed notifications back to {@link Subscription} queues.
+ */
+declare class WsTransport extends Transport {
+    private readonly _url;
+    private readonly _auth?;
+    private _ws;
+    private _nextId;
+    private readonly _pending;
+    private readonly _pendingSubscribe;
+    private readonly _subscriptions;
+    constructor(url: string, auth?: AuthConfig, _timeout?: number, _identity?: ConduitIdentity);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Open a server-side push subscription for `topic`.
+     *
+     * @param topic - Dotted namespace topic, e.g.
+     *   `"agents.my-agent-id.events"` or `"tasks.task-123.*"`.
+     * @returns A {@link Subscription} handle whose async-for loop delivers events.
+     */
+    subscribe(topic: string): Promise<Subscription>;
+    /**
+     * Cancel a server-side subscription.
+     *
+     * The local {@link Subscription} queue is closed immediately.
+     *
+     * @param subscriptionId - The `id` field from the {@link Subscription}
+     *   returned by {@link subscribe}.
+     */
+    unsubscribe(subscriptionId: string): Promise<void>;
+    listTools(options?: any): Promise<MCPTool[]>;
+    callTool(name: string, args: Record<string, any>, _options?: any): Promise<any>;
+    listResources(_options?: any): Promise<MCPResource[]>;
+    readResource(uri: string, _options?: any): Promise<any>;
+    listPrompts(_options?: any): Promise<MCPPrompt[]>;
+    getPrompt(name: string, args?: Record<string, any>, _options?: any): Promise<any>;
+    private _mintId;
+    private _requireConnected;
+    private _send;
+    private _request;
+    private _handleMessage;
+    private _routeNotification;
+    private _failAll;
+}
+
 /**
  * Prism namespace — data transformation, charting, rendering, and export.
  */
@@ -842,6 +973,33 @@ declare class Client {
      * @param args - Template argument values.
      */
     getPrompt(name: string, args?: Record<string, any>, options?: any): Promise<any>;
+    /**
+     * Subscribe to a server-push topic (WebSocket transport only).
+     *
+     * Requires `transport: 'websocket'` when constructing the client.
+     *
+     * @param topic - Dotted namespace topic, e.g.
+     *   `"agents.my-agent-id.events"` or `"tasks.task-123.*"`.
+     * @returns A {@link Subscription} handle. Consume events with
+     *   {@link Subscription.recv} or an `for await` loop.
+     *
+     * @example
+     * ```ts
+     * const sub = await client.subscribe('agents.my-agent-id.events');
+     * for await (const event of sub) {
+     *   console.log(event.event, event.data);
+     * }
+     * await client.unsubscribe(sub.id);
+     * ```
+     */
+    subscribe(topic: string): Promise<Subscription>;
+    /**
+     * Cancel a server-side push subscription.
+     *
+     * @param subscriptionId - The `id` from the {@link Subscription} returned
+     *   by {@link subscribe}.
+     */
+    unsubscribe(subscriptionId: string): Promise<void>;
     private warnIfNotDg;
     /**
      * Semantically discover tools relevant to a goal or query.
@@ -1223,6 +1381,6 @@ declare class InvalidConfigError extends ConduitError {
  * DataGrout Conduit SDK for TypeScript/JavaScript
  */
 
-declare const version = "0.1.0";
+declare const version = "0.4.0";
 
-export { type AuthConfig, AuthError, type Byok, type ChartOptions, Client, type ClientOptions, ConduitError, ConduitIdentity, type ConstrainOptions, type CreditEstimate, DEFAULT_IDENTITY_DIR, DG_CA_URL, DG_SUBSTRATE_ENDPOINT, type DiscoverOptions, type DiscoverResult, type FlowOptions, type ForgetOptions, type GuideOptions, type GuideRequestOptions, type GuideState, GuidedSession, InvalidConfigError, type Keypair, type MCPPrompt, type MCPResource, type MCPTool, type MtlsConfig, NetworkError, NotInitializedError, OAuthTokenProvider, type PerformOptions, type PerformResult, type PlanOptions, type PrismFocusOptions, type QueryCellOptions, type RateLimit, RateLimitError, type RateLimitStatus, type Receipt, type ReflectOptions, type RefractOptions, type RegisteredIdentity, type RegistrationOptions, type RememberOptions, type RenewalOptions, type RotationOptions, type SavedPaths, ServerError, type ToolInfo, type ToolMeta, deriveTokenEndpoint, extractMeta, fetchDgCaCert, fetchWithIdentity, generateKeypair, isDgUrl, refreshCaCert, registerIdentity, rotateIdentity, saveIdentity, version };
+export { type AuthConfig, AuthError, type Byok, type ChartOptions, Client, type ClientOptions, ConduitError, ConduitIdentity, type ConstrainOptions, type CreditEstimate, DEFAULT_IDENTITY_DIR, DG_CA_URL, DG_SUBSTRATE_ENDPOINT, type DiscoverOptions, type DiscoverResult, type FlowOptions, type ForgetOptions, type GuideOptions, type GuideRequestOptions, type GuideState, GuidedSession, InvalidConfigError, type Keypair, type MCPPrompt, type MCPResource, type MCPTool, type MtlsConfig, NetworkError, NotInitializedError, OAuthTokenProvider, type PerformOptions, type PerformResult, type PlanOptions, type PrismFocusOptions, type QueryCellOptions, type RateLimit, RateLimitError, type RateLimitStatus, type Receipt, type ReflectOptions, type RefractOptions, type RegisteredIdentity, type RegistrationOptions, type RememberOptions, type RenewalOptions, type RotationOptions, type SavedPaths, ServerError, Subscription, type SubscriptionEvent, type ToolInfo, type ToolMeta, SUBPROTOCOL as WS_SUBPROTOCOL, WsTransport, deriveTokenEndpoint, extractMeta, fetchDgCaCert, fetchWithIdentity, generateKeypair, isDgUrl, refreshCaCert, registerIdentity, rotateIdentity, saveIdentity, version };

package/dist/index.js

@@ -360,6 +360,8 @@ __export(index_exports, {
   OAuthTokenProvider: () => OAuthTokenProvider,
   RateLimitError: () => RateLimitError,
   ServerError: () => ServerError,
+  WS_SUBPROTOCOL: () => SUBPROTOCOL,
+  WsTransport: () => WsTransport,
   deriveTokenEndpoint: () => deriveTokenEndpoint,
   extractMeta: () => extractMeta,
   fetchDgCaCert: () => fetchDgCaCert,
@@ -727,6 +729,295 @@ var JSONRPCTransport = class extends Transport {
   }
 };
 
+// src/transports/ws.ts
+var SUBPROTOCOL = "datagrout-jsonrpc.v1";
+var SUBSCRIPTION_BUFFER = 256;
+var Subscription = class {
+  id;
+  topic;
+  _queue = [];
+  _waiters = [];
+  _rejecters = [];
+  _closed = false;
+  constructor(id, topic) {
+    this.id = id;
+    this.topic = topic;
+  }
+  /**
+   * Wait for the next event from this subscription.
+   *
+   * @throws When the subscription has been closed.
+   */
+  recv() {
+    if (this._queue.length > 0) {
+      return Promise.resolve(this._queue.shift());
+    }
+    if (this._closed) {
+      return Promise.reject(new Error("Subscription closed"));
+    }
+    return new Promise((resolve, reject) => {
+      this._waiters.push(resolve);
+      this._rejecters.push(reject);
+    });
+  }
+  async *[Symbol.asyncIterator]() {
+    while (this._queue.length > 0 || !this._closed) {
+      try {
+        yield await this.recv();
+      } catch {
+        return;
+      }
+    }
+  }
+  // ── Internal ───────────────────────────────────────────────────────────────
+  _enqueue(event) {
+    if (this._waiters.length > 0) {
+      const resolve = this._waiters.shift();
+      this._rejecters.shift();
+      resolve(event);
+    } else if (this._queue.length < SUBSCRIPTION_BUFFER) {
+      this._queue.push(event);
+    }
+  }
+  _close() {
+    this._closed = true;
+    const err = new Error("Subscription closed");
+    for (const reject of this._rejecters) {
+      reject(err);
+    }
+    this._waiters.length = 0;
+    this._rejecters.length = 0;
+  }
+};
+var WsTransport = class extends Transport {
+  _url;
+  _auth;
+  _ws = null;
+  _nextId = 0;
+  _pending = /* @__PURE__ */ new Map();
+  _pendingSubscribe = /* @__PURE__ */ new Map();
+  _subscriptions = /* @__PURE__ */ new Map();
+  constructor(url, auth, _timeout, _identity) {
+    super();
+    const scheme = new URL(url).protocol.replace(":", "");
+    if (scheme !== "ws" && scheme !== "wss") {
+      throw new Error(`WS transport requires a ws:// or wss:// URL, got ${scheme}://`);
+    }
+    this._url = url;
+    this._auth = auth;
+  }
+  // ── Lifecycle ─────────────────────────────────────────────────────────────
+  async connect() {
+    if (this._ws !== null) return;
+    const WsImpl = await resolveWebSocketImpl();
+    const headers = buildUpgradeHeaders(this._auth);
+    const ws = new WsImpl(this._url, [SUBPROTOCOL], {
+      headers
+    });
+    await new Promise((resolve, reject) => {
+      ws.onopen = () => resolve();
+      ws.onerror = (ev) => reject(new Error(`WS connect failed: ${ev.message ?? "unknown"}`));
+    });
+    ws.onmessage = (ev) => this._handleMessage(ev.data);
+    ws.onerror = (_ev) => this._failAll("WS connection error");
+    ws.onclose = () => {
+      this._failAll("WS connection closed");
+      this._ws = null;
+    };
+    this._ws = ws;
+  }
+  async disconnect() {
+    const ws = this._ws;
+    this._ws = null;
+    this._failAll("WS connection closed");
+    if (ws !== null) {
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+  }
+  // ── Subscriptions ─────────────────────────────────────────────────────────
+  /**
+   * Open a server-side push subscription for `topic`.
+   *
+   * @param topic - Dotted namespace topic, e.g.
+   *   `"agents.my-agent-id.events"` or `"tasks.task-123.*"`.
+   * @returns A {@link Subscription} handle whose async-for loop delivers events.
+   */
+  async subscribe(topic) {
+    this._requireConnected();
+    const id = this._mintId();
+    return new Promise((resolve, reject) => {
+      this._pendingSubscribe.set(id, { topic, resolve, reject });
+      this._send({ jsonrpc: "2.0", id, method: "subscribe", params: { topic } });
+    });
+  }
+  /**
+   * Cancel a server-side subscription.
+   *
+   * The local {@link Subscription} queue is closed immediately.
+   *
+   * @param subscriptionId - The `id` field from the {@link Subscription}
+   *   returned by {@link subscribe}.
+   */
+  async unsubscribe(subscriptionId) {
+    this._requireConnected();
+    const sub = this._subscriptions.get(subscriptionId);
+    if (sub !== void 0) {
+      this._subscriptions.delete(subscriptionId);
+      sub._close();
+    }
+    const id = this._mintId();
+    const ackPromise = new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+    });
+    this._send({
+      jsonrpc: "2.0",
+      id,
+      method: "unsubscribe",
+      params: { subscription: subscriptionId }
+    });
+    await Promise.race([
+      ackPromise,
+      new Promise((resolve) => setTimeout(resolve, 5e3))
+    ]);
+    this._pending.delete(id);
+  }
+  // ── Transport base implementation ─────────────────────────────────────────
+  async listTools(options) {
+    return await this._request("tools/list", options);
+  }
+  async callTool(name, args, _options) {
+    return this._request("tools/call", { name, arguments: args });
+  }
+  async listResources(_options) {
+    return await this._request("resources/list");
+  }
+  async readResource(uri, _options) {
+    return this._request("resources/read", { uri });
+  }
+  async listPrompts(_options) {
+    return await this._request("prompts/list");
+  }
+  async getPrompt(name, args, _options) {
+    return this._request("prompts/get", { name, arguments: args });
+  }
+  // ── Internal ──────────────────────────────────────────────────────────────
+  _mintId() {
+    return `ws-${++this._nextId}`;
+  }
+  _requireConnected() {
+    if (this._ws === null) {
+      throw new Error("WS transport not connected. Call connect() first.");
+    }
+  }
+  _send(payload) {
+    this._ws.send(JSON.stringify(payload));
+  }
+  async _request(method, params) {
+    this._requireConnected();
+    const id = this._mintId();
+    return new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+      this._send({ jsonrpc: "2.0", id, method, ...params !== void 0 ? { params } : {} });
+    });
+  }
+  _handleMessage(data) {
+    let msg;
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (!("id" in msg)) {
+      if (msg["method"] === "notification") {
+        this._routeNotification(msg["params"]);
+      }
+      return;
+    }
+    const msgId = String(msg["id"]);
+    const pendingSub = this._pendingSubscribe.get(msgId);
+    if (pendingSub !== void 0) {
+      this._pendingSubscribe.delete(msgId);
+      const err = msg["error"];
+      if (err !== void 0) {
+        pendingSub.reject(new Error(String(err["message"] ?? "Subscribe failed")));
+        return;
+      }
+      const result = msg["result"] ?? {};
+      const subId = String(result["subscription"] ?? msgId);
+      const sub = new Subscription(subId, pendingSub.topic);
+      this._subscriptions.set(subId, sub);
+      pendingSub.resolve(sub);
+      return;
+    }
+    const pending = this._pending.get(msgId);
+    if (pending !== void 0) {
+      this._pending.delete(msgId);
+      const err = msg["error"];
+      if (err !== void 0) {
+        pending.reject(new Error(String(err["message"] ?? "RPC error")));
+      } else {
+        pending.resolve(msg["result"]);
+      }
+    }
+  }
+  _routeNotification(params) {
+    if (params === void 0) return;
+    const subId = params["subscription"];
+    if (typeof subId !== "string") return;
+    const sub = this._subscriptions.get(subId);
+    if (sub === void 0) return;
+    sub._enqueue({
+      subscription: subId,
+      event: String(params["event"] ?? ""),
+      data: params["data"]
+    });
+  }
+  _failAll(reason) {
+    const err = new Error(reason);
+    for (const { reject } of this._pending.values()) {
+      reject(err);
+    }
+    this._pending.clear();
+    for (const { reject } of this._pendingSubscribe.values()) {
+      reject(err);
+    }
+    this._pendingSubscribe.clear();
+    for (const sub of this._subscriptions.values()) {
+      sub._close();
+    }
+    this._subscriptions.clear();
+  }
+};
+function buildUpgradeHeaders(auth) {
+  const headers = {};
+  if (auth === void 0) return headers;
+  if ("bearer" in auth && auth.bearer !== void 0) {
+    headers["Authorization"] = `Bearer ${auth.bearer}`;
+  } else if ("apiKey" in auth && auth.apiKey !== void 0) {
+    headers["X-API-Key"] = auth.apiKey;
+  } else if ("basic" in auth && auth.basic !== void 0) {
+    const encoded = Buffer.from(`${auth.basic.username}:${auth.basic.password}`).toString("base64");
+    headers["Authorization"] = `Basic ${encoded}`;
+  }
+  return headers;
+}
+async function resolveWebSocketImpl() {
+  if (typeof globalThis.WebSocket !== "undefined") {
+    return globalThis.WebSocket;
+  }
+  try {
+    const { default: WS } = await import("ws");
+    return WS;
+  } catch {
+    throw new Error(
+      "No WebSocket implementation found. Install the 'ws' package: npm install ws"
+    );
+  }
+}
+
 // src/client.ts
 init_identity();
 
@@ -1254,6 +1545,11 @@ var Client2 = class _Client {
     const transportType = options.transport || "mcp";
     if (transportType === "mcp") {
       this.transport = new MCPTransport(this.url, this.auth, identity);
+    } else if (transportType === "websocket") {
+      let wsUrl = this.url;
+      if (wsUrl.startsWith("https://")) wsUrl = "wss://" + wsUrl.slice(8);
+      else if (wsUrl.startsWith("http://")) wsUrl = "ws://" + wsUrl.slice(7);
+      this.transport = new WsTransport(wsUrl, this.auth, options.timeout, identity);
     } else {
       const rpcUrl = this.url.endsWith("/mcp") ? this.url.slice(0, -4) + "/rpc" : this.url;
       this.transport = new JSONRPCTransport(rpcUrl, this.auth, options.timeout, identity);
@@ -1488,6 +1784,50 @@ var Client2 = class _Client {
     this.ensureInitialized();
     return this.sendWithRetry(() => this.transport.getPrompt(name, args, options));
   }
+  // ===== WebSocket push subscriptions =====
+  /**
+   * Subscribe to a server-push topic (WebSocket transport only).
+   *
+   * Requires `transport: 'websocket'` when constructing the client.
+   *
+   * @param topic - Dotted namespace topic, e.g.
+   *   `"agents.my-agent-id.events"` or `"tasks.task-123.*"`.
+   * @returns A {@link Subscription} handle. Consume events with
+   *   {@link Subscription.recv} or an `for await` loop.
+   *
+   * @example
+   * ```ts
+   * const sub = await client.subscribe('agents.my-agent-id.events');
+   * for await (const event of sub) {
+   *   console.log(event.event, event.data);
+   * }
+   * await client.unsubscribe(sub.id);
+   * ```
+   */
+  async subscribe(topic) {
+    this.ensureInitialized();
+    if (!(this.transport instanceof WsTransport)) {
+      throw new Error(
+        "subscribe() requires transport: 'websocket'. Reinitialise the client with transport: 'websocket'."
+      );
+    }
+    return this.transport.subscribe(topic);
+  }
+  /**
+   * Cancel a server-side push subscription.
+   *
+   * @param subscriptionId - The `id` from the {@link Subscription} returned
+   *   by {@link subscribe}.
+   */
+  async unsubscribe(subscriptionId) {
+    this.ensureInitialized();
+    if (!(this.transport instanceof WsTransport)) {
+      throw new Error(
+        "unsubscribe() requires transport: 'websocket'. Reinitialise the client with transport: 'websocket'."
+      );
+    }
+    return this.transport.unsubscribe(subscriptionId);
+  }
   // ===== DG-awareness helpers =====
   warnIfNotDg(method) {
     if (!this.isDg && !this.dgWarned) {
@@ -1778,7 +2118,7 @@ function buildToolMeta(raw) {
 }
 
 // src/index.ts
-var version = "0.1.0";
+var version = "0.4.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthError,
@@ -1795,6 +2135,8 @@ var version = "0.1.0";
   OAuthTokenProvider,
   RateLimitError,
   ServerError,
+  WS_SUBPROTOCOL,
+  WsTransport,
   deriveTokenEndpoint,
   extractMeta,
   fetchDgCaCert,

package/dist/index.mjs

@@ -589,6 +589,295 @@ var JSONRPCTransport = class extends Transport {
   }
 };
 
+// src/transports/ws.ts
+var SUBPROTOCOL = "datagrout-jsonrpc.v1";
+var SUBSCRIPTION_BUFFER = 256;
+var Subscription = class {
+  id;
+  topic;
+  _queue = [];
+  _waiters = [];
+  _rejecters = [];
+  _closed = false;
+  constructor(id, topic) {
+    this.id = id;
+    this.topic = topic;
+  }
+  /**
+   * Wait for the next event from this subscription.
+   *
+   * @throws When the subscription has been closed.
+   */
+  recv() {
+    if (this._queue.length > 0) {
+      return Promise.resolve(this._queue.shift());
+    }
+    if (this._closed) {
+      return Promise.reject(new Error("Subscription closed"));
+    }
+    return new Promise((resolve, reject) => {
+      this._waiters.push(resolve);
+      this._rejecters.push(reject);
+    });
+  }
+  async *[Symbol.asyncIterator]() {
+    while (this._queue.length > 0 || !this._closed) {
+      try {
+        yield await this.recv();
+      } catch {
+        return;
+      }
+    }
+  }
+  // ── Internal ───────────────────────────────────────────────────────────────
+  _enqueue(event) {
+    if (this._waiters.length > 0) {
+      const resolve = this._waiters.shift();
+      this._rejecters.shift();
+      resolve(event);
+    } else if (this._queue.length < SUBSCRIPTION_BUFFER) {
+      this._queue.push(event);
+    }
+  }
+  _close() {
+    this._closed = true;
+    const err = new Error("Subscription closed");
+    for (const reject of this._rejecters) {
+      reject(err);
+    }
+    this._waiters.length = 0;
+    this._rejecters.length = 0;
+  }
+};
+var WsTransport = class extends Transport {
+  _url;
+  _auth;
+  _ws = null;
+  _nextId = 0;
+  _pending = /* @__PURE__ */ new Map();
+  _pendingSubscribe = /* @__PURE__ */ new Map();
+  _subscriptions = /* @__PURE__ */ new Map();
+  constructor(url, auth, _timeout, _identity) {
+    super();
+    const scheme = new URL(url).protocol.replace(":", "");
+    if (scheme !== "ws" && scheme !== "wss") {
+      throw new Error(`WS transport requires a ws:// or wss:// URL, got ${scheme}://`);
+    }
+    this._url = url;
+    this._auth = auth;
+  }
+  // ── Lifecycle ─────────────────────────────────────────────────────────────
+  async connect() {
+    if (this._ws !== null) return;
+    const WsImpl = await resolveWebSocketImpl();
+    const headers = buildUpgradeHeaders(this._auth);
+    const ws = new WsImpl(this._url, [SUBPROTOCOL], {
+      headers
+    });
+    await new Promise((resolve, reject) => {
+      ws.onopen = () => resolve();
+      ws.onerror = (ev) => reject(new Error(`WS connect failed: ${ev.message ?? "unknown"}`));
+    });
+    ws.onmessage = (ev) => this._handleMessage(ev.data);
+    ws.onerror = (_ev) => this._failAll("WS connection error");
+    ws.onclose = () => {
+      this._failAll("WS connection closed");
+      this._ws = null;
+    };
+    this._ws = ws;
+  }
+  async disconnect() {
+    const ws = this._ws;
+    this._ws = null;
+    this._failAll("WS connection closed");
+    if (ws !== null) {
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+  }
+  // ── Subscriptions ─────────────────────────────────────────────────────────
+  /**
+   * Open a server-side push subscription for `topic`.
+   *
+   * @param topic - Dotted namespace topic, e.g.
+   *   `"agents.my-agent-id.events"` or `"tasks.task-123.*"`.
+   * @returns A {@link Subscription} handle whose async-for loop delivers events.
+   */
+  async subscribe(topic) {
+    this._requireConnected();
+    const id = this._mintId();
+    return new Promise((resolve, reject) => {
+      this._pendingSubscribe.set(id, { topic, resolve, reject });
+      this._send({ jsonrpc: "2.0", id, method: "subscribe", params: { topic } });
+    });
+  }
+  /**
+   * Cancel a server-side subscription.
+   *
+   * The local {@link Subscription} queue is closed immediately.
+   *
+   * @param subscriptionId - The `id` field from the {@link Subscription}
+   *   returned by {@link subscribe}.
+   */
+  async unsubscribe(subscriptionId) {
+    this._requireConnected();
+    const sub = this._subscriptions.get(subscriptionId);
+    if (sub !== void 0) {
+      this._subscriptions.delete(subscriptionId);
+      sub._close();
+    }
+    const id = this._mintId();
+    const ackPromise = new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+    });
+    this._send({
+      jsonrpc: "2.0",
+      id,
+      method: "unsubscribe",
+      params: { subscription: subscriptionId }
+    });
+    await Promise.race([
+      ackPromise,
+      new Promise((resolve) => setTimeout(resolve, 5e3))
+    ]);
+    this._pending.delete(id);
+  }
+  // ── Transport base implementation ─────────────────────────────────────────
+  async listTools(options) {
+    return await this._request("tools/list", options);
+  }
+  async callTool(name, args, _options) {
+    return this._request("tools/call", { name, arguments: args });
+  }
+  async listResources(_options) {
+    return await this._request("resources/list");
+  }
+  async readResource(uri, _options) {
+    return this._request("resources/read", { uri });
+  }
+  async listPrompts(_options) {
+    return await this._request("prompts/list");
+  }
+  async getPrompt(name, args, _options) {
+    return this._request("prompts/get", { name, arguments: args });
+  }
+  // ── Internal ──────────────────────────────────────────────────────────────
+  _mintId() {
+    return `ws-${++this._nextId}`;
+  }
+  _requireConnected() {
+    if (this._ws === null) {
+      throw new Error("WS transport not connected. Call connect() first.");
+    }
+  }
+  _send(payload) {
+    this._ws.send(JSON.stringify(payload));
+  }
+  async _request(method, params) {
+    this._requireConnected();
+    const id = this._mintId();
+    return new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+      this._send({ jsonrpc: "2.0", id, method, ...params !== void 0 ? { params } : {} });
+    });
+  }
+  _handleMessage(data) {
+    let msg;
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (!("id" in msg)) {
+      if (msg["method"] === "notification") {
+        this._routeNotification(msg["params"]);
+      }
+      return;
+    }
+    const msgId = String(msg["id"]);
+    const pendingSub = this._pendingSubscribe.get(msgId);
+    if (pendingSub !== void 0) {
+      this._pendingSubscribe.delete(msgId);
+      const err = msg["error"];
+      if (err !== void 0) {
+        pendingSub.reject(new Error(String(err["message"] ?? "Subscribe failed")));
+        return;
+      }
+      const result = msg["result"] ?? {};
+      const subId = String(result["subscription"] ?? msgId);
+      const sub = new Subscription(subId, pendingSub.topic);
+      this._subscriptions.set(subId, sub);
+      pendingSub.resolve(sub);
+      return;
+    }
+    const pending = this._pending.get(msgId);
+    if (pending !== void 0) {
+      this._pending.delete(msgId);
+      const err = msg["error"];
+      if (err !== void 0) {
+        pending.reject(new Error(String(err["message"] ?? "RPC error")));
+      } else {
+        pending.resolve(msg["result"]);
+      }
+    }
+  }
+  _routeNotification(params) {
+    if (params === void 0) return;
+    const subId = params["subscription"];
+    if (typeof subId !== "string") return;
+    const sub = this._subscriptions.get(subId);
+    if (sub === void 0) return;
+    sub._enqueue({
+      subscription: subId,
+      event: String(params["event"] ?? ""),
+      data: params["data"]
+    });
+  }
+  _failAll(reason) {
+    const err = new Error(reason);
+    for (const { reject } of this._pending.values()) {
+      reject(err);
+    }
+    this._pending.clear();
+    for (const { reject } of this._pendingSubscribe.values()) {
+      reject(err);
+    }
+    this._pendingSubscribe.clear();
+    for (const sub of this._subscriptions.values()) {
+      sub._close();
+    }
+    this._subscriptions.clear();
+  }
+};
+function buildUpgradeHeaders(auth) {
+  const headers = {};
+  if (auth === void 0) return headers;
+  if ("bearer" in auth && auth.bearer !== void 0) {
+    headers["Authorization"] = `Bearer ${auth.bearer}`;
+  } else if ("apiKey" in auth && auth.apiKey !== void 0) {
+    headers["X-API-Key"] = auth.apiKey;
+  } else if ("basic" in auth && auth.basic !== void 0) {
+    const encoded = Buffer.from(`${auth.basic.username}:${auth.basic.password}`).toString("base64");
+    headers["Authorization"] = `Basic ${encoded}`;
+  }
+  return headers;
+}
+async function resolveWebSocketImpl() {
+  if (typeof globalThis.WebSocket !== "undefined") {
+    return globalThis.WebSocket;
+  }
+  try {
+    const { default: WS } = await import("ws");
+    return WS;
+  } catch {
+    throw new Error(
+      "No WebSocket implementation found. Install the 'ws' package: npm install ws"
+    );
+  }
+}
+
 // src/client.ts
 init_identity();
 
@@ -1116,6 +1405,11 @@ var Client2 = class _Client {
     const transportType = options.transport || "mcp";
     if (transportType === "mcp") {
       this.transport = new MCPTransport(this.url, this.auth, identity);
+    } else if (transportType === "websocket") {
+      let wsUrl = this.url;
+      if (wsUrl.startsWith("https://")) wsUrl = "wss://" + wsUrl.slice(8);
+      else if (wsUrl.startsWith("http://")) wsUrl = "ws://" + wsUrl.slice(7);
+      this.transport = new WsTransport(wsUrl, this.auth, options.timeout, identity);
     } else {
       const rpcUrl = this.url.endsWith("/mcp") ? this.url.slice(0, -4) + "/rpc" : this.url;
       this.transport = new JSONRPCTransport(rpcUrl, this.auth, options.timeout, identity);
@@ -1350,6 +1644,50 @@ var Client2 = class _Client {
     this.ensureInitialized();
     return this.sendWithRetry(() => this.transport.getPrompt(name, args, options));
   }
+  // ===== WebSocket push subscriptions =====
+  /**
+   * Subscribe to a server-push topic (WebSocket transport only).
+   *
+   * Requires `transport: 'websocket'` when constructing the client.
+   *
+   * @param topic - Dotted namespace topic, e.g.
+   *   `"agents.my-agent-id.events"` or `"tasks.task-123.*"`.
+   * @returns A {@link Subscription} handle. Consume events with
+   *   {@link Subscription.recv} or an `for await` loop.
+   *
+   * @example
+   * ```ts
+   * const sub = await client.subscribe('agents.my-agent-id.events');
+   * for await (const event of sub) {
+   *   console.log(event.event, event.data);
+   * }
+   * await client.unsubscribe(sub.id);
+   * ```
+   */
+  async subscribe(topic) {
+    this.ensureInitialized();
+    if (!(this.transport instanceof WsTransport)) {
+      throw new Error(
+        "subscribe() requires transport: 'websocket'. Reinitialise the client with transport: 'websocket'."
+      );
+    }
+    return this.transport.subscribe(topic);
+  }
+  /**
+   * Cancel a server-side push subscription.
+   *
+   * @param subscriptionId - The `id` from the {@link Subscription} returned
+   *   by {@link subscribe}.
+   */
+  async unsubscribe(subscriptionId) {
+    this.ensureInitialized();
+    if (!(this.transport instanceof WsTransport)) {
+      throw new Error(
+        "unsubscribe() requires transport: 'websocket'. Reinitialise the client with transport: 'websocket'."
+      );
+    }
+    return this.transport.unsubscribe(subscriptionId);
+  }
   // ===== DG-awareness helpers =====
   warnIfNotDg(method) {
     if (!this.isDg && !this.dgWarned) {
@@ -1640,7 +1978,7 @@ function buildToolMeta(raw) {
 }
 
 // src/index.ts
-var version = "0.1.0";
+var version = "0.4.0";
 export {
   AuthError,
   Client2 as Client,
@@ -1656,6 +1994,8 @@ export {
   OAuthTokenProvider,
   RateLimitError,
   ServerError,
+  SUBPROTOCOL as WS_SUBPROTOCOL,
+  WsTransport,
   deriveTokenEndpoint,
   extractMeta,
   fetchDgCaCert,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datagrout/conduit",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Production-ready MCP client with mTLS, OAuth 2.1, and semantic discovery",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -45,10 +45,12 @@
     "url": "https://github.com/DataGrout/conduit-sdk/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",
+    "@types/ws": "^8.5.10",
     "@typescript-eslint/eslint-plugin": "^6.19.0",
     "@typescript-eslint/parser": "^6.19.0",
     "eslint": "^8.56.0",