@tangle-network/tcloud 0.1.4 → 0.3.0

package/dist/index.cjs

@@ -30,6 +30,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BridgeSession: () => BridgeSession,
+  PrivateRouter: () => PrivateRouter,
   TCloud: () => TCloud,
   TCloudClient: () => TCloudClient,
   TCloudError: () => TCloudError,
@@ -40,6 +42,219 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/private-router.ts
+function secureRandom() {
+  const arr = new Uint32Array(1);
+  crypto.getRandomValues(arr);
+  return arr[0] / (4294967295 + 1);
+}
+var PrivateRouter = class {
+  config;
+  operators = [];
+  usage = /* @__PURE__ */ new Map();
+  currentIndex = 0;
+  totalRequests = 0;
+  constructor(config = {}) {
+    this.config = {
+      strategy: config.strategy || "round-robin",
+      maxRequestsPerOperator: config.maxRequestsPerOperator || 5,
+      minOperators: config.minOperators || 3,
+      preferRegions: config.preferRegions,
+      excludeOperators: config.excludeOperators,
+      summarizeOnSwitch: config.summarizeOnSwitch ?? false
+    };
+  }
+  /** Set the available operator pool */
+  setOperators(operators) {
+    let filtered = operators.filter(
+      (o) => !this.config.excludeOperators?.includes(o.slug)
+    );
+    if (this.config.preferRegions?.length) {
+      filtered.sort((a, b) => {
+        const aPreferred = this.config.preferRegions.includes(a.region) ? 0 : 1;
+        const bPreferred = this.config.preferRegions.includes(b.region) ? 0 : 1;
+        return aPreferred - bPreferred;
+      });
+    }
+    this.operators = filtered;
+  }
+  /** Select the next operator for a request */
+  selectOperator(model) {
+    const eligible = this.operators.filter((o) => o.models.includes(model));
+    if (eligible.length === 0) return null;
+    if (eligible.length < this.config.minOperators) {
+      console.warn(
+        `[PrivateRouter] Only ${eligible.length} eligible operator(s) for model "${model}", but minOperators requires ${this.config.minOperators}. Refusing to route.`
+      );
+      return null;
+    }
+    this.totalRequests++;
+    switch (this.config.strategy) {
+      case "round-robin":
+        return this.roundRobin(eligible);
+      case "random":
+        return this.random(eligible);
+      case "geo-distributed":
+        return this.geoDistributed(eligible);
+      case "min-exposure":
+        return this.minExposure(eligible);
+      case "latency-aware":
+        return this.latencyAware(eligible);
+      default:
+        return this.roundRobin(eligible);
+    }
+  }
+  /** Should we summarize context before this request? (operator is changing) */
+  shouldSummarize(model) {
+    if (!this.config.summarizeOnSwitch) return false;
+    const next = this.peekNextOperator(model);
+    const last = this.getLastUsedOperator();
+    return next !== null && last !== null && next.slug !== last.slug;
+  }
+  /** Get privacy stats */
+  getStats() {
+    return {
+      totalRequests: this.totalRequests,
+      operatorsUsed: this.usage.size,
+      operatorBreakdown: Array.from(this.usage.values()).map((u) => ({
+        slug: u.slug,
+        requests: u.requestCount,
+        lastUsed: u.lastUsedAt
+      })),
+      strategy: this.config.strategy
+    };
+  }
+  // ─── Strategies ────────────────────────────────────────────
+  roundRobin(eligible) {
+    const op = eligible[this.currentIndex % eligible.length];
+    this.currentIndex++;
+    this.recordUsage(op);
+    return op;
+  }
+  random(eligible) {
+    const idx = Math.floor(secureRandom() * eligible.length);
+    const op = eligible[idx];
+    this.recordUsage(op);
+    return op;
+  }
+  geoDistributed(eligible) {
+    const regionUsage = /* @__PURE__ */ new Map();
+    for (const op2 of eligible) {
+      const usage = this.usage.get(op2.slug)?.requestCount || 0;
+      const current = regionUsage.get(op2.region) || 0;
+      regionUsage.set(op2.region, current + usage);
+    }
+    const sortedRegions = [...regionUsage.entries()].sort((a, b) => a[1] - b[1]);
+    const targetRegion = sortedRegions[0]?.[0];
+    const regionOps = eligible.filter((o) => o.region === targetRegion);
+    const op = regionOps[Math.floor(secureRandom() * regionOps.length)] || eligible[0];
+    this.recordUsage(op);
+    return op;
+  }
+  minExposure(eligible) {
+    const lastUsed = this.getLastUsedOperator();
+    if (lastUsed) {
+      const lastUsage = this.usage.get(lastUsed.slug);
+      const others = eligible.filter((o) => o.slug !== lastUsed.slug);
+      if (others.length > 0 && lastUsage && lastUsage.requestCount > 0) {
+        const sorted2 = others.sort(
+          (a, b) => (this.usage.get(a.slug)?.requestCount || 0) - (this.usage.get(b.slug)?.requestCount || 0)
+        );
+        const op2 = sorted2[0];
+        this.recordUsage(op2);
+        return op2;
+      }
+    }
+    const sorted = [...eligible].sort(
+      (a, b) => (this.usage.get(a.slug)?.requestCount || 0) - (this.usage.get(b.slug)?.requestCount || 0)
+    );
+    const op = sorted[0];
+    this.recordUsage(op);
+    return op;
+  }
+  latencyAware(eligible) {
+    const weights = eligible.map((o) => {
+      const latencyWeight = 1 / Math.max(o.avgLatencyMs, 10);
+      const usagePenalty = (this.usage.get(o.slug)?.requestCount || 0) * 0.1;
+      return Math.max(latencyWeight - usagePenalty, 0.01);
+    });
+    const totalWeight = weights.reduce((s, w) => s + w, 0);
+    let r = secureRandom() * totalWeight;
+    for (let i = 0; i < eligible.length; i++) {
+      r -= weights[i];
+      if (r <= 0) {
+        this.recordUsage(eligible[i]);
+        return eligible[i];
+      }
+    }
+    const op = eligible[eligible.length - 1];
+    this.recordUsage(op);
+    return op;
+  }
+  // ─── Helpers ───────────────────────────────────────────────
+  recordUsage(op) {
+    const existing = this.usage.get(op.slug);
+    this.usage.set(op.slug, {
+      slug: op.slug,
+      requestCount: (existing?.requestCount || 0) + 1,
+      lastUsedAt: Date.now()
+    });
+  }
+  getLastUsedOperator() {
+    let latest = null;
+    for (const u of this.usage.values()) {
+      if (!latest || u.lastUsedAt > latest.lastUsedAt) latest = u;
+    }
+    if (!latest) return null;
+    return this.operators.find((o) => o.slug === latest.slug) || null;
+  }
+  peekNextOperator(model) {
+    const eligible = this.operators.filter((o) => o.models.includes(model));
+    if (eligible.length === 0) return null;
+    if (eligible.length < this.config.minOperators) return null;
+    const last = this.getLastUsedOperator();
+    switch (this.config.strategy) {
+      case "round-robin":
+        return eligible[this.currentIndex % eligible.length];
+      case "min-exposure": {
+        if (last) {
+          const lastUsage = this.usage.get(last.slug);
+          const others = eligible.filter((o) => o.slug !== last.slug);
+          if (others.length > 0 && lastUsage && lastUsage.requestCount > 0) {
+            const sorted2 = others.sort(
+              (a, b) => (this.usage.get(a.slug)?.requestCount || 0) - (this.usage.get(b.slug)?.requestCount || 0)
+            );
+            return sorted2[0];
+          }
+        }
+        const sorted = [...eligible].sort(
+          (a, b) => (this.usage.get(a.slug)?.requestCount || 0) - (this.usage.get(b.slug)?.requestCount || 0)
+        );
+        return sorted[0];
+      }
+      case "geo-distributed": {
+        const regionUsage = /* @__PURE__ */ new Map();
+        for (const op of eligible) {
+          const usage = this.usage.get(op.slug)?.requestCount || 0;
+          const current = regionUsage.get(op.region) || 0;
+          regionUsage.set(op.region, current + usage);
+        }
+        const sortedRegions = [...regionUsage.entries()].sort((a, b) => a[1] - b[1]);
+        const targetRegion = sortedRegions[0]?.[0];
+        const regionOps = eligible.filter((o) => o.region === targetRegion);
+        return regionOps[0] || eligible[0];
+      }
+      case "random":
+      case "latency-aware":
+      default:
+        if (last && eligible.length > 1) {
+          return eligible.find((o) => o.slug !== last.slug) || eligible[0];
+        }
+        return eligible[0];
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://router.tangle.tools/v1";
 async function proxiedFetch(privacy, url, init, streaming) {
@@ -80,25 +295,44 @@ async function proxiedFetch(privacy, url, init, streaming) {
   }
   return fetch(url, init);
 }
-var TCloudClient = class {
+var DEFAULT_RETRY = {
+  maxRetries: 3,
+  initialBackoffMs: 500,
+  maxBackoffMs: 3e4,
+  multiplier: 2,
+  retryableStatuses: [429, 500, 502, 503, 504]
+};
+var DEFAULT_TIMEOUT_MS = 6e4;
+var DEFAULT_PLATFORM_URL = "https://id.tangle.tools";
+var TCloudClient = class _TCloudClient {
   baseURL;
+  platformURL;
   apiKey;
   model;
   headers;
   spendAuthFn;
   privacy;
   limits;
+  retryConfig;
+  timeoutMs;
   _totalSpent = 0;
   _requestCount = 0;
+  privateRouter;
+  _cachedOperators = [];
+  _operatorsCachedAt = 0;
+  static OPERATORS_TTL_MS = 5 * 60 * 1e3;
   constructor(config = {}) {
     this.baseURL = (config.baseURL || DEFAULT_BASE_URL).replace(/\/$/, "");
-    this.apiKey = config.apiKey || process.env.TCLOUD_API_KEY || process.env.OPENAI_API_KEY;
+    this.platformURL = (config.platformURL || DEFAULT_PLATFORM_URL).replace(/\/$/, "");
+    this.apiKey = config.apiKey || process.env.TCLOUD_API_KEY;
     this.model = config.model || "gpt-4o-mini";
     this.privacy = config.privacy;
     this.limits = config.limits;
+    this.retryConfig = config.retry === false ? null : { ...DEFAULT_RETRY, ...config.retry };
+    this.timeoutMs = config.timeout ?? DEFAULT_TIMEOUT_MS;
     this.headers = {
       "Content-Type": "application/json",
-      "X-Tangle-Client": "tcloud-sdk/0.1.4"
+      "X-Tangle-Client": "tcloud-sdk/0.2.0"
     };
     if (this.apiKey) {
       this.headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -118,6 +352,17 @@ var TCloudClient = class {
     if (config.routing?.region) {
       this.headers["X-Tangle-Region"] = config.routing.region;
     }
+    if (config.routing?.strategy) {
+      const strategyMap = {
+        "round-robin": "round-robin",
+        "lowest-latency": "latency-aware",
+        "lowest-price": "round-robin",
+        "highest-reputation": "round-robin"
+      };
+      this.privateRouter = new PrivateRouter({
+        strategy: strategyMap[config.routing.strategy] || "round-robin"
+      });
+    }
   }
   /** Set the SpendAuth signer for private mode */
   setSpendAuthSigner(fn) {
@@ -151,6 +396,25 @@ var TCloudClient = class {
       if (pct >= 0.8) this.limits.onLimitWarning({ type: "total", current: this._totalSpent, limit: this.limits.maxTotalSpend });
     }
   }
+  /** Ensure the private router has operators loaded (with TTL-based caching) */
+  async ensureRouterOperators() {
+    if (!this.privateRouter) return;
+    const now = Date.now();
+    if (this._cachedOperators.length > 0 && now - this._operatorsCachedAt < _TCloudClient.OPERATORS_TTL_MS) {
+      return;
+    }
+    const data = await this.operators();
+    this._cachedOperators = (data.operators || []).map((op) => ({
+      slug: op.slug,
+      endpointUrl: op.endpointUrl,
+      region: "",
+      reputationScore: op.reputationScore,
+      avgLatencyMs: op.avgLatencyMs,
+      models: op.models.map((m) => m.modelId)
+    }));
+    this._operatorsCachedAt = now;
+    this.privateRouter.setOperators(this._cachedOperators);
+  }
   /** Track cost after a response, using actual pricing from response headers when available */
   trackCost(completion, res) {
     this._requestCount++;
@@ -170,36 +434,154 @@ var TCloudClient = class {
       }
     }
   }
-  /** Chat completion (non-streaming) */
-  async chat(options) {
+  /**
+   * Core fetch with retry + timeout. All helpers build on this.
+   * Retries on retryable status codes with exponential backoff + jitter.
+   */
+  async _doFetch(url, init, streaming) {
+    const retry = this.retryConfig;
+    const maxAttempts = retry ? retry.maxRetries + 1 : 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const controller = new AbortController();
+      let timer;
+      if (this.timeoutMs > 0 && !streaming) {
+        timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      }
+      try {
+        const res = await proxiedFetch(this.privacy, url, {
+          ...init,
+          signal: controller.signal
+        }, streaming);
+        if (res.ok) return res;
+        if (retry && attempt < retry.maxRetries && retry.retryableStatuses.includes(res.status)) {
+          const backoff = Math.min(
+            retry.initialBackoffMs * Math.pow(retry.multiplier, attempt),
+            retry.maxBackoffMs
+          );
+          const jitter = backoff * 0.5 * Math.random();
+          await new Promise((r) => setTimeout(r, backoff + jitter));
+          continue;
+        }
+        const err = await res.json().catch(() => ({ error: res.statusText }));
+        throw new TCloudError(res.status, err.error?.message || err.error || err.message || res.statusText);
+      } catch (e) {
+        if (e instanceof TCloudError) throw e;
+        if (retry && attempt < retry.maxRetries) {
+          const backoff = Math.min(
+            retry.initialBackoffMs * Math.pow(retry.multiplier, attempt),
+            retry.maxBackoffMs
+          );
+          await new Promise((r) => setTimeout(r, backoff));
+          continue;
+        }
+        if (e?.name === "AbortError") {
+          throw new TCloudError(408, `Request timed out after ${this.timeoutMs}ms`);
+        }
+        throw new TCloudError(0, e?.message || "Network error");
+      } finally {
+        if (timer !== void 0) clearTimeout(timer);
+      }
+    }
+    throw new TCloudError(0, "Retry loop exhausted");
+  }
+  /**
+   * Shared request helper for billable JSON API calls.
+   * Enforces: checkLimits → fetch with retry/timeout → error parsing → requestCount.
+   */
+  async _request(url, init = {}) {
     this.checkLimits();
+    const res = await this._doFetch(url, { headers: this.headers, ...init }, false);
+    this._requestCount++;
+    return res.json();
+  }
+  /**
+   * Shared request helper for read-only/non-billable JSON API calls.
+   * No limits check, no request counting.
+   */
+  async _fetch(url, init = {}) {
+    const res = await this._doFetch(url, { headers: this.headers, ...init }, false);
+    return res.json();
+  }
+  /**
+   * Shared request helper for billable calls that return non-JSON (e.g. ArrayBuffer).
+   */
+  async _requestRaw(url, init = {}) {
+    this.checkLimits();
+    const res = await this._doFetch(url, { headers: this.headers, ...init }, false);
+    this._requestCount++;
+    return res;
+  }
+  /**
+   * Prepare headers for chat requests — operator routing + SpendAuth +
+   * bridge short-circuit headers when `options.bridge` is set.
+   * Shared between chat() and chatStream() to eliminate duplication.
+   */
+  async _prepareChatRequest(model, bridge) {
     const headers = { ...this.headers };
     if (this.spendAuthFn) {
       const auth = await this.spendAuthFn();
       headers["X-Payment-Signature"] = JSON.stringify(auth);
       delete headers["Authorization"];
     }
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/chat/completions`, {
+    let baseURL = this.baseURL;
+    if (this.privateRouter) {
+      await this.ensureRouterOperators();
+      const operator = this.privateRouter.selectOperator(model);
+      if (operator) {
+        baseURL = operator.endpointUrl.replace(/\/$/, "");
+        headers["X-Tangle-Operator"] = operator.slug;
+        delete headers["Authorization"];
+      }
+    }
+    if (bridge) {
+      headers["X-Bridge-Unlock"] = bridge.unlock;
+      if (bridge.resume) headers["X-Resume"] = bridge.resume;
+      if (bridge.bridgeUrl) headers["X-Bridge-Url"] = bridge.bridgeUrl;
+      if (bridge.bridgeBearer) headers["X-Bridge-Bearer"] = bridge.bridgeBearer;
+    }
+    return { headers, baseURL };
+  }
+  /**
+   * Resolve the effective model string. When a bridge is set, rewrite to
+   * `bridge/<harness>/<model>` (or `bridge/<harness>` if no model).
+   */
+  _effectiveModel(options) {
+    if (options.bridge) {
+      return options.bridge.model ? `bridge/${options.bridge.harness}/${options.bridge.model}` : `bridge/${options.bridge.harness}`;
+    }
+    return options.model || this.model;
+  }
+  /** Build the chat completions request body */
+  _chatBody(options, stream) {
+    return JSON.stringify({
+      model: this._effectiveModel(options),
+      messages: options.messages,
+      temperature: options.temperature,
+      max_tokens: options.maxTokens,
+      stream,
+      stop: options.stop,
+      top_p: options.topP,
+      frequency_penalty: options.frequencyPenalty,
+      presence_penalty: options.presencePenalty,
+      response_format: options.responseFormat,
+      tools: options.tools,
+      tool_choice: options.toolChoice,
+      ...options.gateway ? { gateway: options.gateway } : {},
+      ...options.providerOptions
+    });
+  }
+  /** Chat completion (non-streaming) */
+  async chat(options) {
+    this.checkLimits();
+    const { headers, baseURL } = await this._prepareChatRequest(
+      this._effectiveModel(options),
+      options.bridge
+    );
+    const res = await this._doFetch(`${baseURL}/chat/completions`, {
       method: "POST",
       headers,
-      body: JSON.stringify({
-        model: options.model || this.model,
-        messages: options.messages,
-        temperature: options.temperature,
-        max_tokens: options.maxTokens,
-        stream: false,
-        stop: options.stop,
-        top_p: options.topP,
-        frequency_penalty: options.frequencyPenalty,
-        presence_penalty: options.presencePenalty,
-        response_format: options.responseFormat,
-        tools: options.tools
-      })
+      body: this._chatBody(options, false)
     }, false);
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({ error: res.statusText }));
-      throw new TCloudError(res.status, err.error?.message || err.error || err.message || res.statusText);
-    }
     const completion = await res.json();
     this.trackCost(completion, res);
     return completion;
@@ -207,29 +589,16 @@ var TCloudClient = class {
   /** Chat completion (streaming) — returns an async iterator of chunks */
   async *chatStream(options) {
     this.checkLimits();
-    const headers = { ...this.headers };
-    if (this.spendAuthFn) {
-      const auth = await this.spendAuthFn();
-      headers["X-Payment-Signature"] = JSON.stringify(auth);
-      delete headers["Authorization"];
-    }
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/chat/completions`, {
+    this._requestCount++;
+    const { headers, baseURL } = await this._prepareChatRequest(
+      this._effectiveModel(options),
+      options.bridge
+    );
+    const res = await this._doFetch(`${baseURL}/chat/completions`, {
       method: "POST",
       headers,
-      body: JSON.stringify({
-        model: options.model || this.model,
-        messages: options.messages,
-        temperature: options.temperature,
-        max_tokens: options.maxTokens,
-        stream: true,
-        stop: options.stop,
-        top_p: options.topP
-      })
+      body: this._chatBody(options, true)
     }, true);
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({ error: res.statusText }));
-      throw new TCloudError(res.status, err.error || err.message || res.statusText);
-    }
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buf = "";
@@ -237,13 +606,13 @@ var TCloudClient = class {
       const { done, value } = await reader.read();
       if (done) break;
       buf += decoder.decode(value, { stream: true });
+      if (buf.length > 1048576) throw new TCloudError(502, "SSE buffer overflow \u2014 server sent >1MB without newline");
       const lines = buf.split("\n");
       buf = lines.pop() || "";
       for (const line of lines) {
         if (!line.startsWith("data: ")) continue;
         const data = line.slice(6).trim();
         if (data === "[DONE]") {
-          this._requestCount++;
           return;
         }
         try {
@@ -253,6 +622,24 @@ var TCloudClient = class {
       }
     }
   }
+  /**
+   * Bridge — scoped helper for a subscription-backed CLI harness behind
+   * the Tangle Router's cli-bridge. Returns a mini-client bound to
+   * (harness, unlock, resume) so you don't thread those through every
+   * call.
+   *
+   * ```ts
+   * const kimi = tcloud.bridge({ harness: 'kimi', model: 'kimi-for-coding', unlock: UNLOCK, resume: 'pr-42' })
+   * await kimi.ask('review this diff…')
+   * for await (const chunk of kimi.stream('continue…')) process.stdout.write(chunk)
+   * ```
+   *
+   * Sessions persist across process restarts — use the same `resume` id
+   * to land on the same CLI conversation (context intact, no replay tax).
+   */
+  bridge(cfg) {
+    return new BridgeSession(this, cfg);
+  }
   /** Convenience: send a single message and get the text response */
   async ask(message, modelOrOptions) {
     const options = typeof modelOrOptions === "string" ? { model: modelOrOptions } : modelOrOptions;
@@ -283,85 +670,112 @@ var TCloudClient = class {
   }
   /** List available models */
   async models() {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/models`, { headers: this.headers }, false);
-    if (!res.ok) throw new TCloudError(res.status, "Failed to fetch models");
-    const data = await res.json();
+    const data = await this._fetch(`${this.baseURL}/models`);
     return data.data || [];
   }
   /** List active operators */
   async operators() {
     const apiRoot = this.baseURL.replace(/\/v1$/, "");
-    const res = await proxiedFetch(this.privacy, `${apiRoot}/api/operators`, { headers: this.headers }, false);
-    if (!res.ok) throw new TCloudError(res.status, "Failed to fetch operators");
-    return res.json();
+    return this._fetch(`${apiRoot}/api/operators`);
   }
+  // ── Billing (via id.tangle.tools) ──
   /** Get credit balance */
   async credits() {
-    const apiRoot = this.baseURL.replace(/\/v1$/, "");
-    const res = await proxiedFetch(this.privacy, `${apiRoot}/api/billing`, { headers: this.headers }, false);
-    if (!res.ok) throw new TCloudError(res.status, "Failed to fetch credits");
-    return res.json();
+    const { data } = await this._fetch(`${this.platformURL}/v1/billing/balance`);
+    return data;
   }
-  /** Add credits */
+  /** Add credits via Stripe checkout. Returns the checkout URL. */
   async addCredits(amount) {
-    const apiRoot = this.baseURL.replace(/\/v1$/, "");
-    const res = await proxiedFetch(this.privacy, `${apiRoot}/api/billing`, {
+    const { data } = await this._fetch(`${this.platformURL}/v1/billing/topup`, {
       method: "POST",
-      headers: this.headers,
       body: JSON.stringify({ amount })
-    }, false);
-    if (!res.ok) throw new TCloudError(res.status, "Failed to add credits");
-    return res.json();
+    });
+    return data;
   }
-  /** Create a new API key */
-  async createKey(name) {
-    const apiRoot = this.baseURL.replace(/\/v1$/, "");
-    const res = await proxiedFetch(this.privacy, `${apiRoot}/api/keys`, {
+  /** Get transaction history */
+  async transactions(limit = 50) {
+    const { data } = await this._fetch(`${this.platformURL}/v1/billing/transactions?limit=${limit}`);
+    return data;
+  }
+  // ── API Keys (via id.tangle.tools) ──
+  /**
+   * Create a new API key.
+   * When called with an API key (not session), the new key is automatically
+   * a child of the calling key — enabling hierarchical key delegation.
+   *
+   * Pass `parentKeyId` explicitly to create a child of a specific key.
+   * Child keys inherit the parent's product scope, allowedModels, and rpmLimit
+   * if not specified. Budget cannot exceed the parent's remaining budget.
+   */
+  async createKey(opts) {
+    const { data } = await this._fetch(`${this.platformURL}/v1/keys`, {
       method: "POST",
-      headers: this.headers,
-      body: JSON.stringify({ name })
-    }, false);
-    if (!res.ok) throw new TCloudError(res.status, "Failed to create API key");
-    return res.json();
+      body: JSON.stringify(opts)
+    });
+    return data;
   }
-  /** List API keys */
-  async keys() {
-    const apiRoot = this.baseURL.replace(/\/v1$/, "");
-    const res = await proxiedFetch(this.privacy, `${apiRoot}/api/keys`, { headers: this.headers }, false);
-    if (!res.ok) throw new TCloudError(res.status, "Failed to fetch keys");
-    return res.json();
+  /** Get a single API key by ID */
+  async getKey(id) {
+    const { data } = await this._fetch(`${this.platformURL}/v1/keys/${id}`);
+    return data;
+  }
+  /**
+   * List API keys.
+   * Pass `children: true` to list child keys of the calling API key.
+   */
+  async keys(opts) {
+    const q = opts?.children ? "?children=true" : "";
+    const { data } = await this._fetch(`${this.platformURL}/v1/keys${q}`);
+    return data;
+  }
+  /**
+   * Update an API key's limits.
+   * Can adjust budget, allowedModels, rpmLimit, expiresAt, and name.
+   */
+  async updateKey(id, updates) {
+    const { data } = await this._fetch(`${this.platformURL}/v1/keys/${id}`, {
+      method: "PATCH",
+      body: JSON.stringify(updates)
+    });
+    return data;
   }
-  /** Revoke an API key */
+  /** Revoke an API key. If the key has children, they are also revoked recursively. */
   async revokeKey(id) {
-    const apiRoot = this.baseURL.replace(/\/v1$/, "");
-    const res = await proxiedFetch(this.privacy, `${apiRoot}/api/keys/${id}`, {
-      method: "DELETE",
-      headers: this.headers
-    }, false);
-    if (!res.ok) throw new TCloudError(res.status, "Failed to revoke key");
+    await this._fetch(`${this.platformURL}/v1/keys/${id}`, { method: "DELETE" });
+  }
+  /** Rotate an API key — creates new key with same config, revokes old */
+  async rotateKey(id) {
+    const { data } = await this._fetch(`${this.platformURL}/v1/keys/${id}/rotate`, { method: "POST" });
+    return data;
+  }
+  // ── Projects (via id.tangle.tools) ──
+  /** Create a project for usage attribution */
+  async createProject(name, product) {
+    const { data } = await this._fetch(`${this.platformURL}/v1/projects`, {
+      method: "POST",
+      body: JSON.stringify({ name, product })
+    });
+    return data;
+  }
+  /** List projects */
+  async projects() {
+    const { data } = await this._fetch(`${this.platformURL}/v1/projects`);
+    return data;
   }
   /** Generate embeddings */
   async embeddings(options) {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/embeddings`, {
+    return this._request(`${this.baseURL}/embeddings`, {
       method: "POST",
-      headers: this.headers,
       body: JSON.stringify({
         model: options.model || "text-embedding-3-small",
         input: options.input
       })
-    }, false);
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({ error: res.statusText }));
-      throw new TCloudError(res.status, err.error?.message || err.error || res.statusText);
-    }
-    this._requestCount++;
-    return res.json();
+    });
   }
   /** Generate images */
   async imageGenerate(options) {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/images/generations`, {
+    return this._request(`${this.baseURL}/images/generations`, {
       method: "POST",
-      headers: this.headers,
       body: JSON.stringify({
         model: options.model || "dall-e-3",
         prompt: options.prompt,
@@ -370,56 +784,36 @@ var TCloudClient = class {
         quality: options.quality,
         response_format: options.response_format
       })
-    }, false);
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({ error: res.statusText }));
-      throw new TCloudError(res.status, err.error?.message || err.error || res.statusText);
-    }
-    this._requestCount++;
-    return res.json();
+    });
   }
   /** Rerank documents by relevance to a query */
   async rerank(options) {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/rerank`, {
+    return this._request(`${this.baseURL}/rerank`, {
       method: "POST",
-      headers: this.headers,
       body: JSON.stringify({
         model: options.model || "rerank-english-v3.0",
         query: options.query,
         documents: options.documents,
         top_n: options.top_n
       })
-    }, false);
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({ error: res.statusText }));
-      throw new TCloudError(res.status, err.error?.message || err.error || res.statusText);
-    }
-    this._requestCount++;
-    return res.json();
+    });
   }
   /** Text-to-speech */
   async speech(options) {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/audio/speech`, {
+    const res = await this._requestRaw(`${this.baseURL}/audio/speech`, {
       method: "POST",
-      headers: this.headers,
       body: JSON.stringify({
         model: options.model || "tts-1",
         input: options.input,
         voice: options.voice || "alloy"
       })
-    }, false);
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({ error: res.statusText }));
-      throw new TCloudError(res.status, err.error?.message || err.error || res.statusText);
-    }
-    this._requestCount++;
+    });
     return res.arrayBuffer();
   }
   /** Legacy completions endpoint */
   async completions(options) {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/completions`, {
+    return this._request(`${this.baseURL}/completions`, {
       method: "POST",
-      headers: this.headers,
       body: JSON.stringify({
         model: options.model || this.model,
         prompt: options.prompt,
@@ -428,13 +822,7 @@ var TCloudClient = class {
         stop: options.stop,
         top_p: options.topP
       })
-    }, false);
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({ error: res.statusText }));
-      throw new TCloudError(res.status, err.error?.message || err.error || res.statusText);
-    }
-    this._requestCount++;
-    return res.json();
+    });
   }
   /** Audio transcription (speech-to-text) */
   async transcribe(file, options) {
@@ -445,6 +833,7 @@ var TCloudClient = class {
     if (options?.prompt) formData.append("prompt", options.prompt);
     const headers = { ...this.headers };
     delete headers["Content-Type"];
+    this.checkLimits();
     const res = await proxiedFetch(this.privacy, `${this.baseURL}/audio/transcriptions`, {
       method: "POST",
       headers,
@@ -452,75 +841,181 @@ var TCloudClient = class {
     }, false);
     if (!res.ok) {
       const err = await res.json().catch(() => ({ error: res.statusText }));
-      throw new TCloudError(res.status, err.error?.message || err.error || res.statusText);
+      throw new TCloudError(res.status, err.error?.message || err.error || err.message || res.statusText);
     }
     this._requestCount++;
     return res.json();
   }
   /** Create a fine-tuning job */
   async fineTuneCreate(options) {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/fine_tuning/jobs`, {
+    return this._request(`${this.baseURL}/fine_tuning/jobs`, {
       method: "POST",
-      headers: this.headers,
       body: JSON.stringify(options)
-    }, false);
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({ error: res.statusText }));
-      throw new TCloudError(res.status, err.error?.message || err.error || res.statusText);
-    }
-    this._requestCount++;
-    return res.json();
+    });
   }
   /** List fine-tuning jobs */
   async fineTuneList() {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/fine_tuning/jobs`, {
-      headers: this.headers
-    }, false);
-    if (!res.ok) throw new TCloudError(res.status, "Failed to fetch fine-tuning jobs");
-    return res.json();
+    return this._fetch(`${this.baseURL}/fine_tuning/jobs`);
   }
   /** Submit a batch of chat requests */
   async batch(requests) {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/batch`, {
+    return this._request(`${this.baseURL}/batch`, {
       method: "POST",
-      headers: this.headers,
       body: JSON.stringify({ requests })
-    }, false);
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({ error: res.statusText }));
-      throw new TCloudError(res.status, err.error?.message || err.error || res.statusText);
-    }
-    return res.json();
+    });
   }
   /** Get batch job status */
   async batchStatus(jobId) {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/batch?id=${jobId}`, {
-      headers: this.headers
-    }, false);
-    if (!res.ok) throw new TCloudError(res.status, "Failed to fetch batch status");
-    return res.json();
+    return this._fetch(`${this.baseURL}/batch?id=${jobId}`);
   }
   /** Generate video */
   async videoGenerate(options) {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/video/generate`, {
+    return this._request(`${this.baseURL}/video/generate`, {
       method: "POST",
-      headers: this.headers,
       body: JSON.stringify(options)
-    }, false);
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({ error: res.statusText }));
-      throw new TCloudError(res.status, err.error?.message || err.error || res.statusText);
-    }
-    this._requestCount++;
-    return res.json();
+    });
   }
   /** Get video generation status */
   async videoStatus(id) {
-    const res = await proxiedFetch(this.privacy, `${this.baseURL}/video?id=${id}`, {
-      headers: this.headers
-    }, false);
-    if (!res.ok) throw new TCloudError(res.status, "Failed to fetch video status");
-    return res.json();
+    return this._fetch(`${this.baseURL}/video?id=${id}`);
+  }
+  /** Generate an avatar video (lip-synced talking head from audio + face image).
+   *  Returns 202 with a job_id for async polling via avatarJobStatus(). */
+  async avatarGenerate(options) {
+    return this._request(`${this.baseURL}/avatar/generate`, {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /** Poll an avatar generation job by ID. */
+  async avatarJobStatus(jobId) {
+    return this._fetch(`${this.baseURL}/avatar/jobs/${jobId}`);
+  }
+  /** Poll an avatar job until it reaches a terminal state (completed/failed).
+   *  Returns the final job status. Throws on failure. */
+  async pollAvatarJob(jobId, options) {
+    const interval = options?.intervalMs ?? 5e3;
+    const timeout = options?.timeoutMs ?? 3e5;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const job = await this.avatarJobStatus(jobId);
+      if (job.status === "completed") return job;
+      if (job.status === "failed") {
+        throw new TCloudError(500, job.error || `Avatar job ${jobId} failed`);
+      }
+      await new Promise((r) => setTimeout(r, interval));
+    }
+    throw new TCloudError(408, `Avatar job ${jobId} timed out after ${timeout}ms`);
+  }
+  /**
+   * Watch an async job via SSE until it reaches a terminal state.
+   * Works with avatar, video, and training blueprint operators.
+   *
+   * @param jobId - The job ID returned by the creation endpoint
+   * @param options - Optional: operatorUrl override, onEvent callback
+   * @returns The final JobEvent (completed/failed/cancelled)
+   */
+  async watchJob(jobId, options) {
+    const base = options?.operatorUrl?.replace(/\/$/, "") || this.baseURL;
+    const url = `${base}/v1/jobs/${encodeURIComponent(jobId)}/events`;
+    const timeout = options?.timeout ?? 3e5;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+      const watchHeaders = {
+        ...this.headers,
+        Accept: "text/event-stream"
+      };
+      if (options?.operatorUrl) {
+        delete watchHeaders["Authorization"];
+      }
+      if (options?.sseToken) {
+        watchHeaders["Authorization"] = `Bearer ${options.sseToken}`;
+      }
+      const res = await proxiedFetch(this.privacy, url, {
+        headers: watchHeaders,
+        signal: controller.signal
+      }, true);
+      if (!res.ok) {
+        const err = await res.json().catch(() => ({ error: res.statusText }));
+        throw new TCloudError(res.status, err.error?.message || err.error || res.statusText);
+      }
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buf = "";
+      const terminalStatuses = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          throw new TCloudError(502, `SSE stream ended without terminal event for job ${jobId}`);
+        }
+        buf += decoder.decode(value, { stream: true });
+        if (buf.length > 1048576) throw new TCloudError(502, "SSE buffer overflow \u2014 server sent >1MB without newline");
+        const lines = buf.split("\n");
+        buf = lines.pop() || "";
+        for (const line of lines) {
+          if (!line.startsWith("data: ")) continue;
+          const data = line.slice(6).trim();
+          if (!data || data === "[DONE]") continue;
+          let event;
+          try {
+            event = JSON.parse(data);
+          } catch {
+            continue;
+          }
+          try {
+            options?.onEvent?.(event);
+          } catch (cbErr) {
+            console.error("watchJob onEvent callback error:", cbErr);
+          }
+          if (terminalStatuses.has(event.status)) {
+            return event;
+          }
+        }
+      }
+    } catch (err) {
+      if (err?.name === "AbortError") {
+        throw new TCloudError(408, `Job ${jobId} timed out after ${timeout}ms`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Vector Store (requires operator routing — X-Tangle-Service/Blueprint/Operator)
+  // ---------------------------------------------------------------------------
+  /** Create a vector collection on the operator's vector store */
+  async createCollection(options) {
+    return this._request(`${this.baseURL}/collections`, {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /** List collections on the operator's vector store */
+  async listCollections() {
+    return this._fetch(`${this.baseURL}/collections`);
+  }
+  /** Upsert vectors into a collection */
+  async upsertVectors(collection, vectors) {
+    return this._request(`${this.baseURL}/collections/${encodeURIComponent(collection)}/upsert`, {
+      method: "POST",
+      body: JSON.stringify({ vectors })
+    });
+  }
+  /** Similarity search in a collection */
+  async queryVectors(collection, options) {
+    return this._request(`${this.baseURL}/collections/${encodeURIComponent(collection)}/query`, {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /** RAG query — embed text + search collection in one call */
+  async ragQuery(options) {
+    return this._request(`${this.baseURL}/rag`, {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
   }
   /** Search models by name, provider, or capability */
   async searchModels(query) {
@@ -539,7 +1034,176 @@ var TCloudClient = class {
     const outputCost = options.outputTokens * parseFloat(model.pricing.completion);
     return { inputCost, outputCost, total: inputCost + outputCost };
   }
+  /**
+   * Get a pricing spectrum across resource tiers for a model.
+   *
+   * Uses REAL per-operator pricing from `operator.models[].inputPrice`.
+   * Each tier filters operators by GPU count and TEE capability, then
+   * reports the cheapest and most expensive operator for that config.
+   *
+   * @param options.model - Model ID to price (falls back to client default)
+   * @param options.tiers - Number of tiers (1-7, default 5)
+   */
+  async pricingSpectrum(options) {
+    const requestedTiers = Math.max(1, Math.min(options.tiers ?? 5, ALL_TIERS.length));
+    const modelId = options.model || this.model;
+    const selected = selectTiers(ALL_TIERS, requestedTiers);
+    const operatorData = await this.operators();
+    const allOperators = operatorData.operators || [];
+    return selected.map((tier) => {
+      const matching = allOperators.filter((op) => {
+        if (tier.gpu > 0 && (op.gpuCount ?? 0) < tier.gpu) return false;
+        if (tier.tee && !op.teeAttested) return false;
+        return true;
+      });
+      const prices = matching.map((op) => op.models.find((m) => m.modelId === modelId)?.inputPrice).filter((p) => p != null && p > 0).sort((a, b) => a - b);
+      const cheapestPrice = prices[0];
+      const priciestPrice = prices.length > 1 ? prices[prices.length - 1] : void 0;
+      return {
+        tier: tier.name,
+        config: tier,
+        cheapestPrice,
+        priciestPrice: priciestPrice !== cheapestPrice ? priciestPrice : void 0,
+        cheapest: cheapestPrice != null ? formatPrice(cheapestPrice) : "no operators for this config",
+        priciest: priciestPrice != null && priciestPrice !== cheapestPrice ? formatPrice(priciestPrice) : void 0,
+        availableOperators: matching.length,
+        operatorsWithModel: prices.length
+      };
+    });
+  }
+  // ── Eval ──────────────────────────────────────────────────────────────
+  get _apiRoot() {
+    return this.baseURL.replace(/\/v1$/, "");
+  }
+  async eval(opts) {
+    return this._request(`${this._apiRoot}/api/eval`, { method: "POST", body: JSON.stringify(opts) });
+  }
+  async createSuite(opts) {
+    return this._request(`${this._apiRoot}/api/eval/suites`, { method: "POST", body: JSON.stringify(opts) });
+  }
+  async listSuites() {
+    return this._fetch(`${this._apiRoot}/api/eval/suites`);
+  }
+  async runSuite(suiteId, opts) {
+    return this._request(`${this._apiRoot}/api/eval/suites/${suiteId}/runs`, { method: "POST", body: JSON.stringify(opts || {}) });
+  }
+  async listRuns(suiteId) {
+    return this._fetch(`${this._apiRoot}/api/eval/suites/${suiteId}/runs`);
+  }
+  async getRun(runId) {
+    return this._fetch(`${this._apiRoot}/api/eval/runs/${runId}`);
+  }
+  async setBaseline(runId) {
+    await this._request(`${this._apiRoot}/api/eval/runs/${runId}`, { method: "PATCH", body: JSON.stringify({ baseline: true }) });
+  }
+  // ── Sandbox ──────────────────────────────────────────────────────────
+  async sandboxPricing(opts) {
+    const p = new URLSearchParams();
+    if (opts?.cpu) p.set("cpu", String(opts.cpu));
+    if (opts?.ram) p.set("ram", String(opts.ram));
+    if (opts?.disk) p.set("disk", String(opts.disk));
+    return this._fetch(`${this._apiRoot}/api/sandbox/pricing?${p}`);
+  }
+  async sandboxStatus() {
+    return this._fetch(`${this._apiRoot}/api/sandbox/link-key`);
+  }
+  async sandboxProvision() {
+    return this._request(`${this._apiRoot}/api/sandbox/provision`, { method: "POST" });
+  }
+  async sandboxCreate(opts) {
+    return this._request(`${this._apiRoot}/api/sandbox/sessions`, { method: "POST", body: JSON.stringify(opts) });
+  }
+  async sandboxList() {
+    return this._fetch(`${this._apiRoot}/api/sandbox/sessions`);
+  }
+  async sandboxStats(sandboxId) {
+    return this._fetch(`${this._apiRoot}/api/sandbox/stats/${sandboxId}`);
+  }
+  async sandboxDestroy(sessionId) {
+    return this._request(`${this._apiRoot}/api/sandbox/sessions/${sessionId}`, { method: "DELETE" });
+  }
+  // ── User Info ────────────────────────────────────────────────────────
+  async userInfo() {
+    return this._fetch(`${this._apiRoot}/api/auth/userinfo`);
+  }
 };
+var ALL_TIERS = [
+  { name: "cpu-only", cpu: 4, ramGb: 16, gpu: 0, tee: false },
+  { name: "gpu", cpu: 8, ramGb: 32, gpu: 1, tee: false },
+  { name: "gpu-tee", cpu: 8, ramGb: 32, gpu: 1, tee: true },
+  { name: "multi-gpu", cpu: 32, ramGb: 128, gpu: 2, tee: false },
+  { name: "multi-gpu-tee", cpu: 32, ramGb: 128, gpu: 2, tee: true },
+  { name: "max-gpu", cpu: 64, ramGb: 256, gpu: 4, tee: false },
+  { name: "max-gpu-tee", cpu: 64, ramGb: 256, gpu: 4, tee: true }
+];
+var BridgeSession = class _BridgeSession {
+  constructor(client, cfg) {
+    this.client = client;
+    this.cfg = cfg;
+  }
+  /** Full chat completion (non-streaming). */
+  async chat(options) {
+    return this.client.chat({ ...options, bridge: this.cfg });
+  }
+  /** Stream OpenAI chat.completion.chunks. */
+  chatStream(options) {
+    return this.client.chatStream({ ...options, bridge: this.cfg });
+  }
+  /** One-shot: send a string, get the assistant text. */
+  async ask(message, extra) {
+    const completion = await this.chat({
+      messages: [{ role: "user", content: message }],
+      ...extra
+    });
+    return completion.choices[0]?.message?.content || "";
+  }
+  /** One-shot: send a string, stream text deltas. */
+  async *stream(message, extra) {
+    for await (const chunk of this.chatStream({
+      messages: [{ role: "user", content: message }],
+      ...extra
+    })) {
+      const content = chunk.choices?.[0]?.delta?.content;
+      if (content) yield content;
+    }
+  }
+  /** Turn-based: send full message history, get assistant text. */
+  async turn(messages, extra) {
+    const completion = await this.chat({ messages, ...extra });
+    return completion.choices[0]?.message?.content || "";
+  }
+  /** Clone with a new resume id — same harness, different logical conversation. */
+  withResume(resume) {
+    return new _BridgeSession(this.client, { ...this.cfg, resume });
+  }
+  /** Clone with a different model inside the same harness. */
+  withModel(model) {
+    return new _BridgeSession(this.client, { ...this.cfg, model });
+  }
+  /** The effective model id that will land on the router (`bridge/<harness>/<model>`). */
+  get model() {
+    return this.cfg.model ? `bridge/${this.cfg.harness}/${this.cfg.model}` : `bridge/${this.cfg.harness}`;
+  }
+  /** The resume id currently bound to this session, if any. */
+  get resume() {
+    return this.cfg.resume;
+  }
+};
+function selectTiers(all, n) {
+  if (n >= all.length) return [...all];
+  if (n <= 1) return [all[0]];
+  if (n === 2) return [all[0], all[all.length - 1]];
+  const result = [all[0]];
+  const step = (all.length - 1) / (n - 1);
+  for (let i = 1; i < n - 1; i++) {
+    result.push(all[Math.round(i * step)]);
+  }
+  result.push(all[all.length - 1]);
+  return result;
+}
+function formatPrice(pricePerToken) {
+  return `$${(pricePerToken * 1e3).toFixed(6)}/1K tokens`;
+}
 var TCloudError = class extends Error {
   constructor(status, message) {
     super(message);
@@ -842,6 +1506,8 @@ var TCloud = class _TCloud extends TCloudClient {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BridgeSession,
+  PrivateRouter,
   TCloud,
   TCloudClient,
   TCloudError,