@tangle-network/tcloud 0.1.3 → 0.2.0

package/dist/instance.cjs

@@ -0,0 +1,1235 @@
+"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 __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/instance.ts
+var instance_exports = {};
+__export(instance_exports, {
+  Instance: () => Instance,
+  appendLogLine: () => appendLogLine,
+  writeTempHarnessConfig: () => writeTempHarnessConfig
+});
+module.exports = __toCommonJS(instance_exports);
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_os = require("os");
+var import_node_crypto = require("crypto");
+
+// 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) {
+  if (!privacy || privacy.mode === "direct") {
+    return fetch(url, init);
+  }
+  if (privacy.mode === "relayer") {
+    if (!privacy.relayerUrl) {
+      throw new Error('relayerUrl is required when privacy mode is "relayer"');
+    }
+    const proxyPath = streaming ? "/relay/proxy-stream" : "/relay/proxy";
+    const hdrs = {};
+    if (init.headers) {
+      const entries = init.headers instanceof Headers ? Array.from(init.headers.entries()) : Object.entries(init.headers);
+      for (const [k, v] of entries) hdrs[k] = v;
+    }
+    return fetch(`${privacy.relayerUrl}${proxyPath}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        target: url,
+        body: typeof init.body === "string" ? JSON.parse(init.body) : init.body,
+        headers: hdrs
+      })
+    });
+  }
+  if (privacy.mode === "socks5") {
+    if (!privacy.socksProxy) {
+      throw new Error('socksProxy is required when privacy mode is "socks5"');
+    }
+    const { SocksProxyAgent } = await import("socks-proxy-agent");
+    const agent = new SocksProxyAgent(privacy.socksProxy);
+    return fetch(url, {
+      ...init,
+      // @ts-expect-error agent is supported by Node's undici but not in the standard RequestInit type
+      agent
+    });
+  }
+  return fetch(url, init);
+}
+var DEFAULT_RETRY = {
+  maxRetries: 3,
+  initialBackoffMs: 500,
+  maxBackoffMs: 3e4,
+  multiplier: 2,
+  retryableStatuses: [429, 500, 502, 503, 504]
+};
+var DEFAULT_TIMEOUT_MS = 6e4;
+var TCloudClient = class _TCloudClient {
+  baseURL;
+  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;
+    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.2.0"
+    };
+    if (this.apiKey) {
+      this.headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    if (config.routing?.mode) {
+      this.headers["X-Tangle-Routing"] = config.routing.mode;
+    }
+    if (config.routing?.prefer) {
+      this.headers["X-Tangle-Operator"] = config.routing.prefer;
+    }
+    if (config.routing?.blueprintId) {
+      this.headers["X-Tangle-Blueprint"] = config.routing.blueprintId;
+    }
+    if (config.routing?.serviceId) {
+      this.headers["X-Tangle-Service"] = config.routing.serviceId;
+    }
+    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) {
+    this.spendAuthFn = fn;
+  }
+  /** Current metering stats */
+  get usage() {
+    return {
+      totalSpent: this._totalSpent,
+      requestCount: this._requestCount,
+      limits: this.limits ? { ...this.limits } : void 0
+    };
+  }
+  /** Check spending limits before a request. Throws TCloudError if blocked. */
+  checkLimits() {
+    if (!this.limits) return;
+    if (this.limits.maxRequests && this._requestCount >= this.limits.maxRequests) {
+      this.limits.onLimitReached?.({ type: "requests", current: this._requestCount, limit: this.limits.maxRequests });
+      throw new TCloudError(429, `Request limit reached (${this._requestCount}/${this.limits.maxRequests})`);
+    }
+    if (this.limits.maxTotalSpend && this._totalSpent >= this.limits.maxTotalSpend) {
+      this.limits.onLimitReached?.({ type: "total", current: this._totalSpent, limit: this.limits.maxTotalSpend });
+      throw new TCloudError(429, `Spending limit reached ($${this._totalSpent.toFixed(6)}/$${this.limits.maxTotalSpend})`);
+    }
+    if (this.limits.maxRequests && this.limits.onLimitWarning) {
+      const pct = this._requestCount / this.limits.maxRequests;
+      if (pct >= 0.8) this.limits.onLimitWarning({ type: "requests", current: this._requestCount, limit: this.limits.maxRequests });
+    }
+    if (this.limits.maxTotalSpend && this.limits.onLimitWarning) {
+      const pct = this._totalSpent / this.limits.maxTotalSpend;
+      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++;
+    if (completion.usage) {
+      let estimatedCost;
+      const inputPrice = res ? parseFloat(res.headers.get("x-tangle-price-input") || "0") : 0;
+      const outputPrice = res ? parseFloat(res.headers.get("x-tangle-price-output") || "0") : 0;
+      if (inputPrice > 0 || outputPrice > 0) {
+        estimatedCost = (completion.usage.prompt_tokens || 0) * inputPrice + (completion.usage.completion_tokens || 0) * outputPrice;
+      } else {
+        const tokens = completion.usage.total_tokens || 0;
+        estimatedCost = tokens * 1e-6;
+      }
+      this._totalSpent += estimatedCost;
+      if (this.limits?.maxCostPerRequest && estimatedCost > this.limits.maxCostPerRequest) {
+        this.limits.onLimitReached?.({ type: "cost", current: estimatedCost, limit: this.limits.maxCostPerRequest });
+      }
+    }
+  }
+  /**
+   * 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.
+   * Shared between chat() and chatStream() to eliminate duplication.
+   */
+  async _prepareChatRequest(model) {
+    const headers = { ...this.headers };
+    if (this.spendAuthFn) {
+      const auth = await this.spendAuthFn();
+      headers["X-Payment-Signature"] = JSON.stringify(auth);
+      delete headers["Authorization"];
+    }
+    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"];
+      }
+    }
+    return { headers, baseURL };
+  }
+  /** Build the chat completions request body */
+  _chatBody(options, stream) {
+    return JSON.stringify({
+      model: options.model || this.model,
+      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.providerOptions
+    });
+  }
+  /** Chat completion (non-streaming) */
+  async chat(options) {
+    this.checkLimits();
+    const { headers, baseURL } = await this._prepareChatRequest(options.model || this.model);
+    const res = await this._doFetch(`${baseURL}/chat/completions`, {
+      method: "POST",
+      headers,
+      body: this._chatBody(options, false)
+    }, false);
+    const completion = await res.json();
+    this.trackCost(completion, res);
+    return completion;
+  }
+  /** Chat completion (streaming) — returns an async iterator of chunks */
+  async *chatStream(options) {
+    this.checkLimits();
+    this._requestCount++;
+    const { headers, baseURL } = await this._prepareChatRequest(options.model || this.model);
+    const res = await this._doFetch(`${baseURL}/chat/completions`, {
+      method: "POST",
+      headers,
+      body: this._chatBody(options, true)
+    }, true);
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    while (true) {
+      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]") {
+          return;
+        }
+        try {
+          yield JSON.parse(data);
+        } catch {
+        }
+      }
+    }
+  }
+  /** Convenience: send a single message and get the text response */
+  async ask(message, modelOrOptions) {
+    const options = typeof modelOrOptions === "string" ? { model: modelOrOptions } : modelOrOptions;
+    const completion = await this.chat({
+      messages: [{ role: "user", content: message }],
+      ...options
+    });
+    return completion.choices[0]?.message?.content || "";
+  }
+  /** Convenience: send a single message and get the full completion (with usage) */
+  async askFull(message, modelOrOptions) {
+    const options = typeof modelOrOptions === "string" ? { model: modelOrOptions } : modelOrOptions;
+    return this.chat({
+      messages: [{ role: "user", content: message }],
+      ...options
+    });
+  }
+  /** Convenience: stream a single message and yield text chunks */
+  async *askStream(message, modelOrOptions) {
+    const options = typeof modelOrOptions === "string" ? { model: modelOrOptions } : modelOrOptions;
+    for await (const chunk of this.chatStream({
+      messages: [{ role: "user", content: message }],
+      ...options
+    })) {
+      const content = chunk.choices[0]?.delta?.content;
+      if (content) yield content;
+    }
+  }
+  /** List available models */
+  async models() {
+    const data = await this._fetch(`${this.baseURL}/models`);
+    return data.data || [];
+  }
+  /** List active operators */
+  async operators() {
+    const apiRoot = this.baseURL.replace(/\/v1$/, "");
+    return this._fetch(`${apiRoot}/api/operators`);
+  }
+  /** Get credit balance */
+  async credits() {
+    const apiRoot = this.baseURL.replace(/\/v1$/, "");
+    return this._fetch(`${apiRoot}/api/billing`);
+  }
+  /** Add credits */
+  async addCredits(amount) {
+    const apiRoot = this.baseURL.replace(/\/v1$/, "");
+    return this._fetch(`${apiRoot}/api/billing`, {
+      method: "POST",
+      body: JSON.stringify({ amount })
+    });
+  }
+  /** Create a new API key */
+  async createKey(name) {
+    const apiRoot = this.baseURL.replace(/\/v1$/, "");
+    return this._fetch(`${apiRoot}/api/keys`, {
+      method: "POST",
+      body: JSON.stringify({ name })
+    });
+  }
+  /** List API keys */
+  async keys() {
+    const apiRoot = this.baseURL.replace(/\/v1$/, "");
+    return this._fetch(`${apiRoot}/api/keys`);
+  }
+  /** Revoke an API key */
+  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) {
+      const err = await res.json().catch(() => ({ error: res.statusText }));
+      throw new TCloudError(res.status, err.error?.message || err.error || err.message || res.statusText);
+    }
+  }
+  /** Generate embeddings */
+  async embeddings(options) {
+    return this._request(`${this.baseURL}/embeddings`, {
+      method: "POST",
+      body: JSON.stringify({
+        model: options.model || "text-embedding-3-small",
+        input: options.input
+      })
+    });
+  }
+  /** Generate images */
+  async imageGenerate(options) {
+    return this._request(`${this.baseURL}/images/generations`, {
+      method: "POST",
+      body: JSON.stringify({
+        model: options.model || "dall-e-3",
+        prompt: options.prompt,
+        n: options.n,
+        size: options.size,
+        quality: options.quality,
+        response_format: options.response_format
+      })
+    });
+  }
+  /** Rerank documents by relevance to a query */
+  async rerank(options) {
+    return this._request(`${this.baseURL}/rerank`, {
+      method: "POST",
+      body: JSON.stringify({
+        model: options.model || "rerank-english-v3.0",
+        query: options.query,
+        documents: options.documents,
+        top_n: options.top_n
+      })
+    });
+  }
+  /** Text-to-speech */
+  async speech(options) {
+    const res = await this._requestRaw(`${this.baseURL}/audio/speech`, {
+      method: "POST",
+      body: JSON.stringify({
+        model: options.model || "tts-1",
+        input: options.input,
+        voice: options.voice || "alloy"
+      })
+    });
+    return res.arrayBuffer();
+  }
+  /** Legacy completions endpoint */
+  async completions(options) {
+    return this._request(`${this.baseURL}/completions`, {
+      method: "POST",
+      body: JSON.stringify({
+        model: options.model || this.model,
+        prompt: options.prompt,
+        temperature: options.temperature,
+        max_tokens: options.maxTokens,
+        stop: options.stop,
+        top_p: options.topP
+      })
+    });
+  }
+  /** Audio transcription (speech-to-text) */
+  async transcribe(file, options) {
+    const formData = new FormData();
+    formData.append("file", file, "audio.webm");
+    formData.append("model", options?.model || "whisper-1");
+    if (options?.language) formData.append("language", options.language);
+    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,
+      body: formData
+    }, 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);
+    }
+    this._requestCount++;
+    return res.json();
+  }
+  /** Create a fine-tuning job */
+  async fineTuneCreate(options) {
+    return this._request(`${this.baseURL}/fine_tuning/jobs`, {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /** List fine-tuning jobs */
+  async fineTuneList() {
+    return this._fetch(`${this.baseURL}/fine_tuning/jobs`);
+  }
+  /** Submit a batch of chat requests */
+  async batch(requests) {
+    return this._request(`${this.baseURL}/batch`, {
+      method: "POST",
+      body: JSON.stringify({ requests })
+    });
+  }
+  /** Get batch job status */
+  async batchStatus(jobId) {
+    return this._fetch(`${this.baseURL}/batch?id=${jobId}`);
+  }
+  /** Generate video */
+  async videoGenerate(options) {
+    return this._request(`${this.baseURL}/video/generate`, {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /** Get video generation status */
+  async videoStatus(id) {
+    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) {
+    const all = await this.models();
+    const q = query.toLowerCase();
+    return all.filter(
+      (m) => m.id.toLowerCase().includes(q) || m.name.toLowerCase().includes(q) || m._provider && m._provider.toLowerCase().includes(q)
+    );
+  }
+  /** Estimate cost for a request (without sending it) */
+  async estimateCost(options) {
+    const models = await this.models();
+    const model = models.find((m) => m.id === (options.model || this.model));
+    if (!model) return { inputCost: 0, outputCost: 0, total: 0 };
+    const inputCost = options.inputTokens * parseFloat(model.pricing.prompt);
+    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
+      };
+    });
+  }
+};
+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 }
+];
+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);
+    this.status = status;
+    this.name = "TCloudError";
+  }
+};
+
+// src/instance.ts
+var MAX_LOG_LINES = 1e4;
+function appendLogLine(buffer, line, maxLines = MAX_LOG_LINES) {
+  buffer.push(line);
+  if (buffer.length > maxLines) {
+    buffer.shift();
+  }
+}
+var Instance = class _Instance {
+  child;
+  _config;
+  _stopped = false;
+  logBuffer;
+  maxLogLines = MAX_LOG_LINES;
+  constructor(child, config, logBuffer) {
+    this.child = child;
+    this._config = config;
+    this.logBuffer = logBuffer;
+  }
+  /**
+   * Start a new harness instance. Resolves once `cargo tangle harness up`
+   * prints its "Harness up" marker, indicating all blueprints are healthy.
+   *
+   * Throws on timeout, process exit before ready, or missing `cargo-tangle`.
+   */
+  static async start(options = {}) {
+    const cargoBinary = options.cargoBinary ?? "cargo-tangle";
+    const timeoutMs = options.timeoutMs ?? 3e5;
+    const routerUrl = options.routerUrl ?? "http://localhost:3000";
+    const args = ["tangle", "harness", "up"];
+    if (options.config) {
+      args.push("--config", options.config);
+    }
+    if (options.only && options.only.length > 0) {
+      args.push("--only", options.only.join(","));
+    }
+    if (options.includeAnvilLogs) {
+      args.push("--include-anvil-logs");
+    }
+    const child = (0, import_node_child_process.spawn)(cargoBinary, args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const logBuffer = [];
+    const pushLog = (line) => {
+      appendLogLine(logBuffer, line, MAX_LOG_LINES);
+      if (!options.quiet) {
+        process.stdout.write(line + "\n");
+      }
+    };
+    let stdoutTail = "";
+    let stderrTail = "";
+    child.stdout?.on("data", (chunk) => {
+      stdoutTail += chunk.toString();
+      const lines = stdoutTail.split("\n");
+      stdoutTail = lines.pop() ?? "";
+      for (const line of lines) pushLog(line);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderrTail += chunk.toString();
+      const lines = stderrTail.split("\n");
+      stderrTail = lines.pop() ?? "";
+      for (const line of lines) pushLog(line);
+    });
+    const blueprintNames = [];
+    try {
+      await new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        let pollInterval;
+        const cleanup = () => {
+          if (settled) return;
+          settled = true;
+          if (pollInterval !== void 0) clearInterval(pollInterval);
+          if (timer !== void 0) clearTimeout(timer);
+          child.removeListener("exit", onExit);
+          child.removeListener("error", onError);
+        };
+        const onExit = (code) => {
+          if (settled) return;
+          cleanup();
+          reject(
+            new Error(
+              `cargo tangle harness exited with code ${code} before becoming ready. Last 20 lines:
+${logBuffer.slice(-20).join("\n")}`
+            )
+          );
+        };
+        const onError = (err) => {
+          if (settled) return;
+          cleanup();
+          reject(new Error(`Failed to spawn ${cargoBinary}: ${err.message}`));
+        };
+        timer = setTimeout(() => {
+          if (settled) return;
+          cleanup();
+          reject(
+            new Error(
+              `Timed out after ${timeoutMs}ms waiting for harness to start. Last 20 lines:
+${logBuffer.slice(-20).join("\n")}`
+            )
+          );
+        }, timeoutMs);
+        child.once("exit", onExit);
+        child.once("error", onError);
+        pollInterval = setInterval(() => {
+          for (const line of logBuffer) {
+            const match = line.match(/Harness up\.\s+(\d+)\s+blueprint/i);
+            if (match) {
+              if (settled) return;
+              cleanup();
+              resolve();
+              return;
+            }
+            const bpMatch = line.match(/Starting blueprint-manager for '([^']+)'/);
+            if (bpMatch) {
+              blueprintNames.push(bpMatch[1]);
+            }
+          }
+        }, 100);
+      });
+    } catch (err) {
+      if (!child.killed) {
+        child.kill("SIGTERM");
+      }
+      throw err;
+    }
+    return new _Instance(
+      child,
+      { routerUrl, blueprints: blueprintNames },
+      logBuffer
+    );
+  }
+  /** URL of the router serving this instance */
+  get routerUrl() {
+    return this._config.routerUrl;
+  }
+  /** Names of blueprints that were started */
+  get blueprints() {
+    return [...this._config.blueprints];
+  }
+  /**
+   * Create a pre-configured {@link TCloudClient} pointed at this instance's router.
+   * Merges any passed config with the instance's routerUrl (instance wins).
+   */
+  client(config = {}) {
+    return new TCloudClient({
+      ...config,
+      baseURL: this._config.routerUrl
+    });
+  }
+  /** Return the last N log lines from the harness */
+  logs(lines = 100) {
+    return this.logBuffer.slice(-lines);
+  }
+  /** Whether the harness process is still running */
+  get isRunning() {
+    return !this._stopped && !this.child.killed && this.child.exitCode === null;
+  }
+  /**
+   * Stop the harness. Sends SIGTERM, waits up to 10s for clean shutdown,
+   * then SIGKILL.
+   */
+  async stop(timeoutMs = 1e4) {
+    if (this._stopped) return;
+    this._stopped = true;
+    if (this.child.exitCode !== null) {
+      return;
+    }
+    this.child.kill("SIGTERM");
+    await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        if (this.child.exitCode === null) {
+          this.child.kill("SIGKILL");
+        }
+        resolve();
+      }, timeoutMs);
+      this.child.once("exit", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+};
+function writeTempHarnessConfig(blueprints) {
+  const dir = (0, import_node_path.join)(
+    (0, import_node_os.tmpdir)(),
+    `tangle-harness-${process.pid}-${Date.now()}-${(0, import_node_crypto.randomUUID)()}`
+  );
+  if (!(0, import_node_fs.existsSync)(dir)) {
+    (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  }
+  const file = (0, import_node_path.join)(dir, "harness.toml");
+  const lines = [];
+  lines.push("[chain]");
+  lines.push("anvil = true");
+  lines.push("");
+  for (const bp of blueprints) {
+    lines.push("[[blueprint]]");
+    lines.push(`name = "${bp.name}"`);
+    lines.push(`path = "${bp.path}"`);
+    if (bp.port !== void 0) {
+      lines.push(`port = ${bp.port}`);
+    }
+    if (bp.env) {
+      for (const [k, v] of Object.entries(bp.env)) {
+        lines.push(`env.${k} = "${v.replace(/"/g, '\\"')}"`);
+      }
+    }
+    lines.push("");
+  }
+  (0, import_node_fs.writeFileSync)(file, lines.join("\n"));
+  return file;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Instance,
+  appendLogLine,
+  writeTempHarnessConfig
+});