@datagrout/conduit 0.3.0 → 0.5.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.5.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/{chunk-RED5DKGI.mjs → chunk-26DYCD4G.mjs}

@@ -1,29 +1,7 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+import {
+  __esm,
+  __export
+} from "./chunk-CIESM3BP.mjs";
 
 // src/oauth.ts
 var oauth_exports = {};
@@ -111,10 +89,6 @@ var init_oauth = __esm({
 });
 
 export {
-  __require,
-  __esm,
-  __export,
-  __toCommonJS,
   deriveTokenEndpoint,
   OAuthTokenProvider,
   oauth_exports,

package/dist/chunk-CIESM3BP.mjs

@@ -0,0 +1,33 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+export {
+  __require,
+  __esm,
+  __export,
+  __toCommonJS
+};

package/dist/chunk-SWH5Y2U7.mjs

@@ -0,0 +1,69 @@
+// src/onramp.ts
+async function _doRegister(opts) {
+  const base = opts.gateway.replace(/\/$/, "");
+  const body = { agent_name: opts.agentName };
+  if (opts.agentType) body["agent_type"] = opts.agentType;
+  if (opts.intendedUse) body["intended_use"] = opts.intendedUse;
+  if (opts.accessCode) body["access_code"] = opts.accessCode;
+  const initResp = await fetch(`${base}/onramp`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!initResp.ok) {
+    const text = await initResp.text();
+    throw new Error(`onramp init rejected (HTTP ${initResp.status}): ${text}`);
+  }
+  const initData = await initResp.json();
+  const sessionToken = initData.session_token;
+  const completeResp = await fetch(`${base}/onramp/complete`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${sessionToken}` }
+  });
+  if (!completeResp.ok) {
+    const text = await completeResp.text();
+    throw new Error(`onramp complete rejected (HTTP ${completeResp.status}): ${text}`);
+  }
+  const data = await completeResp.json();
+  return {
+    clientId: data["client_id"],
+    clientSecret: data["client_secret"],
+    tokenUrl: data["token_url"],
+    scopes: data["scopes"] ?? [],
+    expiresIn: data["expires_in"] ?? 0,
+    rpcUrl: data["rpc_url"],
+    mcpUrl: data["mcp_url"]
+  };
+}
+async function _exchangeToken(creds) {
+  const body = new URLSearchParams({
+    grant_type: "client_credentials",
+    client_id: creds.clientId,
+    client_secret: creds.clientSecret
+  });
+  const resp = await fetch(creds.tokenUrl, {
+    method: "POST",
+    body
+  });
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`token exchange failed (HTTP ${resp.status}): ${text}`);
+  }
+  const data = await resp.json();
+  return data.access_token;
+}
+async function registerOnly(opts) {
+  return _doRegister(opts);
+}
+async function registerAndExchange(opts) {
+  const creds = await _doRegister(opts);
+  const token = await _exchangeToken(creds);
+  return [creds, token];
+}
+
+export {
+  _doRegister,
+  _exchangeToken,
+  registerOnly,
+  registerAndExchange
+};

package/dist/index.d.mts

@@ -1,3 +1,97 @@
+/**
+ * Autonomous agent self-registration (onramp) for DataGrout.
+ *
+ * The onramp flow lets a machine intelligence register itself with DG
+ * without a human in the loop, using only plain HTTP JSON — no MCP client
+ * required. This matters because many agent harnesses gate or restrict MCP
+ * connections but allow arbitrary HTTP requests.
+ *
+ * Flow
+ * ----
+ * 1. POST to `/onramp` with agent identity metadata (no auth).
+ * 2. DG returns a short-lived `session_token` (5 minutes).
+ * 3. POST to `/onramp/complete` with `Authorization: Bearer <session_token>`.
+ * 4. DG issues provisional `client_id` + `client_secret` (restricted scopes).
+ *
+ * @example
+ * ```ts
+ * import { Client } from './client';
+ * import { OnrampOptions } from './onramp';
+ *
+ * // One-shot: autonomous registration + mTLS bootstrap.
+ * const client = await Client.bootstrapOnramp({
+ *   opts: {
+ *     gateway: 'https://app.datagrout.ai',
+ *     agentName: 'my-research-agent',
+ *     agentType: 'claude-sonnet-4-6',
+ *     intendedUse: 'Summarise documents and extract entities.',
+ *   },
+ * });
+ * await client.connect();
+ * ```
+ */
+/** Options for the autonomous agent onramp flow. */
+interface OnrampOptions {
+    /** DataGrout gateway base URL (e.g. `"https://app.datagrout.ai"`). */
+    gateway: string;
+    /** Human-readable name for this agent instance. */
+    agentName: string;
+    /** Model or framework identifier (e.g. `"claude-sonnet-4-6"`, `"gpt-4o"`). */
+    agentType?: string;
+    /** Plain-language description of what the agent intends to do. */
+    intendedUse?: string;
+    /** Optional access code from the server owner — reserved for scope elevation. */
+    accessCode?: string;
+}
+/**
+ * Provisional credentials returned by the DG onramp complete endpoint.
+ *
+ * Store `clientId` and `clientSecret` securely — the secret is shown exactly
+ * once and cannot be recovered after this point.
+ *
+ * `mcpUrl` and `rpcUrl` are provisioned as part of the identity registration
+ * step and may be absent from the initial onramp response. Use
+ * `Client.bootstrapOnramp` for the all-in-one flow that handles this
+ * transparently.
+ */
+interface OnrampCredentials {
+    /** OAuth client ID. */
+    clientId: string;
+    /** OAuth client secret. Store this securely — shown once. */
+    clientSecret: string;
+    /** Token endpoint for the `client_credentials` grant. */
+    tokenUrl: string;
+    /** Granted OAuth scopes. */
+    scopes: string[];
+    /** Provisional credential TTL in seconds. */
+    expiresIn: number;
+    /** JSON-RPC endpoint. Absent until identity is registered. */
+    rpcUrl?: string;
+    /** MCP endpoint. Absent until identity is registered. */
+    mcpUrl?: string;
+}
+/**
+ * Perform the onramp handshake and return provisional OAuth credentials.
+ *
+ * This is the low-level entry point. Most callers should use
+ * `Client.bootstrapOnramp` instead, which chains onramp → token exchange →
+ * mTLS identity bootstrap in a single call.
+ *
+ * @param opts Onramp registration options.
+ * @returns `OnrampCredentials` containing `clientId` and `clientSecret`.
+ */
+declare function registerOnly(opts: OnrampOptions): Promise<OnrampCredentials>;
+/**
+ * Perform the full onramp handshake and OAuth token exchange.
+ *
+ * Returns the provisional credentials alongside a short-lived access token
+ * ready for use with `Client.bootstrapIdentity`.
+ *
+ * @param opts Onramp registration options.
+ * @returns Tuple of `[OnrampCredentials, accessToken]`.
+ */
+declare function registerAndExchange(opts: OnrampOptions): Promise<[OnrampCredentials, string]>;
+
 /**
  * Identity and mTLS support for Conduit connections.
  *
@@ -256,6 +350,7 @@ interface GuideState {
 }
 interface AuthConfig {
     bearer?: string;
+    apiKey?: string;
     basic?: {
         username: string;
         password: string;
@@ -294,6 +389,9 @@ interface ClientOptions {
      * `~/.conduit/` before falling back to token auth.  Equivalent to
      * calling `ConduitIdentity.tryDefault()` and passing the result as
      * `identity`.
+     *
+     * mTLS auto-discovery is **opt-in** — this flag must be set to enable it.
+     * DataGrout URLs do not auto-discover an identity by default.
      */
     identityAuto?: boolean;
     /**
@@ -312,16 +410,11 @@ interface ClientOptions {
      */
     useIntelligentInterface?: boolean;
     /**
-     * Disable automatic mTLS even for DataGrout URLs.
-     *
-     * By default, DG URLs (`*.datagrout.ai`) silently attempt to discover an
-     * mTLS identity from env vars or `~/.conduit/`.  Set to `true` to opt out
-     * and use token-only auth.
-     *
-     * @default false
+     * @deprecated No-op. mTLS auto-discovery is now opt-in via `identityAuto`.
+     * This option is kept for backward compatibility and has no effect.
      */
     disableMtls?: boolean;
-    transport?: 'mcp' | 'jsonrpc';
+    transport?: 'mcp' | 'jsonrpc' | 'websocket';
     timeout?: number;
     /**
      * Maximum number of automatic retries on "server not initialized" errors.
@@ -461,6 +554,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.
  */
@@ -759,6 +982,40 @@ declare class Client {
         identityDir?: string;
         substrateEndpoint?: string;
     }): Promise<Client>;
+    /**
+     * Register autonomously with DG and bootstrap an mTLS identity.
+     *
+     * The all-in-one flow: onramp (no prior credentials required) →
+     * OAuth token exchange → mTLS identity registration and persistence.
+     *
+     * On subsequent runs the saved mTLS identity is auto-discovered and
+     * no credentials are needed.
+     *
+     * @param options.opts         - Onramp registration options.
+     * @param options.url          - MCP server URL. Required if the onramp
+     *                               response does not include `mcpUrl`.
+     * @param options.identityDir  - Custom identity storage directory.
+     *
+     * @example
+     * ```ts
+     * import { Client } from './client';
+     * import type { OnrampOptions } from './onramp';
+     *
+     * const client = await Client.bootstrapOnramp({
+     *   opts: {
+     *     gateway: 'https://app.datagrout.ai',
+     *     agentName: 'my-research-agent',
+     *     agentType: 'claude-sonnet-4-6',
+     *   },
+     * });
+     * await client.connect();
+     * ```
+     */
+    static bootstrapOnramp(options: {
+        opts: OnrampOptions;
+        url?: string;
+        identityDir?: string;
+    }): Promise<Client>;
     /**
      * Establish the underlying transport connection.
      *
@@ -842,6 +1099,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 +1507,6 @@ declare class InvalidConfigError extends ConduitError {
  * DataGrout Conduit SDK for TypeScript/JavaScript
  */
 
-declare const version = "0.1.0";
+declare const version = "0.5.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 OnrampCredentials, type OnrampOptions, 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, registerAndExchange, registerIdentity, registerOnly, rotateIdentity, saveIdentity, version };