@datagrout/conduit 0.1.0

package/dist/index.js

@@ -0,0 +1,1736 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/oauth.ts
+var oauth_exports = {};
+__export(oauth_exports, {
+  OAuthTokenProvider: () => OAuthTokenProvider,
+  deriveTokenEndpoint: () => deriveTokenEndpoint
+});
+function deriveTokenEndpoint(mcpUrl) {
+  const mcpIdx = mcpUrl.indexOf("/mcp");
+  const base = mcpIdx !== -1 ? mcpUrl.slice(0, mcpIdx) : mcpUrl.replace(/\/$/, "");
+  return `${base}/oauth/token`;
+}
+var OAuthTokenProvider;
+var init_oauth = __esm({
+  "src/oauth.ts"() {
+    "use strict";
+    OAuthTokenProvider = class {
+      clientId;
+      clientSecret;
+      tokenEndpoint;
+      scope;
+      cached = null;
+      fetchPromise = null;
+      constructor(opts) {
+        this.clientId = opts.clientId;
+        this.clientSecret = opts.clientSecret;
+        this.tokenEndpoint = opts.tokenEndpoint;
+        this.scope = opts.scope;
+      }
+      /**
+       * Return the current bearer token, fetching a fresh one if necessary.
+       * Concurrent callers share a single in-flight fetch.
+       */
+      async getToken() {
+        const now = Date.now();
+        if (this.cached && this.cached.expiresAt - now > 6e4) {
+          return this.cached.accessToken;
+        }
+        if (!this.fetchPromise) {
+          this.fetchPromise = this.fetchToken().finally(() => {
+            this.fetchPromise = null;
+          });
+        }
+        const cached = await this.fetchPromise;
+        return cached.accessToken;
+      }
+      /** Invalidate the cached token (e.g. after receiving a 401). */
+      invalidate() {
+        this.cached = null;
+      }
+      // ─── Private ───────────────────────────────────────────────────────────────
+      async fetchToken() {
+        const body = new URLSearchParams({
+          grant_type: "client_credentials",
+          client_id: this.clientId,
+          client_secret: this.clientSecret
+        });
+        if (this.scope) {
+          body.set("scope", this.scope);
+        }
+        let response;
+        try {
+          response = await fetch(this.tokenEndpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString()
+          });
+        } catch (err) {
+          throw new Error(`OAuth token request failed: ${err}`);
+        }
+        if (!response.ok) {
+          const text = await response.text().catch(() => "");
+          throw new Error(`OAuth token endpoint returned ${response.status}: ${text}`);
+        }
+        const data = await response.json();
+        const expiresIn = data.expires_in ?? 3600;
+        const cached = {
+          accessToken: data.access_token,
+          expiresAt: Date.now() + expiresIn * 1e3
+        };
+        this.cached = cached;
+        return cached;
+      }
+    };
+  }
+});
+
+// src/identity.ts
+var identity_exports = {};
+__export(identity_exports, {
+  ConduitIdentity: () => ConduitIdentity,
+  fetchWithIdentity: () => fetchWithIdentity
+});
+async function fetchWithIdentity(url, init, identity) {
+  if (typeof process === "undefined" || !process.versions?.node) {
+    console.warn(
+      "[conduit] mTLS identity is set but this environment does not support client certificates in fetch().  The request will proceed without mTLS."
+    );
+    return fetch(url, init);
+  }
+  const https = require("https");
+  const parsedUrl = new URL(url);
+  const options = {
+    hostname: parsedUrl.hostname,
+    port: parsedUrl.port || 443,
+    path: parsedUrl.pathname + parsedUrl.search,
+    method: (init.method ?? "GET").toUpperCase(),
+    headers: flattenHeaders(init.headers),
+    cert: identity.certPem,
+    key: identity.keyPem,
+    ...identity.caPem ? { ca: identity.caPem } : {}
+  };
+  return new Promise((resolve, reject) => {
+    const req = https.request(options, (res) => {
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => {
+        const body = Buffer.concat(chunks);
+        const responseHeaders = new Headers();
+        for (const [key, value] of Object.entries(res.headers)) {
+          if (value !== void 0) {
+            const v = Array.isArray(value) ? value.join(", ") : String(value);
+            responseHeaders.set(key, v);
+          }
+        }
+        resolve(
+          new Response(body, {
+            status: res.statusCode ?? 200,
+            statusText: res.statusMessage ?? "",
+            headers: responseHeaders
+          })
+        );
+      });
+      res.on("error", reject);
+    });
+    req.on("error", reject);
+    if (init.body) {
+      req.write(init.body);
+    }
+    req.end();
+  });
+}
+function flattenHeaders(headers) {
+  if (!headers) return {};
+  if (headers instanceof Headers) {
+    const obj = {};
+    headers.forEach((v, k) => {
+      obj[k] = v;
+    });
+    return obj;
+  }
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers);
+  }
+  return headers;
+}
+var ConduitIdentity;
+var init_identity = __esm({
+  "src/identity.ts"() {
+    "use strict";
+    ConduitIdentity = class _ConduitIdentity {
+      _config;
+      constructor(config) {
+        this._config = config;
+      }
+      // ─── Constructors ───────────────────────────────────────────────────────────
+      /**
+       * Build an identity from PEM strings already in memory.
+       *
+       * @throws {Error} if the PEM strings do not look like a certificate or key.
+       */
+      static fromPem(certPem, keyPem, caPem) {
+        if (!certPem.includes("-----BEGIN CERTIFICATE-----")) {
+          throw new Error(
+            'certPem does not appear to contain a PEM certificate (missing "-----BEGIN CERTIFICATE-----")'
+          );
+        }
+        if (!_ConduitIdentity._hasPemPrivateKey(keyPem)) {
+          throw new Error(
+            "keyPem does not appear to contain a PEM private key (expected PRIVATE KEY, RSA PRIVATE KEY, or EC PRIVATE KEY header)"
+          );
+        }
+        return new _ConduitIdentity({ certPem, keyPem, caPem });
+      }
+      /**
+       * Build an identity by reading PEM files from disk (Node.js only).
+       *
+       * @throws {Error} in browser environments or if the files cannot be read.
+       */
+      static fromPaths(certPath, keyPath, caPath) {
+        if (typeof process === "undefined" || !process.versions?.node) {
+          throw new Error("ConduitIdentity.fromPaths() is only available in Node.js environments");
+        }
+        const fs2 = require("fs");
+        const certPem = fs2.readFileSync(certPath, "utf8");
+        const keyPem = fs2.readFileSync(keyPath, "utf8");
+        const caPem = caPath ? fs2.readFileSync(caPath, "utf8") : void 0;
+        return _ConduitIdentity.fromPem(certPem, keyPem, caPem);
+      }
+      /**
+       * Build an identity from environment variables.
+       *
+       * Reads:
+       * - `CONDUIT_MTLS_CERT` — PEM string for the client certificate
+       * - `CONDUIT_MTLS_KEY`  — PEM string for the private key
+       * - `CONDUIT_MTLS_CA`   — PEM string for the CA (optional)
+       *
+       * @returns `null` if `CONDUIT_MTLS_CERT` is not set.
+       * @throws {Error} if `CONDUIT_MTLS_CERT` is set but `CONDUIT_MTLS_KEY` is missing.
+       */
+      static fromEnv() {
+        const certPem = process.env.CONDUIT_MTLS_CERT;
+        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");
+        }
+        const caPem = process.env.CONDUIT_MTLS_CA || void 0;
+        return _ConduitIdentity.fromPem(certPem, keyPem, caPem);
+      }
+      /**
+       * Try to locate an identity using the auto-discovery chain described in the
+       * module docs.  Returns `null` if nothing is found.
+       */
+      static tryDefault() {
+        return _ConduitIdentity.tryDiscover();
+      }
+      /**
+       * Like {@link tryDefault} but checks `overrideDir` first.
+       *
+       * Discovery order:
+       * 1. `overrideDir` (if provided)
+       * 2. `CONDUIT_MTLS_CERT` + `CONDUIT_MTLS_KEY` env vars
+       * 3. `CONDUIT_IDENTITY_DIR` env var
+       * 4. `~/.conduit/`
+       * 5. `.conduit/` relative to cwd
+       */
+      static tryDiscover(overrideDir) {
+        if (overrideDir) {
+          const id = _ConduitIdentity._tryLoadFromDir(overrideDir);
+          if (id) return id;
+        }
+        try {
+          const id = _ConduitIdentity.fromEnv();
+          if (id) return id;
+        } catch {
+        }
+        if (typeof process === "undefined" || !process.versions?.node) {
+          return null;
+        }
+        const envDir = process.env.CONDUIT_IDENTITY_DIR;
+        if (envDir) {
+          const id = _ConduitIdentity._tryLoadFromDir(envDir);
+          if (id) return id;
+        }
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+        if (home) {
+          const id = _ConduitIdentity._tryLoadFromDir(`${home}/.conduit`);
+          if (id) return id;
+        }
+        {
+          const id = _ConduitIdentity._tryLoadFromDir(".conduit");
+          if (id) return id;
+        }
+        return null;
+      }
+      // ─── Builder-style setters ──────────────────────────────────────────────────
+      /** Attach a known certificate expiry for rotation checks. */
+      withExpiry(expiresAt) {
+        return new _ConduitIdentity({ ...this._config, expiresAt });
+      }
+      // ─── Introspection ──────────────────────────────────────────────────────────
+      /**
+       * Returns `true` if the certificate expires within `thresholdDays`.
+       *
+       * Always returns `false` when no expiry is set.
+       */
+      needsRotation(thresholdDays) {
+        if (!this._config.expiresAt) return false;
+        const thresholdMs = thresholdDays * 864e5;
+        return Date.now() + thresholdMs > this._config.expiresAt.getTime();
+      }
+      get certPem() {
+        return this._config.certPem;
+      }
+      get keyPem() {
+        return this._config.keyPem;
+      }
+      get caPem() {
+        return this._config.caPem;
+      }
+      get expiresAt() {
+        return this._config.expiresAt;
+      }
+      // ─── Internal helpers ───────────────────────────────────────────────────────
+      static _hasPemPrivateKey(pem) {
+        return pem.includes("-----BEGIN PRIVATE KEY-----") || pem.includes("-----BEGIN RSA PRIVATE KEY-----") || pem.includes("-----BEGIN EC PRIVATE KEY-----") || pem.includes("-----BEGIN ENCRYPTED PRIVATE KEY-----");
+      }
+      static _tryLoadFromDir(dir) {
+        try {
+          const fs2 = require("fs");
+          const certPath = `${dir}/identity.pem`;
+          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);
+        } catch {
+          return null;
+        }
+      }
+    };
+  }
+});
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthError: () => AuthError,
+  Client: () => Client2,
+  ConduitError: () => ConduitError,
+  ConduitIdentity: () => ConduitIdentity,
+  DEFAULT_IDENTITY_DIR: () => DEFAULT_IDENTITY_DIR,
+  DG_CA_URL: () => DG_CA_URL,
+  DG_SUBSTRATE_ENDPOINT: () => DG_SUBSTRATE_ENDPOINT,
+  GuidedSession: () => GuidedSession,
+  InvalidConfigError: () => InvalidConfigError,
+  NetworkError: () => NetworkError,
+  NotInitializedError: () => NotInitializedError,
+  OAuthTokenProvider: () => OAuthTokenProvider,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  deriveTokenEndpoint: () => deriveTokenEndpoint,
+  extractMeta: () => extractMeta,
+  fetchDgCaCert: () => fetchDgCaCert,
+  fetchWithIdentity: () => fetchWithIdentity,
+  generateKeypair: () => generateKeypair,
+  isDgUrl: () => isDgUrl,
+  refreshCaCert: () => refreshCaCert,
+  registerIdentity: () => registerIdentity,
+  rotateIdentity: () => rotateIdentity,
+  saveIdentity: () => saveIdentity,
+  version: () => version
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var path2 = __toESM(require("path"));
+
+// src/transports/base.ts
+var Transport = class {
+};
+
+// src/transports/mcp.ts
+init_oauth();
+var import_client = require("@modelcontextprotocol/sdk/client/index.js");
+var import_sse = require("@modelcontextprotocol/sdk/client/sse.js");
+var import_stdio = require("@modelcontextprotocol/sdk/client/stdio.js");
+var MCPTransport = class extends Transport {
+  url;
+  auth;
+  identity;
+  client;
+  clientTransport;
+  oauthProvider;
+  constructor(url, auth, identity) {
+    super();
+    this.url = url;
+    this.auth = auth;
+    this.identity = identity;
+    if (auth?.clientCredentials) {
+      const cc = auth.clientCredentials;
+      const tokenEndpoint = cc.tokenEndpoint ?? deriveTokenEndpoint(url);
+      this.oauthProvider = new OAuthTokenProvider({
+        clientId: cc.clientId,
+        clientSecret: cc.clientSecret,
+        tokenEndpoint,
+        scope: cc.scope
+      });
+    }
+  }
+  async buildHeaders() {
+    const headers = {};
+    if (this.oauthProvider) {
+      const token = await this.oauthProvider.getToken();
+      headers["Authorization"] = `Bearer ${token}`;
+    } else if (this.auth?.bearer) {
+      headers["Authorization"] = `Bearer ${this.auth.bearer}`;
+    } else if (this.auth?.basic) {
+      const encoded = Buffer.from(
+        `${this.auth.basic.username}:${this.auth.basic.password}`
+      ).toString("base64");
+      headers["Authorization"] = `Basic ${encoded}`;
+    } else if (this.auth?.custom) {
+      Object.assign(headers, this.auth.custom);
+    }
+    return headers;
+  }
+  async connect() {
+    if (this.url.startsWith("stdio://")) {
+      const command = this.url.replace("stdio://", "");
+      const parts = command.split(" ");
+      this.clientTransport = new import_stdio.StdioClientTransport({
+        command: parts[0],
+        args: parts.slice(1)
+      });
+    } else if (this.url.startsWith("http://") || this.url.startsWith("https://")) {
+      const headers = await this.buildHeaders();
+      const transportOpts = {};
+      if (Object.keys(headers).length > 0) {
+        transportOpts.requestInit = { headers };
+      }
+      if (this.identity) {
+        const id = this.identity;
+        transportOpts.fetcher = (url, init) => {
+          const { fetchWithIdentity: fetchWithIdentity2 } = (init_identity(), __toCommonJS(identity_exports));
+          return fetchWithIdentity2(
+            typeof url === "string" ? url : url instanceof URL ? url.toString() : url.url,
+            init ?? {},
+            id
+          );
+        };
+      }
+      this.clientTransport = new import_sse.SSEClientTransport(
+        new URL(this.url),
+        transportOpts
+      );
+    } else {
+      throw new Error(`Unsupported MCP URL scheme: ${this.url}`);
+    }
+    this.client = new import_client.Client(
+      { name: "datagrout-conduit", version: "0.1.0" },
+      { capabilities: {} }
+    );
+    await this.client.connect(this.clientTransport);
+  }
+  async disconnect() {
+    if (this.client) {
+      await this.client.close();
+    }
+  }
+  async listTools(options) {
+    if (!this.client) {
+      throw new Error("Not connected. Call connect() first.");
+    }
+    const result = await this.client.listTools(options);
+    return result.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      annotations: tool.annotations
+    }));
+  }
+  async callTool(name, args, options) {
+    if (!this.client) {
+      throw new Error("Not connected. Call connect() first.");
+    }
+    const result = await this.client.callTool({ name, arguments: args });
+    const content = result?.content;
+    if (Array.isArray(content) && content.length > 0) {
+      const first = content[0];
+      if (first && typeof first.text === "string") {
+        try {
+          return JSON.parse(first.text);
+        } catch {
+          return { text: first.text };
+        }
+      }
+    }
+    return result;
+  }
+  async listResources(options) {
+    if (!this.client) {
+      throw new Error("Not connected. Call connect() first.");
+    }
+    const result = await this.client.listResources();
+    return result.resources.map((resource) => ({
+      uri: resource.uri,
+      name: resource.name,
+      description: resource.description,
+      mimeType: resource.mimeType
+    }));
+  }
+  async readResource(uri, options) {
+    if (!this.client) {
+      throw new Error("Not connected. Call connect() first.");
+    }
+    const result = await this.client.readResource({ uri });
+    return result.contents;
+  }
+  async listPrompts(options) {
+    if (!this.client) {
+      throw new Error("Not connected. Call connect() first.");
+    }
+    const result = await this.client.listPrompts();
+    return result.prompts.map((prompt) => ({
+      name: prompt.name,
+      description: prompt.description,
+      arguments: prompt.arguments
+    }));
+  }
+  async getPrompt(name, args, options) {
+    if (!this.client) {
+      throw new Error("Not connected. Call connect() first.");
+    }
+    const result = await this.client.getPrompt({ name, arguments: args || {} });
+    return result.messages;
+  }
+};
+
+// src/transports/jsonrpc.ts
+init_identity();
+init_oauth();
+
+// src/errors.ts
+var ConduitError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var NotInitializedError = class extends ConduitError {
+  constructor() {
+    super("Client not initialized. Call connect() first.");
+  }
+};
+var RateLimitError = class extends ConduitError {
+  status;
+  retryAfter;
+  constructor(status, retryAfter) {
+    const limitStr = status.limit === "unlimited" ? "unlimited" : `${status.limit.perHour}/hour`;
+    super(`Rate limit exceeded (${status.used} / ${limitStr} calls this hour)`);
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+};
+var AuthError = class extends ConduitError {
+  constructor(message = "Authentication failed") {
+    super(message);
+  }
+};
+var NetworkError = class extends ConduitError {
+  constructor(message) {
+    super(message);
+  }
+};
+var ServerError = class extends ConduitError {
+  code;
+  serverMessage;
+  constructor(code, serverMessage) {
+    super(`Server error ${code}: ${serverMessage}`);
+    this.code = code;
+    this.serverMessage = serverMessage;
+  }
+};
+var InvalidConfigError = class extends ConduitError {
+  constructor(message) {
+    super(message);
+  }
+};
+
+// src/transports/jsonrpc.ts
+function unwrapContent(result) {
+  if (result && Array.isArray(result.content) && result.content.length > 0) {
+    const first = result.content[0];
+    if (first && typeof first.text === "string") {
+      try {
+        return JSON.parse(first.text);
+      } catch {
+        return { text: first.text };
+      }
+    }
+  }
+  return result;
+}
+function parseRateLimitError(response) {
+  const used = parseInt(response.headers.get("X-RateLimit-Used") ?? "0", 10) || 0;
+  const limitStr = response.headers.get("X-RateLimit-Limit") ?? "50";
+  const limit = limitStr.toLowerCase() === "unlimited" ? "unlimited" : { perHour: parseInt(limitStr, 10) || 50 };
+  const isLimited = limit === "unlimited" ? false : used >= limit.perHour;
+  const remaining = limit === "unlimited" ? null : Math.max(0, limit.perHour - used);
+  return new RateLimitError({ used, limit, isLimited, remaining });
+}
+var JSONRPCTransport = class extends Transport {
+  url;
+  auth;
+  identity;
+  timeout;
+  requestId = 0;
+  /** Resolved token provider, present only when `auth.clientCredentials` is set. */
+  oauthProvider;
+  constructor(url, auth, timeout = 3e4, identity) {
+    super();
+    this.url = url;
+    this.auth = auth;
+    this.identity = identity;
+    this.timeout = timeout;
+    if (identity?.needsRotation(30)) {
+      console.warn("[conduit] mTLS certificate expires within 30 days \u2014 consider rotating");
+    }
+    if (auth?.clientCredentials) {
+      const cc = auth.clientCredentials;
+      const tokenEndpoint = cc.tokenEndpoint ?? (() => {
+        const { deriveTokenEndpoint: deriveTokenEndpoint2 } = (init_oauth(), __toCommonJS(oauth_exports));
+        return deriveTokenEndpoint2(url);
+      })();
+      this.oauthProvider = new OAuthTokenProvider({
+        clientId: cc.clientId,
+        clientSecret: cc.clientSecret,
+        tokenEndpoint,
+        scope: cc.scope
+      });
+    }
+  }
+  async connect() {
+  }
+  async disconnect() {
+  }
+  async call(method, params) {
+    return this._callWithRetry(method, params, false);
+  }
+  async _callWithRetry(method, params, isRetry) {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.oauthProvider) {
+      const token = await this.oauthProvider.getToken();
+      headers["Authorization"] = `Bearer ${token}`;
+    } 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}`);
+      headers["Authorization"] = `Basic ${credentials}`;
+    } else if (this.auth?.custom) {
+      Object.assign(headers, this.auth.custom);
+    }
+    const request = {
+      jsonrpc: "2.0",
+      id: ++this.requestId,
+      method,
+      params: params || {}
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    const fetchInit = {
+      method: "POST",
+      headers,
+      body: JSON.stringify(request),
+      signal: controller.signal
+    };
+    try {
+      const response = this.identity ? await fetchWithIdentity(this.url, fetchInit, this.identity) : await fetch(this.url, fetchInit);
+      if (response.status === 429) {
+        throw parseRateLimitError(response);
+      }
+      if (response.status === 401 && this.oauthProvider && !isRetry) {
+        this.oauthProvider.invalidate();
+        return this._callWithRetry(method, params, true);
+      }
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      const data = await response.json();
+      if (data.error) {
+        throw new Error(`JSONRPC Error: ${JSON.stringify(data.error)}`);
+      }
+      return data.result;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  async listTools(options) {
+    const result = await this.call("tools/list", options);
+    return result?.tools || [];
+  }
+  async callTool(name, args, options) {
+    const params = { name, arguments: args, ...options };
+    const result = await this.call("tools/call", params);
+    return unwrapContent(result);
+  }
+  async listResources(options) {
+    const result = await this.call("resources/list", options);
+    return result?.resources || [];
+  }
+  async readResource(uri, options) {
+    const params = { uri, ...options };
+    return await this.call("resources/read", params);
+  }
+  async listPrompts(options) {
+    const result = await this.call("prompts/list", options);
+    return result?.prompts || [];
+  }
+  async getPrompt(name, args, options) {
+    const params = { name, arguments: args || {}, ...options };
+    return await this.call("prompts/get", params);
+  }
+};
+
+// src/client.ts
+init_identity();
+
+// src/registration.ts
+var fs = __toESM(require("fs"));
+var os = __toESM(require("os"));
+var path = __toESM(require("path"));
+var crypto = __toESM(require("crypto"));
+var DG_CA_URL = "https://ca.datagrout.ai/ca.pem";
+var DG_SUBSTRATE_ENDPOINT = "https://app.datagrout.ai/api/v1/substrate/identity";
+var DEFAULT_IDENTITY_DIR = path.join(os.homedir(), ".conduit");
+async function fetchDgCaCert(url = DG_CA_URL) {
+  const resp = await fetch(url, {
+    headers: { Accept: "application/x-pem-file, text/plain, */*" }
+  });
+  if (!resp.ok) {
+    throw new Error(`CA cert fetch failed (HTTP ${resp.status}) from ${url}`);
+  }
+  const pem = await resp.text();
+  if (!pem.includes("-----BEGIN CERTIFICATE-----")) {
+    throw new Error(`Response from ${url} does not look like a PEM certificate`);
+  }
+  return pem;
+}
+async function refreshCaCert(identityDir = DEFAULT_IDENTITY_DIR, url = DG_CA_URL) {
+  const pem = await fetchDgCaCert(url);
+  fs.mkdirSync(identityDir, { recursive: true });
+  const caPath = path.join(identityDir, "ca.pem");
+  fs.writeFileSync(caPath, pem, "utf8");
+  return caPath;
+}
+function generateKeypair() {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync("ec", {
+    namedCurve: "P-256"
+  });
+  return {
+    privateKeyPem: privateKey.export({ type: "pkcs8", format: "pem" }),
+    publicKeyPem: publicKey.export({ type: "spki", format: "pem" })
+  };
+}
+async function registerIdentity(keypair, opts) {
+  const { privateKeyPem, publicKeyPem } = keypair;
+  const url = opts.endpoint.replace(/\/$/, "") + "/register";
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${opts.authToken}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ public_key_pem: publicKeyPem, name: opts.name })
+  });
+  if (!resp.ok) {
+    const body2 = await resp.text();
+    throw new Error(`Registration failed (HTTP ${resp.status}): ${body2}`);
+  }
+  const body = await resp.json();
+  let caPem = body.ca_cert_pem;
+  if (!caPem) {
+    try {
+      caPem = await fetchDgCaCert(opts.caUrl ?? DG_CA_URL);
+    } catch {
+      caPem = void 0;
+    }
+  }
+  return {
+    certPem: body.cert_pem,
+    keyPem: privateKeyPem,
+    caPem,
+    id: body.id,
+    name: body.name,
+    fingerprint: body.fingerprint,
+    registeredAt: body.registered_at ?? "",
+    validUntil: body.valid_until
+  };
+}
+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 url = opts.endpoint.replace(/\/$/, "") + "/rotate";
+  const https = await import("https");
+  const urlModule = await import("url");
+  const parsed = new urlModule.URL(url);
+  const responseBody = await new Promise((resolve, reject) => {
+    const reqOptions = {
+      hostname: parsed.hostname,
+      port: parsed.port || 443,
+      path: parsed.pathname,
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      cert: opts.currentCertPem,
+      key: opts.currentKeyPem
+    };
+    const body = JSON.stringify({ public_key_pem: publicKeyPem, name: opts.name });
+    const req = https.request(reqOptions, (res) => {
+      let data = "";
+      res.on("data", (chunk) => {
+        data += chunk;
+      });
+      res.on("end", () => {
+        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+          resolve(data);
+        } else {
+          reject(new Error(`Rotation failed (HTTP ${res.statusCode}): ${data}`));
+        }
+      });
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+  const respBody = JSON.parse(responseBody);
+  let caPem = respBody.ca_cert_pem;
+  if (!caPem) {
+    try {
+      caPem = await fetchDgCaCert(opts.caUrl ?? DG_CA_URL);
+    } catch {
+      caPem = void 0;
+    }
+  }
+  return {
+    certPem: respBody.cert_pem,
+    keyPem: privateKeyPem,
+    caPem,
+    id: respBody.id,
+    name: respBody.name,
+    fingerprint: respBody.fingerprint,
+    registeredAt: respBody.registered_at ?? "",
+    validUntil: respBody.valid_until
+  };
+}
+function saveIdentity(identity, directory = DEFAULT_IDENTITY_DIR) {
+  fs.mkdirSync(directory, { recursive: true });
+  const certPath = path.join(directory, "identity.pem");
+  const keyPath = path.join(directory, "identity_key.pem");
+  fs.writeFileSync(certPath, identity.certPem, "utf8");
+  fs.writeFileSync(keyPath, identity.keyPem, { encoding: "utf8", mode: 384 });
+  const result = { certPath, keyPath };
+  if (identity.caPem) {
+    const caPath = path.join(directory, "ca.pem");
+    fs.writeFileSync(caPath, identity.caPem, "utf8");
+    result.caPath = caPath;
+  }
+  return result;
+}
+
+// src/client.ts
+var GuidedSession = class {
+  client;
+  state;
+  constructor(client, state) {
+    this.client = client;
+    this.state = state;
+  }
+  /** Unique session identifier used to resume the workflow. */
+  get sessionId() {
+    return this.state.sessionId;
+  }
+  /** Current workflow status (e.g. `"ready"`, `"completed"`). */
+  get status() {
+    return this.state.status;
+  }
+  /** Available options for the current step. */
+  get options() {
+    return this.state.options || [];
+  }
+  /** Final result, populated once `status === "completed"`. */
+  get result() {
+    return this.state.result;
+  }
+  /** Returns the raw `GuideState` snapshot for this step. */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Advance the guided session by selecting an option.
+   *
+   * @param optionId - The `id` of the option to choose (from `session.options`).
+   * @returns A new `GuidedSession` reflecting the next workflow step.
+   */
+  async choose(optionId) {
+    return await this.client.guide({
+      sessionId: this.sessionId,
+      choice: optionId
+    });
+  }
+  /**
+   * Retrieve the completed workflow result.
+   *
+   * Throws if the session has not yet reached `status === "completed"`.
+   * Use `choose()` to advance through remaining steps first.
+   */
+  async complete() {
+    if (this.status === "completed") {
+      return this.result;
+    }
+    throw new Error(
+      `Workflow not complete (status: ${this.status}). Call choose() with one of the available options.`
+    );
+  }
+};
+function isDgUrl(url) {
+  return url.includes("datagrout.ai") || url.includes("datagrout.dev") || !!process.env["CONDUIT_IS_DG"];
+}
+var Client2 = class _Client {
+  url;
+  auth;
+  useIntelligentInterface;
+  transport;
+  isDg;
+  dgWarned = false;
+  initialized = false;
+  maxRetries;
+  constructor(options) {
+    if (typeof options === "string") {
+      options = { url: options };
+    }
+    this.url = options.url;
+    this.auth = options.auth;
+    this.isDg = isDgUrl(this.url);
+    this.useIntelligentInterface = options.useIntelligentInterface ?? this.isDg;
+    this.maxRetries = options.maxRetries ?? 3;
+    let identity = options.identity ?? (options.identityAuto ? ConduitIdentity.tryDiscover(options.identityDir) ?? void 0 : void 0);
+    if (identity === void 0 && this.isDg && !options.disableMtls) {
+      identity = ConduitIdentity.tryDiscover(options.identityDir) ?? void 0;
+    }
+    const transportType = options.transport || "mcp";
+    if (transportType === "mcp") {
+      this.transport = new MCPTransport(this.url, this.auth, 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);
+    }
+  }
+  // ===== Bootstrap / seamless mTLS =====
+  /**
+   * Create a `Client` with an mTLS identity bootstrapped automatically.
+   *
+   * Checks the auto-discovery chain first. If an existing identity is found
+   * and not within 7 days of expiry, it is reused. Otherwise a new keypair
+   * is generated, registered with DataGrout, and saved locally.
+   *
+   * After the first successful bootstrap the token is no longer needed —
+   * mTLS handles authentication on every subsequent run.
+   *
+   * @param options.url              - DataGrout server URL.
+   * @param options.authToken        - Bearer token for the initial registration call.
+   * @param options.name             - Human-readable identity name (default: `"conduit-client"`).
+   * @param options.identityDir      - Custom identity storage directory.
+   * @param options.substrateEndpoint - Override the DG Substrate endpoint.
+   */
+  static async bootstrapIdentity(options) {
+    const dir = options.identityDir || DEFAULT_IDENTITY_DIR;
+    const name = options.name || "conduit-client";
+    const endpoint = options.substrateEndpoint || DG_SUBSTRATE_ENDPOINT;
+    const existing = ConduitIdentity.tryDiscover(dir);
+    if (existing && !existing.needsRotation(7)) {
+      const client2 = new _Client({ url: options.url, identity: existing });
+      await client2.connect();
+      return client2;
+    }
+    const keypair = generateKeypair();
+    const registered = await registerIdentity(keypair, {
+      endpoint,
+      authToken: options.authToken,
+      name
+    });
+    saveIdentity(registered, dir);
+    const identity = ConduitIdentity.fromPaths(
+      path2.join(dir, "identity.pem"),
+      path2.join(dir, "identity_key.pem"),
+      path2.join(dir, "ca.pem")
+    );
+    const client = new _Client({ url: options.url, identity });
+    await client.connect();
+    return client;
+  }
+  /**
+   * Like `bootstrapIdentity` but uses OAuth 2.1 `client_credentials` to obtain
+   * the bearer token automatically — no pre-obtained token needed.
+   *
+   * @param options.url              - DataGrout server URL.
+   * @param options.clientId         - OAuth client ID.
+   * @param options.clientSecret     - OAuth client secret.
+   * @param options.name             - Human-readable identity name (default: `"conduit-client"`).
+   * @param options.identityDir      - Custom identity storage directory.
+   * @param options.substrateEndpoint - Override the DG Substrate endpoint.
+   */
+  static async bootstrapIdentityOAuth(options) {
+    const { OAuthTokenProvider: OAuthTokenProvider2, deriveTokenEndpoint: deriveTokenEndpoint2 } = await Promise.resolve().then(() => (init_oauth(), oauth_exports));
+    const tokenEndpoint = deriveTokenEndpoint2(options.url);
+    const provider = new OAuthTokenProvider2({
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      tokenEndpoint
+    });
+    const token = await provider.getToken();
+    return _Client.bootstrapIdentity({
+      url: options.url,
+      authToken: token,
+      name: options.name,
+      identityDir: options.identityDir,
+      substrateEndpoint: options.substrateEndpoint
+    });
+  }
+  // ===== Lifecycle =====
+  /**
+   * Establish the underlying transport connection.
+   *
+   * Must be called before any other method. For the MCP transport this
+   * performs the JSON-RPC `initialize` handshake; for JSONRPC it is a no-op
+   * (connections are per-request).
+   */
+  async connect() {
+    await this.transport.connect();
+    this.initialized = true;
+  }
+  /**
+   * Close the underlying transport connection and mark the client as
+   * uninitialized. After calling this, `connect()` must be called again
+   * before issuing further requests.
+   */
+  async disconnect() {
+    await this.transport.disconnect();
+    this.initialized = false;
+  }
+  ensureInitialized() {
+    if (!this.initialized) {
+      throw new NotInitializedError();
+    }
+  }
+  /**
+   * Wrap a transport call with automatic retry on "not initialized" errors
+   * (JSON-RPC code -32002). Re-initializes the connection and retries up to
+   * `maxRetries` times with 500ms backoff between attempts.
+   */
+  async sendWithRetry(fn) {
+    let retries = this.maxRetries;
+    while (true) {
+      try {
+        return await fn();
+      } catch (error) {
+        const isNotInit = error?.code === -32002 || error?.message?.includes("not initialized");
+        if (isNotInit && retries > 0) {
+          retries--;
+          await this.connect();
+          await new Promise((r) => setTimeout(r, 500));
+          continue;
+        }
+        throw error;
+      }
+    }
+  }
+  // ===== Standard MCP API (Drop-in Compatible) =====
+  /**
+   * List all tools exposed by the connected MCP server.
+   *
+   * Calls the MCP `tools/list` method with automatic cursor-based pagination.
+   * When `useIntelligentInterface` is enabled (default for DataGrout URLs),
+   * integration tools (names containing `@`) are filtered out, leaving only
+   * the DataGrout semantic discovery interface.
+   *
+   * JSON-RPC method: `tools/list`
+   */
+  async listTools(options) {
+    this.ensureInitialized();
+    return this.sendWithRetry(async () => {
+      let allTools = [];
+      let cursor;
+      do {
+        const response = await this.transport.listTools({ ...options, cursor });
+        const tools = Array.isArray(response) ? response : response.tools || [];
+        allTools.push(...tools);
+        cursor = Array.isArray(response) ? void 0 : response.nextCursor;
+      } while (cursor);
+      if (this.useIntelligentInterface) {
+        return allTools.filter((t) => !t.name.includes("@"));
+      }
+      return allTools;
+    });
+  }
+  /**
+   * Invoke a named tool on the connected MCP server.
+   *
+   * JSON-RPC method: `tools/call`
+   *
+   * @param name - Fully-qualified tool name (e.g. `salesforce@v1/get_lead@v1`).
+   * @param args - Tool input arguments.
+   */
+  async callTool(name, args, _options) {
+    this.ensureInitialized();
+    return this.sendWithRetry(() => this.transport.callTool(name, args));
+  }
+  /**
+   * List resources exposed by the connected MCP server.
+   *
+   * JSON-RPC method: `resources/list`
+   */
+  async listResources(options) {
+    this.ensureInitialized();
+    return this.sendWithRetry(() => this.transport.listResources(options));
+  }
+  /**
+   * Read the content of a named resource.
+   *
+   * JSON-RPC method: `resources/read`
+   *
+   * @param uri - Resource URI as returned by `listResources()`.
+   */
+  async readResource(uri, options) {
+    this.ensureInitialized();
+    return this.sendWithRetry(() => this.transport.readResource(uri, options));
+  }
+  /**
+   * List prompt templates exposed by the connected MCP server.
+   *
+   * JSON-RPC method: `prompts/list`
+   */
+  async listPrompts(options) {
+    this.ensureInitialized();
+    return this.sendWithRetry(() => this.transport.listPrompts(options));
+  }
+  /**
+   * Retrieve a prompt template, optionally instantiated with arguments.
+   *
+   * JSON-RPC method: `prompts/get`
+   *
+   * @param name - Prompt name as returned by `listPrompts()`.
+   * @param args - Template argument values.
+   */
+  async getPrompt(name, args, options) {
+    this.ensureInitialized();
+    return this.sendWithRetry(() => this.transport.getPrompt(name, args, options));
+  }
+  // ===== DG-awareness helpers =====
+  warnIfNotDg(method) {
+    if (!this.isDg && !this.dgWarned) {
+      this.dgWarned = true;
+      console.warn(
+        `[conduit] \`${method}\` is a DataGrout-specific extension. The connected server may not support it. Standard MCP methods (listTools, callTool, \u2026) work on any server.`
+      );
+    }
+  }
+  // ===== DataGrout Extensions =====
+  /**
+   * Semantically discover tools relevant to a goal or query.
+   *
+   * Uses DataGrout's vector-search index to find the best-matching tools
+   * across all registered integrations. Returns ranked results with scores,
+   * descriptions, and schemas.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/discovery.discover`
+   *
+   * @param options.query        - Natural language search query.
+   * @param options.goal         - High-level goal description (alternative to `query`).
+   * @param options.limit        - Maximum results to return (default: 10).
+   * @param options.minScore     - Minimum relevance score (default: 0.0).
+   * @param options.integrations - Filter by specific integration names.
+   * @param options.servers      - Filter by specific server IDs.
+   */
+  async discover(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("discover");
+    const params = {
+      limit: options.limit ?? 10,
+      min_score: options.minScore ?? 0
+    };
+    if (options.query) params.query = options.query;
+    if (options.goal) params.goal = options.goal;
+    if (options.integrations) params.integrations = options.integrations;
+    if (options.servers) params.servers = options.servers;
+    const result = await this.sendWithRetry(
+      () => this.transport.callTool("data-grout/discovery.discover", params)
+    );
+    const tools = result.results || result.tools || [];
+    return {
+      queryUsed: result.goal_used || result.query_used || result.queryUsed || "",
+      results: tools.map((r) => ({
+        toolName: r.tool_name || r.toolName,
+        integration: r.integration,
+        serverId: r.server_id || r.serverId || r.server,
+        score: r.score,
+        distance: r.distance,
+        description: r.description,
+        sideEffects: r.side_effects || r.sideEffects,
+        inputSchema: r.input_contract || r.input_schema || r.inputSchema,
+        outputSchema: r.output_contract || r.output_schema || r.outputSchema
+      })),
+      total: result.total ?? tools.length,
+      limit: result.limit ?? (options.limit ?? 10)
+    };
+  }
+  /**
+   * Execute a single tool call routed through DataGrout's gateway.
+   *
+   * The gateway handles credential injection, usage tracking, and receipts.
+   * Use `performBatch()` to execute multiple calls in one request.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/discovery.perform`
+   *
+   * @param options.tool     - Fully-qualified tool name.
+   * @param options.args     - Tool input arguments.
+   * @param options.demux    - When `true`, use semantic demultiplexing.
+   * @param options.demuxMode - Demux strictness (`"strict"` | `"fuzzy"`).
+   */
+  async perform(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("perform");
+    return await this.performWithTracking(
+      options.tool,
+      options.args,
+      options.demux ? { demux: options.demux, demuxMode: options.demuxMode } : void 0
+    );
+  }
+  /**
+   * Execute multiple tool calls in a single gateway request.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/discovery.perform`
+   *
+   * @param calls - Array of `{ tool, args }` call descriptors.
+   */
+  async performBatch(calls) {
+    this.ensureInitialized();
+    this.warnIfNotDg("performBatch");
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/discovery.perform", calls)
+    );
+  }
+  /**
+   * Start or advance a guided workflow session.
+   *
+   * The first call (with only `goal`) starts a new session and returns the
+   * initial options. Subsequent calls provide `sessionId` and `choice` to
+   * advance through steps. Returns a `GuidedSession` that exposes helpers
+   * for navigating the workflow.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/discovery.guide`
+   *
+   * @param options.goal      - High-level goal to accomplish (first call only).
+   * @param options.policy    - Optional policy constraints for tool selection.
+   * @param options.sessionId - Resume an existing session (subsequent calls).
+   * @param options.choice    - Option ID selected at the current step.
+   */
+  async guide(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("guide");
+    const params = {};
+    if (options.goal) params.goal = options.goal;
+    if (options.policy) params.policy = options.policy;
+    if (options.sessionId) params.session_id = options.sessionId;
+    if (options.choice) params.choice = options.choice;
+    const result = await this.sendWithRetry(
+      () => this.transport.callTool("data-grout/discovery.guide", params)
+    );
+    const state = {
+      sessionId: result.session_id || result.sessionId,
+      step: result.step,
+      message: result.message,
+      status: result.status,
+      options: result.options?.map((o) => ({
+        id: o.id,
+        label: o.label,
+        cost: o.cost,
+        viable: o.viable,
+        metadata: o.metadata
+      })),
+      pathTaken: result.path_taken || result.pathTaken,
+      totalCost: result.total_cost || result.totalCost,
+      result: result.result,
+      progress: result.progress
+    };
+    return new GuidedSession(this, state);
+  }
+  /**
+   * Execute a pre-planned sequence of tool calls (a "flow") through the
+   * DataGrout gateway.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/flow.into`
+   *
+   * @param options.plan          - Ordered list of tool call descriptors.
+   * @param options.validateCtc   - Validate each call against its CTC schema (default: `true`).
+   * @param options.saveAsSkill   - Persist the flow as a reusable skill (default: `false`).
+   * @param options.inputData     - Runtime input data for the flow.
+   */
+  async flowInto(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("flowInto");
+    const params = {
+      plan: options.plan,
+      validate_ctc: options.validateCtc ?? true,
+      save_as_skill: options.saveAsSkill ?? false
+    };
+    if (options.inputData) {
+      params.input_data = options.inputData;
+    }
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/flow.into", params)
+    );
+  }
+  /**
+   * Transform data from one annotated type to another using the DataGrout
+   * Prism semantic mapping engine.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/prism.focus`
+   *
+   * @param options.data               - Source payload to transform.
+   * @param options.sourceType         - Semantic type of the source data.
+   * @param options.targetType         - Desired semantic type for the output.
+   * @param options.sourceAnnotations  - Additional schema hints for the source.
+   * @param options.targetAnnotations  - Additional schema hints for the target.
+   * @param options.context            - Free-text context to guide the mapping.
+   */
+  async prismFocus(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("prismFocus");
+    const params = {
+      data: options.data,
+      source_type: options.sourceType,
+      target_type: options.targetType,
+      ...options.sourceAnnotations && { source_annotations: options.sourceAnnotations },
+      ...options.targetAnnotations && { target_annotations: options.targetAnnotations },
+      ...options.context && { context: options.context }
+    };
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/prism.focus", params)
+    );
+  }
+  /**
+   * Generate an execution plan for a goal using DataGrout's planning engine.
+   *
+   * Returns an ordered list of tool calls that, when executed, accomplish the
+   * stated goal. Throws `InvalidConfigError` if neither `goal` nor `query` is
+   * provided.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/discovery.plan`
+   *
+   * @param options.goal                - High-level goal description.
+   * @param options.query               - Search query to anchor the plan (alternative to `goal`).
+   * @param options.server              - Restrict planning to a specific server.
+   * @param options.k                   - Maximum number of plan steps.
+   * @param options.policy              - Policy constraints for tool selection.
+   * @param options.have                - Pre-existing data/context available to the planner.
+   * @param options.returnCallHandles   - Include call handles in the response.
+   * @param options.exposeVirtualSkills - Include virtual skills in the plan.
+   * @param options.modelOverrides      - Override LLM model settings.
+   */
+  async plan(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("plan");
+    if (!options.goal && !options.query) {
+      throw new InvalidConfigError("plan() requires either goal or query");
+    }
+    const params = {};
+    if (options.goal) params.goal = options.goal;
+    if (options.query) params.query = options.query;
+    if (options.server) params.server = options.server;
+    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.modelOverrides) params.model_overrides = options.modelOverrides;
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/discovery.plan", params)
+    );
+  }
+  /**
+   * Analyse and summarise a payload using the DataGrout Prism refraction engine.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/prism.refract`
+   *
+   * @param options.goal    - Description of what to extract or summarise.
+   * @param options.payload - Input data to analyse (any JSON-serializable value).
+   * @param options.verbose - Include detailed processing trace in the response.
+   * @param options.chart   - Also generate a chart representation.
+   */
+  async refract(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("refract");
+    const params = {
+      goal: options.goal,
+      payload: options.payload
+    };
+    if (options.verbose !== void 0) params.verbose = options.verbose;
+    if (options.chart !== void 0) params.chart = options.chart;
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/prism.refract", params)
+    );
+  }
+  /**
+   * Generate a chart from a data payload using the DataGrout Prism engine.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/prism.chart`
+   *
+   * @param options.goal      - What the chart should visualise.
+   * @param options.payload   - Input data (any JSON-serializable value).
+   * @param options.format    - Output format (e.g. `"png"`, `"svg"`).
+   * @param options.chartType - Chart type (e.g. `"bar"`, `"line"`, `"pie"`).
+   * @param options.title     - Chart title.
+   * @param options.xLabel    - X-axis label.
+   * @param options.yLabel    - Y-axis label.
+   * @param options.width     - Chart width in pixels.
+   * @param options.height    - Chart height in pixels.
+   */
+  async chart(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("chart");
+    const params = {
+      goal: options.goal,
+      payload: options.payload
+    };
+    if (options.format) params.format = options.format;
+    if (options.chartType) params.chart_type = options.chartType;
+    if (options.title) params.title = options.title;
+    if (options.xLabel) params.x_label = options.xLabel;
+    if (options.yLabel) params.y_label = options.yLabel;
+    if (options.width !== void 0) params.width = options.width;
+    if (options.height !== void 0) params.height = options.height;
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/prism.chart", params)
+    );
+  }
+  /**
+   * Generate a document toward a natural-language goal.
+   * Supported formats: markdown, html, pdf, json.
+   */
+  async render(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("render");
+    const { goal, format = "markdown", payload, sections, ...rest } = options;
+    const params = { goal, format, ...rest };
+    if (payload !== void 0) params.payload = payload;
+    if (sections !== void 0) params.sections = sections;
+    return this.sendWithRetry(() => this.transport.callTool("data-grout/prism.render", params));
+  }
+  /**
+   * Convert content to another format (no LLM). Supports csv, xlsx, pdf, json, html, markdown, etc.
+   */
+  async export(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("export");
+    const { content, format, ...rest } = options;
+    const params = { content, format, ...rest };
+    return this.sendWithRetry(() => this.transport.callTool("data-grout/prism.export", params));
+  }
+  /**
+   * Pause workflow for human approval. Use for destructive or policy-gated actions.
+   */
+  async requestApproval(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("requestApproval");
+    const { action, details, reason, context, ...rest } = options;
+    const params = { action, ...rest };
+    if (details !== void 0) params.details = details;
+    if (reason !== void 0) params.reason = reason;
+    if (context !== void 0) params.context = context;
+    return this.sendWithRetry(() => this.transport.callTool("data-grout/flow.request-approval", params));
+  }
+  /**
+   * Request user clarification for missing fields. Pauses until user provides values.
+   */
+  async requestFeedback(options) {
+    this.ensureInitialized();
+    this.warnIfNotDg("requestFeedback");
+    const { missing_fields, reason, ...rest } = options;
+    const params = { missing_fields, reason, ...rest };
+    return this.sendWithRetry(() => this.transport.callTool("data-grout/flow.request-feedback", params));
+  }
+  /**
+   * List recent tool executions for the current server.
+   */
+  async executionHistory(options = {}) {
+    this.ensureInitialized();
+    this.warnIfNotDg("executionHistory");
+    const params = { limit: options.limit ?? 50, offset: options.offset ?? 0, refractions_only: options.refractions_only ?? false, ...options };
+    if (options.status !== void 0) params.status = options.status;
+    return this.sendWithRetry(() => this.transport.callTool("data-grout/inspect.execution-history", params));
+  }
+  /**
+   * Get details and transcript for a specific execution.
+   */
+  async executionDetails(executionId) {
+    this.ensureInitialized();
+    this.warnIfNotDg("executionDetails");
+    return this.sendWithRetry(() => this.transport.callTool("data-grout/inspect.execution-details", { execution_id: executionId }));
+  }
+  /**
+   * Call any DataGrout first-party tool by its short name.
+   *
+   * Prepends `data-grout/` to the tool name automatically, so
+   * `client.dg('prism.render', { ... })` calls `data-grout/prism.render`.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/<toolShortName>`
+   *
+   * @param toolShortName - Tool name without the `data-grout/` prefix.
+   * @param params        - Tool input arguments.
+   */
+  async dg(toolShortName, params = {}) {
+    this.ensureInitialized();
+    const method = `data-grout/${toolShortName}`;
+    return this.sendWithRetry(() => this.transport.callTool(method, params));
+  }
+  async remember(statementOrOptions, optionsArg) {
+    this.ensureInitialized();
+    let statement;
+    let opts;
+    if (typeof statementOrOptions === "string") {
+      statement = statementOrOptions;
+      opts = optionsArg;
+    } else {
+      opts = statementOrOptions;
+      statement = opts.statement;
+    }
+    if (!statement && !opts?.facts?.length) {
+      throw new InvalidConfigError("remember() requires either a statement or facts");
+    }
+    const params = {
+      tag: opts?.tag ?? "default"
+    };
+    if (opts?.facts) {
+      params.facts = opts.facts;
+    } else {
+      params.statement = statement;
+    }
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/logic.remember", params)
+    );
+  }
+  async queryCell(questionOrOptions, optionsArg) {
+    this.ensureInitialized();
+    let question;
+    let opts;
+    if (typeof questionOrOptions === "string") {
+      question = questionOrOptions;
+      opts = optionsArg;
+    } else {
+      opts = questionOrOptions;
+      question = opts.question;
+    }
+    if (!question && !opts?.patterns?.length) {
+      throw new InvalidConfigError("queryCell() requires either a question or patterns");
+    }
+    const params = {
+      limit: opts?.limit ?? 50
+    };
+    if (opts?.patterns) {
+      params.patterns = opts.patterns;
+    } else {
+      params.question = question;
+    }
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/logic.query", params)
+    );
+  }
+  /**
+   * Retract facts from the agent's logic cell.
+   *
+   * Throws `InvalidConfigError` if neither `handles` nor `pattern` is provided.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/logic.forget`
+   *
+   * @param options.handles - Specific fact handles to retract.
+   * @param options.pattern - Natural language pattern — retract all matching facts.
+   */
+  async forget(options) {
+    this.ensureInitialized();
+    if (!options.handles?.length && !options.pattern) {
+      throw new InvalidConfigError("forget() requires either handles or pattern");
+    }
+    const params = {};
+    if (options.handles) params.handles = options.handles;
+    if (options.pattern) params.pattern = options.pattern;
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/logic.forget", params)
+    );
+  }
+  /**
+   * Reflect on the agent's logic cell — returns a full snapshot or a
+   * per-entity view of all stored facts.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/logic.reflect`
+   *
+   * @param options.entity      - Optional entity name to scope reflection.
+   * @param options.summaryOnly - When `true`, return only counts (default: `false`).
+   */
+  async reflect(options) {
+    this.ensureInitialized();
+    const params = {
+      summary_only: options?.summaryOnly ?? false
+    };
+    if (options?.entity) params.entity = options.entity;
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/logic.reflect", params)
+    );
+  }
+  /**
+   * Store a logical rule or policy in the agent's logic cell.
+   *
+   * Rules are permanent constraints evaluated during `queryCell()` calls.
+   *
+   * JSON-RPC method: `tools/call` → `data-grout/logic.constrain`
+   *
+   * @param rule         - Natural language rule (e.g. `"VIP customers have ARR > $500K"`).
+   * @param options.tag  - Tag/namespace for this constraint (default: `"constraint"`).
+   */
+  async constrain(rule, options) {
+    this.ensureInitialized();
+    const params = {
+      rule,
+      tag: options?.tag ?? "constraint"
+    };
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/logic.constrain", params)
+    );
+  }
+  /**
+   * Estimate the credit cost of a tool call without executing it.
+   *
+   * Passes `estimate_only: true` to the tool, which returns a cost breakdown
+   * without performing any side effects or charging credits.
+   *
+   * @param tool - Fully-qualified tool name.
+   * @param args - Tool input arguments.
+   */
+  async estimateCost(tool, args) {
+    this.ensureInitialized();
+    const estimateArgs = { ...args, estimate_only: true };
+    return this.sendWithRetry(
+      () => this.transport.callTool(tool, estimateArgs)
+    );
+  }
+  // ===== Internal Helpers =====
+  async performWithTracking(tool, args, options) {
+    const params = { tool, args, ...options };
+    return this.sendWithRetry(
+      () => this.transport.callTool("data-grout/discovery.perform", params)
+    );
+  }
+};
+
+// src/index.ts
+init_identity();
+init_oauth();
+
+// src/types.ts
+function extractMeta(result) {
+  const raw = result?._meta?.datagrout ?? result?._datagrout ?? result?._meta;
+  if (!raw?.receipt) return null;
+  const r = raw.receipt;
+  const receipt = {
+    receiptId: r.receipt_id ?? "",
+    transactionId: r.transaction_id,
+    timestamp: r.timestamp ?? "",
+    estimatedCredits: r.estimated_credits ?? 0,
+    actualCredits: r.actual_credits ?? 0,
+    netCredits: r.net_credits ?? 0,
+    savings: r.savings ?? 0,
+    savingsBonus: r.savings_bonus ?? 0,
+    balanceBefore: r.balance_before,
+    balanceAfter: r.balance_after,
+    breakdown: r.breakdown ?? {},
+    byok: {
+      enabled: r.byok?.enabled ?? false,
+      discountApplied: r.byok?.discount_applied ?? 0,
+      discountRate: r.byok?.discount_rate ?? 0
+    }
+  };
+  const e = raw.credit_estimate;
+  const creditEstimate = e ? {
+    estimatedTotal: e.estimated_total ?? 0,
+    actualTotal: e.actual_total ?? 0,
+    netTotal: e.net_total ?? 0,
+    breakdown: e.breakdown ?? {}
+  } : void 0;
+  return { receipt, creditEstimate };
+}
+
+// src/index.ts
+var version = "0.1.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthError,
+  Client,
+  ConduitError,
+  ConduitIdentity,
+  DEFAULT_IDENTITY_DIR,
+  DG_CA_URL,
+  DG_SUBSTRATE_ENDPOINT,
+  GuidedSession,
+  InvalidConfigError,
+  NetworkError,
+  NotInitializedError,
+  OAuthTokenProvider,
+  RateLimitError,
+  ServerError,
+  deriveTokenEndpoint,
+  extractMeta,
+  fetchDgCaCert,
+  fetchWithIdentity,
+  generateKeypair,
+  isDgUrl,
+  refreshCaCert,
+  registerIdentity,
+  rotateIdentity,
+  saveIdentity,
+  version
+});