@tangle-network/tcloud 0.4.2 → 0.4.3

package/dist/cli.cjs

@@ -38,6 +38,8 @@ var PrivateRouter = class {
   usage = /* @__PURE__ */ new Map();
   currentIndex = 0;
   totalRequests = 0;
+  /** Slug of the most-recently-selected operator. Populated on each selectOperator() hit. */
+  _lastSelectedSlug = null;
   constructor(config = {}) {
     this.config = {
       strategy: config.strategy || "round-robin",
@@ -183,6 +185,11 @@ var PrivateRouter = class {
       requestCount: (existing?.requestCount || 0) + 1,
       lastUsedAt: Date.now()
     });
+    this._lastSelectedSlug = op.slug;
+  }
+  /** Slug of the most-recently-selected operator (null before the first call). */
+  get lastSelectedSlug() {
+    return this._lastSelectedSlug;
   }
   getLastUsedOperator() {
     let latest = null;
@@ -240,6 +247,7 @@ var PrivateRouter = class {
 };
 
 // src/client.ts
+var ROTATING_MARKER = "__tcloudRotating";
 var DEFAULT_BASE_URL = "https://router.tangle.tools/v1";
 var SDK_VERSION = "0.4.0";
 async function proxiedFetch(privacy, url, init, streaming) {
@@ -337,6 +345,54 @@ var TCloudClient = class _TCloudClient {
     const baseURL = opts.url.replace(/\/+$/, "") + "/v1";
     return new _TCloudClient({ ...opts.config ?? {}, apiKey: opts.bearer, baseURL });
   }
+  /**
+   * Build a client that rotates which operator serves each call. Mirrors
+   * {@link TCloudClient.shielded} in shape: returns a standard `TCloudClient`
+   * that behaves identically for the OpenAI-compatible surface but
+   * dispatches each chat/completions/embeddings request through a
+   * {@link PrivateRouter} — different operator per call per the chosen
+   * strategy.
+   *
+   * ```ts
+   * const tcloud = TCloudClient.rotating({
+   *   apiKey: process.env.TCLOUD_API_KEY,
+   *   routing: { strategy: 'min-exposure' },
+   * })
+   * await tcloud.ask('hello')
+   * tcloud.getRotationStats() // { callsByOperator: { ... }, currentOperator: '…' }
+   * ```
+   *
+   * Rotation is meaningful only for stateless calls. Sandbox-harness
+   * sessions bind to a single operator for the lifetime of the session;
+   * `rotating()` clients refuse to dispatch them — see {@link bridge}.
+   */
+  static rotating(config = {}) {
+    const routing = config.routing ?? {};
+    const strategy = routing.strategy ?? "min-exposure";
+    const { routing: _omit, ...base } = config;
+    const client = new _TCloudClient(base);
+    const router = new PrivateRouter({
+      strategy,
+      minOperators: routing.minOperators ?? 1,
+      maxRequestsPerOperator: routing.maxRequestsPerOperator,
+      excludeOperators: routing.excludeOperators,
+      preferRegions: routing.preferRegions
+    });
+    if (routing.pool && routing.pool.length > 0) {
+      router.setOperators(routing.pool);
+      client._cachedOperators = routing.pool;
+      client._operatorsCachedAt = Date.now();
+    }
+    ;
+    client.privateRouter = router;
+    Object.defineProperty(client, ROTATING_MARKER, {
+      value: true,
+      enumerable: false,
+      configurable: false,
+      writable: false
+    });
+    return client;
+  }
   constructor(config = {}) {
     this.baseURL = (config.baseURL || DEFAULT_BASE_URL).replace(/\/$/, "");
     this.platformURL = (config.platformURL || DEFAULT_PLATFORM_URL).replace(/\/$/, "");
@@ -652,10 +708,38 @@ var TCloudClient = class _TCloudClient {
    *
    * Sessions persist across process restarts — use the same `resume` id
    * to land on the same CLI conversation (context intact, no replay tax).
+   *
+   * Guard: clients built via {@link TCloudClient.rotating} cannot dispatch
+   * sandbox-harness sessions (rotation rotates per call; a sandbox session
+   * binds to one operator). Attempting `bridge({ harness: 'sandbox' })` on
+   * a rotating client throws.
    */
   bridge(cfg) {
+    if (cfg.harness === "sandbox" && this[ROTATING_MARKER] === true) {
+      throw new Error(
+        "TCloudClient.rotating() cannot dispatch sandbox-harness sessions.\nSandbox sessions bind to a single operator; rotation is meaningful only for\nstateless calls. Use TCloudClient.shielded() + AgentProfile.confidential.tee\nfor privacy-preserving sandbox execution instead."
+      );
+    }
     return new BridgeSession(this, cfg);
   }
+  /**
+   * Rotation stats — populated only on clients created via
+   * {@link TCloudClient.rotating}. Non-rotating clients return an empty
+   * counter and `currentOperator: null`.
+   */
+  getRotationStats() {
+    if (!this.privateRouter) {
+      return { callsByOperator: {}, currentOperator: null };
+    }
+    const callsByOperator = {};
+    for (const row of this.privateRouter.getStats().operatorBreakdown) {
+      callsByOperator[row.slug] = row.requests;
+    }
+    return {
+      callsByOperator,
+      currentOperator: this.privateRouter.lastSelectedSlug
+    };
+  }
   /** Convenience: send a single message and get the text response */
   async ask(message, modelOrOptions) {
     const options = typeof modelOrOptions === "string" ? { model: modelOrOptions } : modelOrOptions;
@@ -1157,6 +1241,8 @@ var BridgeSession = class _BridgeSession {
     this.client = client;
     this.cfg = cfg;
   }
+  client;
+  cfg;
   /** Full chat completion (non-streaming). */
   async chat(options) {
     return this.client.chat({ ...options, bridge: this.cfg });
@@ -1226,6 +1312,7 @@ var TCloudError = class extends Error {
     this.status = status;
     this.name = "TCloudError";
   }
+  status;
 };
 
 // src/shielded.ts
@@ -1481,7 +1568,208 @@ async function replenishDirect(fundingKey, tokenAddress, amount, commitment, spe
   }
 }
 
+// src/sandbox.ts
+var import_sandbox = require("@tangle-network/sandbox");
+var import_node_crypto = require("crypto");
+var import_tcloud_attestation = require("@tangle-network/tcloud-attestation");
+var DEFAULT_SANDBOX_URL = "https://sandbox.tangle.tools";
+var TCloudSandbox = class {
+  client;
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_SANDBOX_URL).replace(/\/+$/, "");
+    this.timeoutMs = config.timeoutMs;
+    this.client = new import_sandbox.Sandbox({
+      apiKey: this.apiKey,
+      baseUrl: this.baseUrl,
+      timeoutMs: config.timeoutMs
+    });
+  }
+  async create(options) {
+    const effectiveVerify = shouldVerifyAttestation(options);
+    const attestationPolicy = buildAttestationPolicy(options);
+    const createOptions = buildSandboxCreateOptions({
+      ...options,
+      verify: effectiveVerify
+    });
+    const sandbox2 = await this.client.create(createOptions);
+    this.attachTeeApiFallbacks(sandbox2);
+    let attestation = attestationFromMetadata(sandbox2.metadata);
+    if ((effectiveVerify || createOptions.confidential?.attestationNonce) && !attestation) {
+      const getTeeAttestation = sandbox2.getTeeAttestation;
+      if (typeof getTeeAttestation !== "function") {
+        throw new Error("Installed @tangle-network/sandbox does not expose TEE attestation fetching");
+      }
+      attestation = (await getTeeAttestation.call(
+        sandbox2,
+        createOptions.confidential?.attestationNonce ? { attestationNonce: createOptions.confidential.attestationNonce } : void 0
+      )).attestation;
+    }
+    if (effectiveVerify && !attestation) {
+      throw new Error("TEE attestation verification requested but no evidence was returned");
+    }
+    const verification = effectiveVerify ? await (0, import_tcloud_attestation.verifyAttestationAsync)(attestation, {
+      ...attestationPolicy,
+      expectedNonce: createOptions.confidential?.attestationNonce
+    }) : void 0;
+    if (verification && !verification.valid) {
+      throw new Error(`TEE attestation verification failed: ${verification.errors.join("; ")}`);
+    }
+    return {
+      sandbox: sandbox2,
+      attestation,
+      verification,
+      attestationNonce: createOptions.confidential?.attestationNonce,
+      attestationStatus: {
+        requested: Boolean(options.tee),
+        evidenceReturned: Boolean(attestation),
+        verified: Boolean(verification?.valid),
+        nonceBound: Boolean(createOptions.confidential?.attestationNonce && verification?.valid),
+        errors: verification?.errors ?? []
+      }
+    };
+  }
+  attachTeeApiFallbacks(sandbox2) {
+    if (typeof sandbox2 !== "object" || sandbox2 === null) return;
+    const target = sandbox2;
+    if (typeof target.id !== "string" || target.id.length === 0) return;
+    if (typeof target.getTeeAttestation !== "function") {
+      target.getTeeAttestation = (options) => this.fetchTeeAttestation(target.id, options?.attestationNonce);
+    }
+    if (typeof target.getTeePublicKey !== "function") {
+      target.getTeePublicKey = () => this.fetchTeePublicKey(target.id);
+    }
+  }
+  async fetchTeeAttestation(sandboxId, attestationNonce) {
+    const response = await this.fetchSandboxApi(
+      `/v1/sandboxes/${encodeURIComponent(sandboxId)}/tee/attestation`,
+      {
+        method: attestationNonce ? "POST" : "GET",
+        body: attestationNonce ? JSON.stringify({ attestation_nonce: attestationNonce }) : void 0
+      }
+    );
+    const data = await response.json();
+    if (attestationNonce && !data.attestationNonce) {
+      data.attestationNonce = attestationNonce;
+    }
+    return data;
+  }
+  async fetchTeePublicKey(sandboxId) {
+    const response = await this.fetchSandboxApi(
+      `/v1/sandboxes/${encodeURIComponent(sandboxId)}/tee/public-key`,
+      { method: "GET" }
+    );
+    return response.json();
+  }
+  async fetchSandboxApi(path2, options) {
+    const headers = new Headers(options.headers);
+    headers.set("Authorization", `Bearer ${this.apiKey}`);
+    if (options.body && !headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json");
+    }
+    const response = await fetch(`${this.baseUrl}${path2}`, {
+      ...options,
+      headers,
+      signal: options.signal ?? (this.timeoutMs ? AbortSignal.timeout(this.timeoutMs) : void 0)
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Sandbox API ${path2} failed with HTTP ${response.status}: ${body}`);
+    }
+    return response;
+  }
+};
+function buildSandboxCreateOptions(options) {
+  if (!options.tee && (options.sealed || options.attestationNonce || options.verify)) {
+    throw new Error("TEE options require a tee value");
+  }
+  const shouldGenerateNonce = options.attestationNonce === "auto" || shouldVerifyAttestation(options) && !options.attestationNonce;
+  const attestationNonce = shouldGenerateNonce ? generateAttestationNonce() : options.attestationNonce;
+  if (attestationNonce) {
+    validateAttestationNonce(attestationNonce);
+  }
+  return {
+    name: options.name,
+    environment: options.environment ?? options.image,
+    sshEnabled: options.ssh || void 0,
+    git: options.gitUrl ? {
+      url: options.gitUrl,
+      ref: options.gitRef
+    } : void 0,
+    resources: options.cpu || options.memoryMb || options.diskGb ? {
+      cpuCores: options.cpu,
+      memoryMB: options.memoryMb,
+      diskGB: options.diskGb
+    } : void 0,
+    backend: options.backend ? { type: options.backend } : void 0,
+    confidential: options.tee ? {
+      tee: options.tee,
+      sealed: options.sealed || void 0,
+      attestationNonce,
+      attestationRefresh: Boolean(attestationNonce)
+    } : void 0
+  };
+}
+function shouldVerifyAttestation(options) {
+  return Boolean(options.tee || options.verify);
+}
+function buildAttestationPolicy(options) {
+  if (!options.tee || options.tee === "any") return options.attestationPolicy ?? {};
+  const requestedTypes = acceptedAttestationTypesForTee(options.tee);
+  const acceptedTeeTypes = options.attestationPolicy?.acceptedTeeTypes;
+  if (acceptedTeeTypes?.length && !acceptedTeeTypes.some((type) => requestedTypes.includes(type))) {
+    throw new Error(
+      `TEE attestation policy does not accept requested TEE type ${options.tee}`
+    );
+  }
+  return {
+    ...options.attestationPolicy,
+    acceptedTeeTypes: acceptedTeeTypes?.length ? acceptedTeeTypes.filter((type) => requestedTypes.includes(type)) : requestedTypes
+  };
+}
+function acceptedAttestationTypesForTee(tee) {
+  switch (tee) {
+    case "phala-dstack":
+      return ["tdx", "phala-dstack"];
+    case "gcp":
+      return ["tdx", "sev-snp", "gcp"];
+    case "azure":
+      return ["sev-snp", "azure"];
+    default:
+      return [(0, import_tcloud_attestation.normalizeTeeType)(tee)];
+  }
+}
+function validateAttestationNonce(value) {
+  const normalized = value.trim().toLowerCase().replace(/^0x/, "");
+  if (!/^[0-9a-f]+$/.test(normalized)) {
+    throw new Error("attestation nonce must be hex");
+  }
+  if (normalized.length % 2 !== 0) {
+    throw new Error("attestation nonce must have even hex length");
+  }
+  const bytes = normalized.length / 2;
+  if (bytes < 32 || bytes > 64) {
+    throw new Error(`attestation nonce must be 32-64 bytes, got ${bytes}`);
+  }
+}
+function generateAttestationNonce(bytes = 32) {
+  return Array.from((0, import_node_crypto.randomBytes)(bytes)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function attestationFromMetadata(metadata) {
+  const raw = metadata?.teeAttestationJson;
+  if (typeof raw !== "string" || raw.trim() === "") return void 0;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+}
+
 // src/index.ts
+var import_tcloud_attestation2 = require("@tangle-network/tcloud-attestation");
 var TCloud = class _TCloud extends TCloudClient {
   constructor(config) {
     super(config);
@@ -1510,6 +1798,21 @@ var TCloud = class _TCloud extends TCloudClient {
   static shielded(config) {
     return createShieldedClient(config);
   }
+  /**
+   * Create a client that rotates operators per call.
+   * See {@link TCloudClient.rotating} for semantics.
+   *
+   * ```ts
+   * const client = TCloud.rotating({
+   *   apiKey: process.env.TCLOUD_API_KEY,
+   *   routing: { strategy: 'min-exposure' },
+   * })
+   * const stats = client.getRotationStats()
+   * ```
+   */
+  static rotating(config) {
+    return TCloudClient.rotating(config);
+  }
   /**
    * Generate a new ephemeral wallet (without creating a client).
    *
@@ -1562,11 +1865,31 @@ function getClient(opts) {
   }
   return new TCloud({ baseURL: `${config.apiUrl}/v1`, apiKey: config.apiKey, model: config.defaultModel });
 }
+function requireApiKey(config) {
+  if (!config.apiKey) {
+    console.error("No API key. Run: tcloud login");
+    process.exit(1);
+  }
+  return config.apiKey;
+}
+function optionalNumber(value) {
+  if (value == null) return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Expected a number, got ${String(value)}`);
+  }
+  return parsed;
+}
+function teeType(value) {
+  if (!value) return void 0;
+  return value.toLowerCase();
+}
 var program = new import_commander.Command();
 program.name("tcloud").description("Tangle AI Cloud CLI").version("0.1.0");
-program.command("config").description("View or update configuration").option("--api-url <url>", "API base URL").option("--api-key <key>", "API key").option("--model <model>", "Default model").option("--chain <id>", "Chain ID").action((opts) => {
+program.command("config").description("View or update configuration").option("--api-url <url>", "API base URL").option("--sandbox-url <url>", "Sandbox API base URL").option("--api-key <key>", "API key").option("--model <model>", "Default model").option("--chain <id>", "Chain ID").action((opts) => {
   const c = loadConfig();
   if (opts.apiUrl) c.apiUrl = opts.apiUrl;
+  if (opts.sandboxUrl) c.sandboxUrl = opts.sandboxUrl;
   if (opts.apiKey) c.apiKey = opts.apiKey;
   if (opts.model) c.defaultModel = opts.model;
   if (opts.chain) c.chainId = parseInt(opts.chain);
@@ -1835,6 +2158,52 @@ program.command("operators").description("List active operators").action(async (
     console.error("Error:", e.message);
   }
 });
+var sandbox = program.command("sandbox").description("Sandbox workflows");
+sandbox.command("create").description("Create a sandbox").option("--name <name>", "Sandbox name").option("--image <image>", "Sandbox image or environment").option("--environment <environment>", "Sandbox environment").option("--ssh", "Enable SSH").option("--cpu <cores>", "CPU cores").option("--memory <mb>", "Memory in MB").option("--disk <gb>", "Disk in GB").option("--git-url <url>", "Git repository URL").option("--git-ref <ref>", "Git ref").option("--backend <type>", "Agent backend").option("--tee <type>", "Require a TEE backend: any, tdx, nitro, sev-snp, phala-dstack, gcp, azure").option("--sealed", "Require sealed secret support").option("--attestation-nonce <hex|auto>", "Attach a caller challenge nonce").option("--verify", "Verify returned attestation evidence (default when --tee is set)").option("--allow-unverified-hardware", "Allow structural attestation checks before vendor-root verification is available").option("--sandbox-url <url>", "Sandbox API base URL").option("--json", "Print JSON").action(async (opts) => {
+  try {
+    const config = loadConfig();
+    const client = new TCloudSandbox({
+      apiKey: requireApiKey(config),
+      baseUrl: opts.sandboxUrl ?? config.sandboxUrl
+    });
+    const result = await client.create({
+      name: opts.name,
+      image: opts.image,
+      environment: opts.environment,
+      ssh: Boolean(opts.ssh),
+      cpu: optionalNumber(opts.cpu),
+      memoryMb: optionalNumber(opts.memory),
+      diskGb: optionalNumber(opts.disk),
+      gitUrl: opts.gitUrl,
+      gitRef: opts.gitRef,
+      backend: opts.backend,
+      tee: teeType(opts.tee),
+      sealed: Boolean(opts.sealed),
+      attestationNonce: opts.attestationNonce,
+      verify: Boolean(opts.verify || opts.tee),
+      attestationPolicy: {
+        allowUnverifiedHardware: Boolean(opts.allowUnverifiedHardware)
+      }
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const box = result.sandbox;
+    console.log(`Sandbox created: ${box.id ?? "unknown"}`);
+    if (box.status) console.log(`Status: ${box.status}`);
+    if (opts.tee) {
+      const status = result.attestationStatus;
+      console.log(`TEE: ${opts.tee}`);
+      console.log(`Attestation: ${status.verified ? "verified" : status.evidenceReturned ? "unverified" : "not returned"}`);
+      console.log(`Nonce bound: ${status.nonceBound ? "yes" : "no"}`);
+      if (result.attestationNonce) console.log(`Attestation nonce: ${result.attestationNonce}`);
+    }
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
 var credits = program.command("credits").description("Credit management");
 credits.command("balance").description("Check balance").action(async () => {
   const client = getClient();

package/dist/cli.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import {
   TCloud
-} from "./chunk-577KIKFA.js";
+} from "./chunk-MB4VK4MM.js";
+import {
+  TCloudSandbox
+} from "./chunk-DBIT227N.js";
 import {
   generateWallet
-} from "./chunk-A7AEPV2G.js";
-import "./chunk-B22AH4JH.js";
+} from "./chunk-4ZUVGKVH.js";
+import "./chunk-M5K3EFNP.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -49,11 +52,31 @@ function getClient(opts) {
   }
   return new TCloud({ baseURL: `${config.apiUrl}/v1`, apiKey: config.apiKey, model: config.defaultModel });
 }
+function requireApiKey(config) {
+  if (!config.apiKey) {
+    console.error("No API key. Run: tcloud login");
+    process.exit(1);
+  }
+  return config.apiKey;
+}
+function optionalNumber(value) {
+  if (value == null) return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Expected a number, got ${String(value)}`);
+  }
+  return parsed;
+}
+function teeType(value) {
+  if (!value) return void 0;
+  return value.toLowerCase();
+}
 var program = new Command();
 program.name("tcloud").description("Tangle AI Cloud CLI").version("0.1.0");
-program.command("config").description("View or update configuration").option("--api-url <url>", "API base URL").option("--api-key <key>", "API key").option("--model <model>", "Default model").option("--chain <id>", "Chain ID").action((opts) => {
+program.command("config").description("View or update configuration").option("--api-url <url>", "API base URL").option("--sandbox-url <url>", "Sandbox API base URL").option("--api-key <key>", "API key").option("--model <model>", "Default model").option("--chain <id>", "Chain ID").action((opts) => {
   const c = loadConfig();
   if (opts.apiUrl) c.apiUrl = opts.apiUrl;
+  if (opts.sandboxUrl) c.sandboxUrl = opts.sandboxUrl;
   if (opts.apiKey) c.apiKey = opts.apiKey;
   if (opts.model) c.defaultModel = opts.model;
   if (opts.chain) c.chainId = parseInt(opts.chain);
@@ -322,6 +345,52 @@ program.command("operators").description("List active operators").action(async (
     console.error("Error:", e.message);
   }
 });
+var sandbox = program.command("sandbox").description("Sandbox workflows");
+sandbox.command("create").description("Create a sandbox").option("--name <name>", "Sandbox name").option("--image <image>", "Sandbox image or environment").option("--environment <environment>", "Sandbox environment").option("--ssh", "Enable SSH").option("--cpu <cores>", "CPU cores").option("--memory <mb>", "Memory in MB").option("--disk <gb>", "Disk in GB").option("--git-url <url>", "Git repository URL").option("--git-ref <ref>", "Git ref").option("--backend <type>", "Agent backend").option("--tee <type>", "Require a TEE backend: any, tdx, nitro, sev-snp, phala-dstack, gcp, azure").option("--sealed", "Require sealed secret support").option("--attestation-nonce <hex|auto>", "Attach a caller challenge nonce").option("--verify", "Verify returned attestation evidence (default when --tee is set)").option("--allow-unverified-hardware", "Allow structural attestation checks before vendor-root verification is available").option("--sandbox-url <url>", "Sandbox API base URL").option("--json", "Print JSON").action(async (opts) => {
+  try {
+    const config = loadConfig();
+    const client = new TCloudSandbox({
+      apiKey: requireApiKey(config),
+      baseUrl: opts.sandboxUrl ?? config.sandboxUrl
+    });
+    const result = await client.create({
+      name: opts.name,
+      image: opts.image,
+      environment: opts.environment,
+      ssh: Boolean(opts.ssh),
+      cpu: optionalNumber(opts.cpu),
+      memoryMb: optionalNumber(opts.memory),
+      diskGb: optionalNumber(opts.disk),
+      gitUrl: opts.gitUrl,
+      gitRef: opts.gitRef,
+      backend: opts.backend,
+      tee: teeType(opts.tee),
+      sealed: Boolean(opts.sealed),
+      attestationNonce: opts.attestationNonce,
+      verify: Boolean(opts.verify || opts.tee),
+      attestationPolicy: {
+        allowUnverifiedHardware: Boolean(opts.allowUnverifiedHardware)
+      }
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const box = result.sandbox;
+    console.log(`Sandbox created: ${box.id ?? "unknown"}`);
+    if (box.status) console.log(`Status: ${box.status}`);
+    if (opts.tee) {
+      const status = result.attestationStatus;
+      console.log(`TEE: ${opts.tee}`);
+      console.log(`Attestation: ${status.verified ? "verified" : status.evidenceReturned ? "unverified" : "not returned"}`);
+      console.log(`Nonce bound: ${status.nonceBound ? "yes" : "no"}`);
+      if (result.attestationNonce) console.log(`Attestation nonce: ${result.attestationNonce}`);
+    }
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+});
 var credits = program.command("credits").description("Credit management");
 credits.command("balance").description("Check balance").action(async () => {
   const client = getClient();

package/dist/{client-D7_hFedn.d.ts → client-DkQugNHH.d.cts}

@@ -590,6 +590,8 @@ declare class PrivateRouter {
     private usage;
     private currentIndex;
     private totalRequests;
+    /** Slug of the most-recently-selected operator. Populated on each selectOperator() hit. */
+    private _lastSelectedSlug;
     constructor(config?: Partial<PrivateRouterConfig>);
     /** Set the available operator pool */
     setOperators(operators: OperatorInfo[]): void;
@@ -614,6 +616,8 @@ declare class PrivateRouter {
     private minExposure;
     private latencyAware;
     private recordUsage;
+    /** Slug of the most-recently-selected operator (null before the first call). */
+    get lastSelectedSlug(): string | null;
     private getLastUsedOperator;
     private peekNextOperator;
 }
@@ -623,6 +627,35 @@ declare class PrivateRouter {
  * Shared between CLI and SDK.
  */
 
+/** Rotation knobs for {@link TCloudClient.rotating}. */
+interface RotatingRoutingConfig {
+    /** Router strategy. Defaults to `'min-exposure'`. */
+    strategy?: Extract<RoutingStrategy, 'min-exposure' | 'round-robin' | 'random'>;
+    /**
+     * Pre-seed the operator pool. When omitted the client fetches
+     * `/api/operators` on the first call (TTL-cached).
+     */
+    pool?: OperatorInfo[];
+    /** Minimum distinct operators required before routing proceeds. */
+    minOperators?: number;
+    /** Max requests per operator before forced rotation. */
+    maxRequestsPerOperator?: number;
+    /** Exclude specific operator slugs. */
+    excludeOperators?: string[];
+    /** Prefer specific regions (others kept as fallback). */
+    preferRegions?: string[];
+}
+/** Configuration accepted by {@link TCloudClient.rotating}. */
+type RotatingClientConfig = Omit<TCloudConfig, 'routing'> & {
+    routing?: RotatingRoutingConfig;
+};
+/** Rotation stats surfaced by {@link TCloudClient.getRotationStats}. */
+interface RotationStats {
+    /** Per-operator call counter. */
+    callsByOperator: Record<string, number>;
+    /** Slug of the most-recently-selected operator, if any. */
+    currentOperator: string | null;
+}
 declare class TCloudClient {
     readonly baseURL: string;
     readonly platformURL: string;
@@ -675,6 +708,28 @@ declare class TCloudClient {
         /** Optional config passthrough (timeout, retry, etc). */
         config?: Omit<TCloudConfig, 'apiKey' | 'baseURL'>;
     }): TCloudClient;
+    /**
+     * Build a client that rotates which operator serves each call. Mirrors
+     * {@link TCloudClient.shielded} in shape: returns a standard `TCloudClient`
+     * that behaves identically for the OpenAI-compatible surface but
+     * dispatches each chat/completions/embeddings request through a
+     * {@link PrivateRouter} — different operator per call per the chosen
+     * strategy.
+     *
+     * ```ts
+     * const tcloud = TCloudClient.rotating({
+     *   apiKey: process.env.TCLOUD_API_KEY,
+     *   routing: { strategy: 'min-exposure' },
+     * })
+     * await tcloud.ask('hello')
+     * tcloud.getRotationStats() // { callsByOperator: { ... }, currentOperator: '…' }
+     * ```
+     *
+     * Rotation is meaningful only for stateless calls. Sandbox-harness
+     * sessions bind to a single operator for the lifetime of the session;
+     * `rotating()` clients refuse to dispatch them — see {@link bridge}.
+     */
+    static rotating(config?: RotatingClientConfig): TCloudClient;
     constructor(config?: TCloudConfig);
     /** Set the SpendAuth signer for private mode */
     setSpendAuthSigner(fn: () => Promise<SpendAuth>): void;
@@ -754,8 +809,19 @@ declare class TCloudClient {
      *
      * Sessions persist across process restarts — use the same `resume` id
      * to land on the same CLI conversation (context intact, no replay tax).
+     *
+     * Guard: clients built via {@link TCloudClient.rotating} cannot dispatch
+     * sandbox-harness sessions (rotation rotates per call; a sandbox session
+     * binds to one operator). Attempting `bridge({ harness: 'sandbox' })` on
+     * a rotating client throws.
      */
     bridge(cfg: BridgeOptions): BridgeSession;
+    /**
+     * Rotation stats — populated only on clients created via
+     * {@link TCloudClient.rotating}. Non-rotating clients return an empty
+     * counter and `currentOperator: null`.
+     */
+    getRotationStats(): RotationStats;
     /** Convenience: send a single message and get the text response */
     ask(message: string, modelOrOptions?: string | Partial<ChatOptions>): Promise<string>;
     /** Convenience: send a single message and get the full completion (with usage) */
@@ -1149,4 +1215,4 @@ declare class TCloudError extends Error {
     constructor(status: number, message: string);
 }
 
-export { type ApiKeyInfo as A, type BatchJobResponse as B, type ChatCompletion as C, type RoutingStrategy as D, type EmbeddingOptions as E, type FineTuningJob as F, type GatewayOptions as G, type SpendAuth as H, type ImageGenerateOptions as I, type JobEvent as J, type SpendingLimits as K, TCloudError as L, type Model as M, type TierConfig as N, type Operator as O, type PricingTier as P, type TranscriptionResponse as Q, type RerankOptions as R, type ShieldedConfig as S, TCloudClient as T, type UpdateKeyOptions as U, type VideoGenerateOptions as V, type VideoResponse as W, type WatchJobOptions as X, type TCloudConfig as a, type AvatarGenerateRequest as b, type AvatarGenerateResponse as c, type AvatarJobStatus as d, type AvatarResult as e, type BatchRequest as f, type BridgeOptions as g, BridgeSession as h, type ChatCompletionChunk as i, type ChatMessage as j, type ChatOptions as k, type CompletionOptions as l, type CompletionResponse as m, type CreateKeyOptions as n, type CreatedKey as o, type CreditBalance as p, type EmbeddingResponse as q, type FineTuningJobOptions as r, type ImageResponse as s, type OperatorInfo as t, type PrivacyConfig as u, PrivateRouter as v, type PrivateRouterConfig as w, type RerankResponse as x, type RetryConfig as y, type RoutingConfig as z };
+export { type ApiKeyInfo as A, type BatchJobResponse as B, type ChatCompletion as C, type RotatingRoutingConfig as D, type EmbeddingOptions as E, type FineTuningJob as F, type GatewayOptions as G, type RotationStats as H, type ImageGenerateOptions as I, type JobEvent as J, type RoutingConfig as K, type RoutingStrategy as L, type Model as M, type SpendAuth as N, type Operator as O, type PricingTier as P, type SpendingLimits as Q, type RotatingClientConfig as R, type ShieldedConfig as S, TCloudClient as T, TCloudError as U, type TierConfig as V, type TranscriptionResponse as W, type UpdateKeyOptions as X, type VideoGenerateOptions as Y, type VideoResponse as Z, type WatchJobOptions as _, type TCloudConfig as a, type AvatarGenerateRequest as b, type AvatarGenerateResponse as c, type AvatarJobStatus as d, type AvatarResult as e, type BatchRequest as f, type BridgeOptions as g, BridgeSession as h, type ChatCompletionChunk as i, type ChatMessage as j, type ChatOptions as k, type CompletionOptions as l, type CompletionResponse as m, type CreateKeyOptions as n, type CreatedKey as o, type CreditBalance as p, type EmbeddingResponse as q, type FineTuningJobOptions as r, type ImageResponse as s, type OperatorInfo as t, type PrivacyConfig as u, PrivateRouter as v, type PrivateRouterConfig as w, type RerankOptions as x, type RerankResponse as y, type RetryConfig as z };