@datagrout/conduit 0.5.0 → 0.7.0

package/dist/{chunk-26DYCD4G.mjs → chunk-LW7VX5SZ.mjs}

@@ -73,7 +73,9 @@ var init_oauth = __esm({
         }
         if (!response.ok) {
           const text = await response.text().catch(() => "");
-          throw new Error(`OAuth token endpoint returned ${response.status}: ${text}`);
+          throw new Error(
+            `OAuth token endpoint returned ${response.status}: ${text}`
+          );
         }
         const data = await response.json();
         const expiresIn = data.expires_in ?? 3600;

package/dist/{chunk-SWH5Y2U7.mjs → chunk-W56N7X6V.mjs}

@@ -22,7 +22,9 @@ async function _doRegister(opts) {
   });
   if (!completeResp.ok) {
     const text = await completeResp.text();
-    throw new Error(`onramp complete rejected (HTTP ${completeResp.status}): ${text}`);
+    throw new Error(
+      `onramp complete rejected (HTTP ${completeResp.status}): ${text}`
+    );
   }
   const data = await completeResp.json();
   return {

package/dist/index.d.mts

@@ -226,7 +226,7 @@ declare function fetchWithIdentity(url: string, init: RequestInit, identity: Con
  * - `"unlimited"` — authenticated DataGrout users; the gateway never blocks them.
  * - `{ perHour: number }` — unauthenticated callers hitting a per-hour cap.
  */
-type RateLimit = 'unlimited' | {
+type RateLimit = "unlimited" | {
     perHour: number;
 };
 /**
@@ -414,7 +414,7 @@ interface ClientOptions {
      * This option is kept for backward compatibility and has no effect.
      */
     disableMtls?: boolean;
-    transport?: 'mcp' | 'jsonrpc' | 'websocket';
+    transport?: "mcp" | "jsonrpc" | "websocket";
     timeout?: number;
     /**
      * Maximum number of automatic retries on "server not initialized" errors.
@@ -437,7 +437,7 @@ interface PerformOptions {
     tool: string;
     args: Record<string, any>;
     demux?: boolean;
-    demuxMode?: 'strict' | 'fuzzy';
+    demuxMode?: "strict" | "fuzzy";
 }
 interface GuideRequestOptions {
     goal?: string;
@@ -649,9 +649,31 @@ declare class WsTransport extends Transport {
     private readonly _pending;
     private readonly _pendingSubscribe;
     private readonly _subscriptions;
+    /**
+     * Handle for the recurring ping timer; non-null only while connected.
+     * Cleared on disconnect / close.  Set indirectly via {@link _startPingTimer}.
+     */
+    private _pingTimer;
+    /**
+     * Interval in ms between client-initiated ping frames.  Public-readable so
+     * tests can inject a small value via {@link WsTransport.setPingInterval};
+     * defaults to {@link PING_INTERVAL_MS}.
+     */
+    private _pingIntervalMs;
     constructor(url: string, auth?: AuthConfig, _timeout?: number, _identity?: ConduitIdentity);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
+    /**
+     * Override the ping interval (ms) — used by tests to avoid 25-second waits.
+     * Must be called BEFORE {@link connect}; has no effect on an already-running
+     * timer.  In production code, leave the default ({@link PING_INTERVAL_MS}).
+     */
+    setPingInterval(intervalMs: number): void;
+    /** Tracks how many ping frames this transport has sent — for tests. */
+    get pingsSent(): number;
+    private _pingsSent;
+    private _startPingTimer;
+    private _stopPingTimer;
     /**
      * Open a server-side push subscription for `topic`.
      *

package/dist/index.d.ts

@@ -226,7 +226,7 @@ declare function fetchWithIdentity(url: string, init: RequestInit, identity: Con
  * - `"unlimited"` — authenticated DataGrout users; the gateway never blocks them.
  * - `{ perHour: number }` — unauthenticated callers hitting a per-hour cap.
  */
-type RateLimit = 'unlimited' | {
+type RateLimit = "unlimited" | {
     perHour: number;
 };
 /**
@@ -414,7 +414,7 @@ interface ClientOptions {
      * This option is kept for backward compatibility and has no effect.
      */
     disableMtls?: boolean;
-    transport?: 'mcp' | 'jsonrpc' | 'websocket';
+    transport?: "mcp" | "jsonrpc" | "websocket";
     timeout?: number;
     /**
      * Maximum number of automatic retries on "server not initialized" errors.
@@ -437,7 +437,7 @@ interface PerformOptions {
     tool: string;
     args: Record<string, any>;
     demux?: boolean;
-    demuxMode?: 'strict' | 'fuzzy';
+    demuxMode?: "strict" | "fuzzy";
 }
 interface GuideRequestOptions {
     goal?: string;
@@ -649,9 +649,31 @@ declare class WsTransport extends Transport {
     private readonly _pending;
     private readonly _pendingSubscribe;
     private readonly _subscriptions;
+    /**
+     * Handle for the recurring ping timer; non-null only while connected.
+     * Cleared on disconnect / close.  Set indirectly via {@link _startPingTimer}.
+     */
+    private _pingTimer;
+    /**
+     * Interval in ms between client-initiated ping frames.  Public-readable so
+     * tests can inject a small value via {@link WsTransport.setPingInterval};
+     * defaults to {@link PING_INTERVAL_MS}.
+     */
+    private _pingIntervalMs;
     constructor(url: string, auth?: AuthConfig, _timeout?: number, _identity?: ConduitIdentity);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
+    /**
+     * Override the ping interval (ms) — used by tests to avoid 25-second waits.
+     * Must be called BEFORE {@link connect}; has no effect on an already-running
+     * timer.  In production code, leave the default ({@link PING_INTERVAL_MS}).
+     */
+    setPingInterval(intervalMs: number): void;
+    /** Tracks how many ping frames this transport has sent — for tests. */
+    get pingsSent(): number;
+    private _pingsSent;
+    private _startPingTimer;
+    private _stopPingTimer;
     /**
      * Open a server-side push subscription for `topic`.
      *

package/dist/index.js

@@ -101,7 +101,9 @@ var init_oauth = __esm({
         }
         if (!response.ok) {
           const text = await response.text().catch(() => "");
-          throw new Error(`OAuth token endpoint returned ${response.status}: ${text}`);
+          throw new Error(
+            `OAuth token endpoint returned ${response.status}: ${text}`
+          );
         }
         const data = await response.json();
         const expiresIn = data.expires_in ?? 3600;
@@ -136,7 +138,9 @@ async function fetchWithIdentity(url, init, identity) {
     port: parsedUrl.port || 443,
     path: parsedUrl.pathname + parsedUrl.search,
     method: (init.method ?? "GET").toUpperCase(),
-    headers: flattenHeaders(init.headers),
+    headers: flattenHeaders(
+      init.headers
+    ),
     cert: identity.certPem,
     key: identity.keyPem,
     ...identity.caPem ? { ca: identity.caPem } : {}
@@ -220,7 +224,9 @@ var init_identity = __esm({
        */
       static fromPaths(certPath, keyPath, caPath) {
         if (typeof process === "undefined" || !process.versions?.node) {
-          throw new Error("ConduitIdentity.fromPaths() is only available in Node.js environments");
+          throw new Error(
+            "ConduitIdentity.fromPaths() is only available in Node.js environments"
+          );
         }
         const fs2 = require("fs");
         const certPem = fs2.readFileSync(certPath, "utf8");
@@ -244,7 +250,9 @@ var init_identity = __esm({
         if (!certPem) return null;
         const keyPem = process.env.CONDUIT_MTLS_KEY;
         if (!keyPem) {
-          throw new Error("CONDUIT_MTLS_CERT is set but CONDUIT_MTLS_KEY is missing");
+          throw new Error(
+            "CONDUIT_MTLS_CERT is set but CONDUIT_MTLS_KEY is missing"
+          );
         }
         const caPem = process.env.CONDUIT_MTLS_CA || void 0;
         return _ConduitIdentity.fromPem(certPem, keyPem, caPem);
@@ -334,7 +342,11 @@ var init_identity = __esm({
           const keyPath = `${dir}/identity_key.pem`;
           if (!fs2.existsSync(certPath) || !fs2.existsSync(keyPath)) return null;
           const caPath = `${dir}/ca.pem`;
-          return _ConduitIdentity.fromPaths(certPath, keyPath, fs2.existsSync(caPath) ? caPath : void 0);
+          return _ConduitIdentity.fromPaths(
+            certPath,
+            keyPath,
+            fs2.existsSync(caPath) ? caPath : void 0
+          );
         } catch {
           return null;
         }
@@ -374,7 +386,9 @@ async function _doRegister(opts) {
   });
   if (!completeResp.ok) {
     const text = await completeResp.text();
-    throw new Error(`onramp complete rejected (HTTP ${completeResp.status}): ${text}`);
+    throw new Error(
+      `onramp complete rejected (HTTP ${completeResp.status}): ${text}`
+    );
   }
   const data = await completeResp.json();
   return {
@@ -565,6 +579,9 @@ var MCPTransport = class extends Transport {
       throw new Error("Not connected. Call connect() first.");
     }
     const result = await this.client.callTool({ name, arguments: args });
+    if (result?.structuredContent !== void 0) {
+      return result.structuredContent;
+    }
     const content = result?.content;
     if (Array.isArray(content) && content.length > 0) {
       const first = content[0];
@@ -575,6 +592,7 @@ var MCPTransport = class extends Transport {
           return { text: first.text };
         }
       }
+      return first;
     }
     return result;
   }
@@ -671,7 +689,11 @@ var InvalidConfigError = class extends ConduitError {
 
 // src/transports/jsonrpc.ts
 function unwrapContent(result) {
-  if (result && Array.isArray(result.content) && result.content.length > 0) {
+  if (!result) return result;
+  if (result.structuredContent !== void 0) {
+    return result.structuredContent;
+  }
+  if (Array.isArray(result.content) && result.content.length > 0) {
     const first = result.content[0];
     if (first && typeof first.text === "string") {
       try {
@@ -680,6 +702,7 @@ function unwrapContent(result) {
         return { text: first.text };
       }
     }
+    return first;
   }
   return result;
 }
@@ -706,7 +729,9 @@ var JSONRPCTransport = class extends Transport {
     this.identity = identity;
     this.timeout = timeout;
     if (identity?.needsRotation(30)) {
-      console.warn("[conduit] mTLS certificate expires within 30 days \u2014 consider rotating");
+      console.warn(
+        "[conduit] mTLS certificate expires within 30 days \u2014 consider rotating"
+      );
     }
     if (auth?.clientCredentials) {
       const cc = auth.clientCredentials;
@@ -739,7 +764,9 @@ var JSONRPCTransport = class extends Transport {
     } else if (this.auth?.bearer) {
       headers["Authorization"] = `Bearer ${this.auth.bearer}`;
     } else if (this.auth?.basic) {
-      const credentials = btoa(`${this.auth.basic.username}:${this.auth.basic.password}`);
+      const credentials = btoa(
+        `${this.auth.basic.username}:${this.auth.basic.password}`
+      );
       headers["Authorization"] = `Basic ${credentials}`;
     } else if (this.auth?.custom) {
       Object.assign(headers, this.auth.custom);
@@ -809,6 +836,7 @@ var JSONRPCTransport = class extends Transport {
 // src/transports/ws.ts
 var SUBPROTOCOL = "datagrout-jsonrpc.v1";
 var SUBSCRIPTION_BUFFER = 256;
+var PING_INTERVAL_MS = 25e3;
 var Subscription = class {
   id;
   topic;
@@ -874,11 +902,24 @@ var WsTransport = class extends Transport {
   _pending = /* @__PURE__ */ new Map();
   _pendingSubscribe = /* @__PURE__ */ new Map();
   _subscriptions = /* @__PURE__ */ new Map();
+  /**
+   * Handle for the recurring ping timer; non-null only while connected.
+   * Cleared on disconnect / close.  Set indirectly via {@link _startPingTimer}.
+   */
+  _pingTimer = null;
+  /**
+   * Interval in ms between client-initiated ping frames.  Public-readable so
+   * tests can inject a small value via {@link WsTransport.setPingInterval};
+   * defaults to {@link PING_INTERVAL_MS}.
+   */
+  _pingIntervalMs = PING_INTERVAL_MS;
   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}://`);
+      throw new Error(
+        `WS transport requires a ws:// or wss:// URL, got ${scheme}://`
+      );
     }
     this._url = url;
     this._auth = auth;
@@ -893,19 +934,24 @@ var WsTransport = class extends Transport {
     });
     await new Promise((resolve, reject) => {
       ws.onopen = () => resolve();
-      ws.onerror = (ev) => reject(new Error(`WS connect failed: ${ev.message ?? "unknown"}`));
+      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._stopPingTimer();
       this._ws = null;
     };
     this._ws = ws;
+    this._startPingTimer();
   }
   async disconnect() {
     const ws = this._ws;
     this._ws = null;
+    this._stopPingTimer();
     this._failAll("WS connection closed");
     if (ws !== null) {
       try {
@@ -914,6 +960,42 @@ var WsTransport = class extends Transport {
       }
     }
   }
+  // ── Ping keepalive ────────────────────────────────────────────────────────
+  /**
+   * Override the ping interval (ms) — used by tests to avoid 25-second waits.
+   * Must be called BEFORE {@link connect}; has no effect on an already-running
+   * timer.  In production code, leave the default ({@link PING_INTERVAL_MS}).
+   */
+  setPingInterval(intervalMs) {
+    this._pingIntervalMs = intervalMs;
+  }
+  /** Tracks how many ping frames this transport has sent — for tests. */
+  get pingsSent() {
+    return this._pingsSent;
+  }
+  _pingsSent = 0;
+  _startPingTimer() {
+    if (this._pingTimer !== null || this._pingIntervalMs <= 0) return;
+    this._pingTimer = setInterval(() => {
+      const ws = this._ws;
+      if (ws === null) return;
+      if (typeof ws.ping === "function") {
+        try {
+          ws.ping();
+          this._pingsSent += 1;
+        } catch {
+        }
+      }
+    }, this._pingIntervalMs);
+    const t = this._pingTimer;
+    if (typeof t.unref === "function") t.unref();
+  }
+  _stopPingTimer() {
+    if (this._pingTimer !== null) {
+      clearInterval(this._pingTimer);
+      this._pingTimer = null;
+    }
+  }
   // ── Subscriptions ─────────────────────────────────────────────────────────
   /**
    * Open a server-side push subscription for `topic`.
@@ -927,7 +1009,12 @@ var WsTransport = class extends Transport {
     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 } });
+      this._send({
+        jsonrpc: "2.0",
+        id,
+        method: "subscribe",
+        params: { topic }
+      });
     });
   }
   /**
@@ -997,7 +1084,12 @@ var WsTransport = class extends Transport {
     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 } : {} });
+      this._send({
+        jsonrpc: "2.0",
+        id,
+        method,
+        ...params !== void 0 ? { params } : {}
+      });
     });
   }
   _handleMessage(data) {
@@ -1009,7 +1101,9 @@ var WsTransport = class extends Transport {
     }
     if (!("id" in msg)) {
       if (msg["method"] === "notification") {
-        this._routeNotification(msg["params"]);
+        this._routeNotification(
+          msg["params"]
+        );
       }
       return;
     }
@@ -1019,7 +1113,9 @@ var WsTransport = class extends Transport {
       this._pendingSubscribe.delete(msgId);
       const err = msg["error"];
       if (err !== void 0) {
-        pendingSub.reject(new Error(String(err["message"] ?? "Subscribe failed")));
+        pendingSub.reject(
+          new Error(String(err["message"] ?? "Subscribe failed"))
+        );
         return;
       }
       const result = msg["result"] ?? {};
@@ -1076,7 +1172,9 @@ function buildUpgradeHeaders(auth) {
   } 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");
+    const encoded = Buffer.from(
+      `${auth.basic.username}:${auth.basic.password}`
+    ).toString("base64");
     headers["Authorization"] = `Basic ${encoded}`;
   }
   return headers;
@@ -1115,7 +1213,9 @@ async function fetchDgCaCert(url = DG_CA_URL) {
   }
   const pem = await resp.text();
   if (!pem.includes("-----BEGIN CERTIFICATE-----")) {
-    throw new Error(`Response from ${url} does not look like a PEM certificate`);
+    throw new Error(
+      `Response from ${url} does not look like a PEM certificate`
+    );
   }
   return pem;
 }
@@ -1131,7 +1231,10 @@ function generateKeypair() {
     namedCurve: "P-256"
   });
   return {
-    privateKeyPem: privateKey.export({ type: "pkcs8", format: "pem" }),
+    privateKeyPem: privateKey.export({
+      type: "pkcs8",
+      format: "pem"
+    }),
     publicKeyPem: publicKey.export({ type: "spki", format: "pem" })
   };
 }
@@ -1171,9 +1274,17 @@ async function registerIdentity(keypair, opts) {
   };
 }
 async function rotateIdentity(opts) {
-  const { privateKey, publicKey } = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
-  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" });
-  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" });
+  const { privateKey, publicKey } = crypto.generateKeyPairSync("ec", {
+    namedCurve: "P-256"
+  });
+  const publicKeyPem = publicKey.export({
+    type: "spki",
+    format: "pem"
+  });
+  const privateKeyPem = privateKey.export({
+    type: "pkcs8",
+    format: "pem"
+  });
   const url = opts.endpoint.replace(/\/$/, "") + "/rotate";
   const https = await import("https");
   const urlModule = await import("url");
@@ -1188,7 +1299,10 @@ async function rotateIdentity(opts) {
       cert: opts.currentCertPem,
       key: opts.currentKeyPem
     };
-    const body = JSON.stringify({ public_key_pem: publicKeyPem, name: opts.name });
+    const body = JSON.stringify({
+      public_key_pem: publicKeyPem,
+      name: opts.name
+    });
     const req = https.request(reqOptions, (res) => {
       let data = "";
       res.on("data", (chunk) => {
@@ -1198,7 +1312,9 @@ async function rotateIdentity(opts) {
         if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
           resolve(data);
         } else {
-          reject(new Error(`Rotation failed (HTTP ${res.statusCode}): ${data}`));
+          reject(
+            new Error(`Rotation failed (HTTP ${res.statusCode}): ${data}`)
+          );
         }
       });
     });
@@ -1298,8 +1414,12 @@ var PrismNamespace = class {
       data: options.data,
       source_type: options.sourceType,
       target_type: options.targetType,
-      ...options.sourceAnnotations && { source_annotations: options.sourceAnnotations },
-      ...options.targetAnnotations && { target_annotations: options.targetAnnotations },
+      ...options.sourceAnnotations && {
+        source_annotations: options.sourceAnnotations
+      },
+      ...options.targetAnnotations && {
+        target_annotations: options.targetAnnotations
+      },
       ...options.context && { context: options.context }
     };
     return this.callDg("prism.focus", params);
@@ -1324,7 +1444,9 @@ var LogicNamespace = class {
       statement = opts.statement;
     }
     if (!statement && !opts?.facts?.length) {
-      throw new InvalidConfigError("remember() requires either a statement or facts");
+      throw new InvalidConfigError(
+        "remember() requires either a statement or facts"
+      );
     }
     const params = { tag: opts?.tag ?? "default" };
     if (opts?.facts) {
@@ -1345,7 +1467,9 @@ var LogicNamespace = class {
       question = opts.question;
     }
     if (!question && !opts?.patterns?.length) {
-      throw new InvalidConfigError("query() requires either a question or patterns");
+      throw new InvalidConfigError(
+        "query() requires either a question or patterns"
+      );
     }
     const params = { limit: opts?.limit ?? 50 };
     if (opts?.patterns) {
@@ -1358,7 +1482,9 @@ var LogicNamespace = class {
   /** Retract facts from the logic cell (`data-grout/logic.forget`). */
   async forget(options) {
     if (!options.handles?.length && !options.pattern) {
-      throw new InvalidConfigError("forget() requires either handles or pattern");
+      throw new InvalidConfigError(
+        "forget() requires either handles or pattern"
+      );
     }
     const params = {};
     if (options.handles) params.handles = options.handles;
@@ -1367,13 +1493,18 @@ var LogicNamespace = class {
   }
   /** Reflect on the logic cell (`data-grout/logic.reflect`). */
   async reflect(options) {
-    const params = { summary_only: options?.summaryOnly ?? false };
+    const params = {
+      summary_only: options?.summaryOnly ?? false
+    };
     if (options?.entity) params.entity = options.entity;
     return this.callDg("logic.reflect", params);
   }
   /** Add a constraint rule (`data-grout/logic.constrain`). */
   async constrain(rule, options) {
-    const params = { rule, tag: options?.tag ?? "constraint" };
+    const params = {
+      rule,
+      tag: options?.tag ?? "constraint"
+    };
     return this.callDg("logic.constrain", params);
   }
   /** Hydrate the logic cell from external data (`data-grout/logic.hydrate`). */
@@ -1535,7 +1666,9 @@ var FlowNamespace = class {
   /** Get details for a specific execution (`data-grout/inspect.execution-details`). */
   async details(executionId) {
     this.warn("inspect.execution-details");
-    return this.callDg("inspect.execution-details", { execution_id: executionId });
+    return this.callDg("inspect.execution-details", {
+      execution_id: executionId
+    });
   }
 };
 
@@ -1623,10 +1756,20 @@ var Client2 = class _Client {
       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);
+      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);
+      this.transport = new JSONRPCTransport(
+        rpcUrl,
+        this.auth,
+        options.timeout,
+        identity
+      );
     }
   }
   // ===== Bootstrap / seamless mTLS =====
@@ -1735,9 +1878,15 @@ var Client2 = class _Client {
     const existing = ConduitIdentity.tryDiscover(dir);
     if (existing && !existing.needsRotation(7)) {
       if (!options.url) {
-        throw new Error("'url' must be provided when an existing identity is reused");
+        throw new Error(
+          "'url' must be provided when an existing identity is reused"
+        );
       }
-      return new _Client({ url: options.url, identity: existing, identityDir: dir });
+      return new _Client({
+        url: options.url,
+        identity: existing,
+        identityDir: dir
+      });
     }
     const creds = await _doRegister2(options.opts);
     const token = await _exchangeToken2(creds);
@@ -1805,7 +1954,9 @@ var Client2 = class _Client {
   // ===== Namespace Accessors =====
   callDgTool = async (tool, params) => {
     this.ensureInitialized();
-    return this.sendWithRetry(() => this.transport.callTool(`data-grout/${tool}`, params));
+    return this.sendWithRetry(
+      () => this.transport.callTool(`data-grout/${tool}`, params)
+    );
   };
   /** Data transformation, charting, rendering, and type bridging. */
   get prism() {
@@ -1821,7 +1972,10 @@ var Client2 = class _Client {
   }
   /** Work product registration, listing, and retrieval. */
   get deliverables() {
-    return new DeliverablesNamespace(this.callDgTool, (m) => this.warnIfNotDg(m));
+    return new DeliverablesNamespace(
+      this.callDgTool,
+      (m) => this.warnIfNotDg(m)
+    );
   }
   /** Cache listing and inspection. */
   get ephemerals() {
@@ -1910,7 +2064,9 @@ var Client2 = class _Client {
    */
   async getPrompt(name, args, options) {
     this.ensureInitialized();
-    return this.sendWithRetry(() => this.transport.getPrompt(name, args, options));
+    return this.sendWithRetry(
+      () => this.transport.getPrompt(name, args, options)
+    );
   }
   // ===== WebSocket push subscriptions =====
   /**
@@ -2011,7 +2167,7 @@ var Client2 = class _Client {
         outputSchema: r.output_contract || r.output_schema || r.outputSchema
       })),
       total: result.total ?? tools.length,
-      limit: result.limit ?? (options.limit ?? 10)
+      limit: result.limit ?? options.limit ?? 10
     };
   }
   /**
@@ -2127,8 +2283,10 @@ var Client2 = class _Client {
     if (options.k !== void 0) params.k = options.k;
     if (options.policy) params.policy = options.policy;
     if (options.have) params.have = options.have;
-    if (options.returnCallHandles !== void 0) params.return_call_handles = options.returnCallHandles;
-    if (options.exposeVirtualSkills !== void 0) params.expose_virtual_skills = options.exposeVirtualSkills;
+    if (options.returnCallHandles !== void 0)
+      params.return_call_handles = options.returnCallHandles;
+    if (options.exposeVirtualSkills !== void 0)
+      params.expose_virtual_skills = options.exposeVirtualSkills;
     if (options.modelOverrides) params.model_overrides = options.modelOverrides;
     return this.sendWithRetry(
       () => this.transport.callTool("data-grout/discovery.plan", params)

package/dist/index.mjs

@@ -3,11 +3,11 @@ import {
   deriveTokenEndpoint,
   init_oauth,
   oauth_exports
-} from "./chunk-26DYCD4G.mjs";
+} from "./chunk-LW7VX5SZ.mjs";
 import {
   registerAndExchange,
   registerOnly
-} from "./chunk-SWH5Y2U7.mjs";
+} from "./chunk-W56N7X6V.mjs";
 import {
   __esm,
   __export,
@@ -35,7 +35,9 @@ async function fetchWithIdentity(url, init, identity) {
     port: parsedUrl.port || 443,
     path: parsedUrl.pathname + parsedUrl.search,
     method: (init.method ?? "GET").toUpperCase(),
-    headers: flattenHeaders(init.headers),
+    headers: flattenHeaders(
+      init.headers
+    ),
     cert: identity.certPem,
     key: identity.keyPem,
     ...identity.caPem ? { ca: identity.caPem } : {}
@@ -119,7 +121,9 @@ var init_identity = __esm({
        */
       static fromPaths(certPath, keyPath, caPath) {
         if (typeof process === "undefined" || !process.versions?.node) {
-          throw new Error("ConduitIdentity.fromPaths() is only available in Node.js environments");
+          throw new Error(
+            "ConduitIdentity.fromPaths() is only available in Node.js environments"
+          );
         }
         const fs2 = __require("fs");
         const certPem = fs2.readFileSync(certPath, "utf8");
@@ -143,7 +147,9 @@ var init_identity = __esm({
         if (!certPem) return null;
         const keyPem = process.env.CONDUIT_MTLS_KEY;
         if (!keyPem) {
-          throw new Error("CONDUIT_MTLS_CERT is set but CONDUIT_MTLS_KEY is missing");
+          throw new Error(
+            "CONDUIT_MTLS_CERT is set but CONDUIT_MTLS_KEY is missing"
+          );
         }
         const caPem = process.env.CONDUIT_MTLS_CA || void 0;
         return _ConduitIdentity.fromPem(certPem, keyPem, caPem);
@@ -233,7 +239,11 @@ var init_identity = __esm({
           const keyPath = `${dir}/identity_key.pem`;
           if (!fs2.existsSync(certPath) || !fs2.existsSync(keyPath)) return null;
           const caPath = `${dir}/ca.pem`;
-          return _ConduitIdentity.fromPaths(certPath, keyPath, fs2.existsSync(caPath) ? caPath : void 0);
+          return _ConduitIdentity.fromPaths(
+            certPath,
+            keyPath,
+            fs2.existsSync(caPath) ? caPath : void 0
+          );
         } catch {
           return null;
         }
@@ -354,6 +364,9 @@ var MCPTransport = class extends Transport {
       throw new Error("Not connected. Call connect() first.");
     }
     const result = await this.client.callTool({ name, arguments: args });
+    if (result?.structuredContent !== void 0) {
+      return result.structuredContent;
+    }
     const content = result?.content;
     if (Array.isArray(content) && content.length > 0) {
       const first = content[0];
@@ -364,6 +377,7 @@ var MCPTransport = class extends Transport {
           return { text: first.text };
         }
       }
+      return first;
     }
     return result;
   }
@@ -460,7 +474,11 @@ var InvalidConfigError = class extends ConduitError {
 
 // src/transports/jsonrpc.ts
 function unwrapContent(result) {
-  if (result && Array.isArray(result.content) && result.content.length > 0) {
+  if (!result) return result;
+  if (result.structuredContent !== void 0) {
+    return result.structuredContent;
+  }
+  if (Array.isArray(result.content) && result.content.length > 0) {
     const first = result.content[0];
     if (first && typeof first.text === "string") {
       try {
@@ -469,6 +487,7 @@ function unwrapContent(result) {
         return { text: first.text };
       }
     }
+    return first;
   }
   return result;
 }
@@ -495,7 +514,9 @@ var JSONRPCTransport = class extends Transport {
     this.identity = identity;
     this.timeout = timeout;
     if (identity?.needsRotation(30)) {
-      console.warn("[conduit] mTLS certificate expires within 30 days \u2014 consider rotating");
+      console.warn(
+        "[conduit] mTLS certificate expires within 30 days \u2014 consider rotating"
+      );
     }
     if (auth?.clientCredentials) {
       const cc = auth.clientCredentials;
@@ -528,7 +549,9 @@ var JSONRPCTransport = class extends Transport {
     } else if (this.auth?.bearer) {
       headers["Authorization"] = `Bearer ${this.auth.bearer}`;
     } else if (this.auth?.basic) {
-      const credentials = btoa(`${this.auth.basic.username}:${this.auth.basic.password}`);
+      const credentials = btoa(
+        `${this.auth.basic.username}:${this.auth.basic.password}`
+      );
       headers["Authorization"] = `Basic ${credentials}`;
     } else if (this.auth?.custom) {
       Object.assign(headers, this.auth.custom);
@@ -598,6 +621,7 @@ var JSONRPCTransport = class extends Transport {
 // src/transports/ws.ts
 var SUBPROTOCOL = "datagrout-jsonrpc.v1";
 var SUBSCRIPTION_BUFFER = 256;
+var PING_INTERVAL_MS = 25e3;
 var Subscription = class {
   id;
   topic;
@@ -663,11 +687,24 @@ var WsTransport = class extends Transport {
   _pending = /* @__PURE__ */ new Map();
   _pendingSubscribe = /* @__PURE__ */ new Map();
   _subscriptions = /* @__PURE__ */ new Map();
+  /**
+   * Handle for the recurring ping timer; non-null only while connected.
+   * Cleared on disconnect / close.  Set indirectly via {@link _startPingTimer}.
+   */
+  _pingTimer = null;
+  /**
+   * Interval in ms between client-initiated ping frames.  Public-readable so
+   * tests can inject a small value via {@link WsTransport.setPingInterval};
+   * defaults to {@link PING_INTERVAL_MS}.
+   */
+  _pingIntervalMs = PING_INTERVAL_MS;
   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}://`);
+      throw new Error(
+        `WS transport requires a ws:// or wss:// URL, got ${scheme}://`
+      );
     }
     this._url = url;
     this._auth = auth;
@@ -682,19 +719,24 @@ var WsTransport = class extends Transport {
     });
     await new Promise((resolve, reject) => {
       ws.onopen = () => resolve();
-      ws.onerror = (ev) => reject(new Error(`WS connect failed: ${ev.message ?? "unknown"}`));
+      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._stopPingTimer();
       this._ws = null;
     };
     this._ws = ws;
+    this._startPingTimer();
   }
   async disconnect() {
     const ws = this._ws;
     this._ws = null;
+    this._stopPingTimer();
     this._failAll("WS connection closed");
     if (ws !== null) {
       try {
@@ -703,6 +745,42 @@ var WsTransport = class extends Transport {
       }
     }
   }
+  // ── Ping keepalive ────────────────────────────────────────────────────────
+  /**
+   * Override the ping interval (ms) — used by tests to avoid 25-second waits.
+   * Must be called BEFORE {@link connect}; has no effect on an already-running
+   * timer.  In production code, leave the default ({@link PING_INTERVAL_MS}).
+   */
+  setPingInterval(intervalMs) {
+    this._pingIntervalMs = intervalMs;
+  }
+  /** Tracks how many ping frames this transport has sent — for tests. */
+  get pingsSent() {
+    return this._pingsSent;
+  }
+  _pingsSent = 0;
+  _startPingTimer() {
+    if (this._pingTimer !== null || this._pingIntervalMs <= 0) return;
+    this._pingTimer = setInterval(() => {
+      const ws = this._ws;
+      if (ws === null) return;
+      if (typeof ws.ping === "function") {
+        try {
+          ws.ping();
+          this._pingsSent += 1;
+        } catch {
+        }
+      }
+    }, this._pingIntervalMs);
+    const t = this._pingTimer;
+    if (typeof t.unref === "function") t.unref();
+  }
+  _stopPingTimer() {
+    if (this._pingTimer !== null) {
+      clearInterval(this._pingTimer);
+      this._pingTimer = null;
+    }
+  }
   // ── Subscriptions ─────────────────────────────────────────────────────────
   /**
    * Open a server-side push subscription for `topic`.
@@ -716,7 +794,12 @@ var WsTransport = class extends Transport {
     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 } });
+      this._send({
+        jsonrpc: "2.0",
+        id,
+        method: "subscribe",
+        params: { topic }
+      });
     });
   }
   /**
@@ -786,7 +869,12 @@ var WsTransport = class extends Transport {
     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 } : {} });
+      this._send({
+        jsonrpc: "2.0",
+        id,
+        method,
+        ...params !== void 0 ? { params } : {}
+      });
     });
   }
   _handleMessage(data) {
@@ -798,7 +886,9 @@ var WsTransport = class extends Transport {
     }
     if (!("id" in msg)) {
       if (msg["method"] === "notification") {
-        this._routeNotification(msg["params"]);
+        this._routeNotification(
+          msg["params"]
+        );
       }
       return;
     }
@@ -808,7 +898,9 @@ var WsTransport = class extends Transport {
       this._pendingSubscribe.delete(msgId);
       const err = msg["error"];
       if (err !== void 0) {
-        pendingSub.reject(new Error(String(err["message"] ?? "Subscribe failed")));
+        pendingSub.reject(
+          new Error(String(err["message"] ?? "Subscribe failed"))
+        );
         return;
       }
       const result = msg["result"] ?? {};
@@ -865,7 +957,9 @@ function buildUpgradeHeaders(auth) {
   } 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");
+    const encoded = Buffer.from(
+      `${auth.basic.username}:${auth.basic.password}`
+    ).toString("base64");
     headers["Authorization"] = `Basic ${encoded}`;
   }
   return headers;
@@ -904,7 +998,9 @@ async function fetchDgCaCert(url = DG_CA_URL) {
   }
   const pem = await resp.text();
   if (!pem.includes("-----BEGIN CERTIFICATE-----")) {
-    throw new Error(`Response from ${url} does not look like a PEM certificate`);
+    throw new Error(
+      `Response from ${url} does not look like a PEM certificate`
+    );
   }
   return pem;
 }
@@ -920,7 +1016,10 @@ function generateKeypair() {
     namedCurve: "P-256"
   });
   return {
-    privateKeyPem: privateKey.export({ type: "pkcs8", format: "pem" }),
+    privateKeyPem: privateKey.export({
+      type: "pkcs8",
+      format: "pem"
+    }),
     publicKeyPem: publicKey.export({ type: "spki", format: "pem" })
   };
 }
@@ -960,9 +1059,17 @@ async function registerIdentity(keypair, opts) {
   };
 }
 async function rotateIdentity(opts) {
-  const { privateKey, publicKey } = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
-  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" });
-  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" });
+  const { privateKey, publicKey } = crypto.generateKeyPairSync("ec", {
+    namedCurve: "P-256"
+  });
+  const publicKeyPem = publicKey.export({
+    type: "spki",
+    format: "pem"
+  });
+  const privateKeyPem = privateKey.export({
+    type: "pkcs8",
+    format: "pem"
+  });
   const url = opts.endpoint.replace(/\/$/, "") + "/rotate";
   const https = await import("https");
   const urlModule = await import("url");
@@ -977,7 +1084,10 @@ async function rotateIdentity(opts) {
       cert: opts.currentCertPem,
       key: opts.currentKeyPem
     };
-    const body = JSON.stringify({ public_key_pem: publicKeyPem, name: opts.name });
+    const body = JSON.stringify({
+      public_key_pem: publicKeyPem,
+      name: opts.name
+    });
     const req = https.request(reqOptions, (res) => {
       let data = "";
       res.on("data", (chunk) => {
@@ -987,7 +1097,9 @@ async function rotateIdentity(opts) {
         if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
           resolve(data);
         } else {
-          reject(new Error(`Rotation failed (HTTP ${res.statusCode}): ${data}`));
+          reject(
+            new Error(`Rotation failed (HTTP ${res.statusCode}): ${data}`)
+          );
         }
       });
     });
@@ -1087,8 +1199,12 @@ var PrismNamespace = class {
       data: options.data,
       source_type: options.sourceType,
       target_type: options.targetType,
-      ...options.sourceAnnotations && { source_annotations: options.sourceAnnotations },
-      ...options.targetAnnotations && { target_annotations: options.targetAnnotations },
+      ...options.sourceAnnotations && {
+        source_annotations: options.sourceAnnotations
+      },
+      ...options.targetAnnotations && {
+        target_annotations: options.targetAnnotations
+      },
       ...options.context && { context: options.context }
     };
     return this.callDg("prism.focus", params);
@@ -1113,7 +1229,9 @@ var LogicNamespace = class {
       statement = opts.statement;
     }
     if (!statement && !opts?.facts?.length) {
-      throw new InvalidConfigError("remember() requires either a statement or facts");
+      throw new InvalidConfigError(
+        "remember() requires either a statement or facts"
+      );
     }
     const params = { tag: opts?.tag ?? "default" };
     if (opts?.facts) {
@@ -1134,7 +1252,9 @@ var LogicNamespace = class {
       question = opts.question;
     }
     if (!question && !opts?.patterns?.length) {
-      throw new InvalidConfigError("query() requires either a question or patterns");
+      throw new InvalidConfigError(
+        "query() requires either a question or patterns"
+      );
     }
     const params = { limit: opts?.limit ?? 50 };
     if (opts?.patterns) {
@@ -1147,7 +1267,9 @@ var LogicNamespace = class {
   /** Retract facts from the logic cell (`data-grout/logic.forget`). */
   async forget(options) {
     if (!options.handles?.length && !options.pattern) {
-      throw new InvalidConfigError("forget() requires either handles or pattern");
+      throw new InvalidConfigError(
+        "forget() requires either handles or pattern"
+      );
     }
     const params = {};
     if (options.handles) params.handles = options.handles;
@@ -1156,13 +1278,18 @@ var LogicNamespace = class {
   }
   /** Reflect on the logic cell (`data-grout/logic.reflect`). */
   async reflect(options) {
-    const params = { summary_only: options?.summaryOnly ?? false };
+    const params = {
+      summary_only: options?.summaryOnly ?? false
+    };
     if (options?.entity) params.entity = options.entity;
     return this.callDg("logic.reflect", params);
   }
   /** Add a constraint rule (`data-grout/logic.constrain`). */
   async constrain(rule, options) {
-    const params = { rule, tag: options?.tag ?? "constraint" };
+    const params = {
+      rule,
+      tag: options?.tag ?? "constraint"
+    };
     return this.callDg("logic.constrain", params);
   }
   /** Hydrate the logic cell from external data (`data-grout/logic.hydrate`). */
@@ -1324,7 +1451,9 @@ var FlowNamespace = class {
   /** Get details for a specific execution (`data-grout/inspect.execution-details`). */
   async details(executionId) {
     this.warn("inspect.execution-details");
-    return this.callDg("inspect.execution-details", { execution_id: executionId });
+    return this.callDg("inspect.execution-details", {
+      execution_id: executionId
+    });
   }
 };
 
@@ -1412,10 +1541,20 @@ var Client2 = class _Client {
       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);
+      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);
+      this.transport = new JSONRPCTransport(
+        rpcUrl,
+        this.auth,
+        options.timeout,
+        identity
+      );
     }
   }
   // ===== Bootstrap / seamless mTLS =====
@@ -1473,7 +1612,7 @@ var Client2 = class _Client {
    * @param options.substrateEndpoint - Override the DG Substrate endpoint.
    */
   static async bootstrapIdentityOAuth(options) {
-    const { OAuthTokenProvider: OAuthTokenProvider2, deriveTokenEndpoint: deriveTokenEndpoint2 } = await import("./oauth-NSDC2G7W.mjs");
+    const { OAuthTokenProvider: OAuthTokenProvider2, deriveTokenEndpoint: deriveTokenEndpoint2 } = await import("./oauth-T2D3EDCN.mjs");
     const tokenEndpoint = deriveTokenEndpoint2(options.url);
     const provider = new OAuthTokenProvider2({
       clientId: options.clientId,
@@ -1519,14 +1658,20 @@ var Client2 = class _Client {
    * ```
    */
   static async bootstrapOnramp(options) {
-    const { _doRegister, _exchangeToken } = await import("./onramp-743RJTNI.mjs");
+    const { _doRegister, _exchangeToken } = await import("./onramp-RDGV3FOI.mjs");
     const dir = options.identityDir || DEFAULT_IDENTITY_DIR;
     const existing = ConduitIdentity.tryDiscover(dir);
     if (existing && !existing.needsRotation(7)) {
       if (!options.url) {
-        throw new Error("'url' must be provided when an existing identity is reused");
+        throw new Error(
+          "'url' must be provided when an existing identity is reused"
+        );
       }
-      return new _Client({ url: options.url, identity: existing, identityDir: dir });
+      return new _Client({
+        url: options.url,
+        identity: existing,
+        identityDir: dir
+      });
     }
     const creds = await _doRegister(options.opts);
     const token = await _exchangeToken(creds);
@@ -1594,7 +1739,9 @@ var Client2 = class _Client {
   // ===== Namespace Accessors =====
   callDgTool = async (tool, params) => {
     this.ensureInitialized();
-    return this.sendWithRetry(() => this.transport.callTool(`data-grout/${tool}`, params));
+    return this.sendWithRetry(
+      () => this.transport.callTool(`data-grout/${tool}`, params)
+    );
   };
   /** Data transformation, charting, rendering, and type bridging. */
   get prism() {
@@ -1610,7 +1757,10 @@ var Client2 = class _Client {
   }
   /** Work product registration, listing, and retrieval. */
   get deliverables() {
-    return new DeliverablesNamespace(this.callDgTool, (m) => this.warnIfNotDg(m));
+    return new DeliverablesNamespace(
+      this.callDgTool,
+      (m) => this.warnIfNotDg(m)
+    );
   }
   /** Cache listing and inspection. */
   get ephemerals() {
@@ -1699,7 +1849,9 @@ var Client2 = class _Client {
    */
   async getPrompt(name, args, options) {
     this.ensureInitialized();
-    return this.sendWithRetry(() => this.transport.getPrompt(name, args, options));
+    return this.sendWithRetry(
+      () => this.transport.getPrompt(name, args, options)
+    );
   }
   // ===== WebSocket push subscriptions =====
   /**
@@ -1800,7 +1952,7 @@ var Client2 = class _Client {
         outputSchema: r.output_contract || r.output_schema || r.outputSchema
       })),
       total: result.total ?? tools.length,
-      limit: result.limit ?? (options.limit ?? 10)
+      limit: result.limit ?? options.limit ?? 10
     };
   }
   /**
@@ -1916,8 +2068,10 @@ var Client2 = class _Client {
     if (options.k !== void 0) params.k = options.k;
     if (options.policy) params.policy = options.policy;
     if (options.have) params.have = options.have;
-    if (options.returnCallHandles !== void 0) params.return_call_handles = options.returnCallHandles;
-    if (options.exposeVirtualSkills !== void 0) params.expose_virtual_skills = options.exposeVirtualSkills;
+    if (options.returnCallHandles !== void 0)
+      params.return_call_handles = options.returnCallHandles;
+    if (options.exposeVirtualSkills !== void 0)
+      params.expose_virtual_skills = options.exposeVirtualSkills;
     if (options.modelOverrides) params.model_overrides = options.modelOverrides;
     return this.sendWithRetry(
       () => this.transport.callTool("data-grout/discovery.plan", params)

package/dist/{oauth-NSDC2G7W.mjs → oauth-T2D3EDCN.mjs}

@@ -2,7 +2,7 @@ import {
   OAuthTokenProvider,
   deriveTokenEndpoint,
   init_oauth
-} from "./chunk-26DYCD4G.mjs";
+} from "./chunk-LW7VX5SZ.mjs";
 import "./chunk-CIESM3BP.mjs";
 init_oauth();
 export {

package/dist/{onramp-743RJTNI.mjs → onramp-RDGV3FOI.mjs}

@@ -3,7 +3,7 @@ import {
   _exchangeToken,
   registerAndExchange,
   registerOnly
-} from "./chunk-SWH5Y2U7.mjs";
+} from "./chunk-W56N7X6V.mjs";
 import "./chunk-CIESM3BP.mjs";
 export {
   _doRegister,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datagrout/conduit",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Production-ready MCP client with mTLS, OAuth 2.1, and semantic discovery",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",