@tangle-network/tcloud 0.4.2 → 0.4.4

package/dist/sandbox.d.cts

@@ -0,0 +1,90 @@
+import { AsyncAttestationPolicy, AttestationVerificationResult } from '@tangle-network/tcloud-attestation';
+
+type TCloudSandboxTee = 'any' | 'tdx' | 'nitro' | 'sev-snp' | 'phala-dstack' | 'gcp' | 'azure' | (string & {});
+interface TCloudSandboxCreateOptions {
+    name?: string;
+    image?: string;
+    environment?: string;
+    ssh?: boolean;
+    cpu?: number;
+    memoryMb?: number;
+    diskGb?: number;
+    gitUrl?: string;
+    gitRef?: string;
+    backend?: 'opencode' | 'claude-code' | 'codex' | 'amp' | (string & {});
+    tee?: TCloudSandboxTee;
+    sealed?: boolean;
+    attestationNonce?: string | 'auto';
+    verify?: boolean;
+    attestationPolicy?: Omit<AsyncAttestationPolicy, 'expectedNonce'>;
+}
+interface TCloudSandboxAttestationStatus {
+    requested: boolean;
+    evidenceReturned: boolean;
+    verified: boolean;
+    nonceBound: boolean;
+    errors: string[];
+}
+interface TCloudSandboxCreateResult {
+    sandbox: unknown;
+    attestation?: unknown;
+    verification?: AttestationVerificationResult;
+    attestationNonce?: string;
+    attestationStatus: TCloudSandboxAttestationStatus;
+}
+interface TCloudTeeAttestationChallenge {
+    nonce: string;
+    randomHex: string;
+    contextHashHex?: string;
+}
+interface TCloudTeeAttestationHeartbeatSample {
+    sequence: number;
+    nonce: string;
+    context: string;
+    attestation: unknown;
+    verification: AttestationVerificationResult;
+    checkedAt: Date;
+}
+interface TCloudTeeAttestationHeartbeatOptions {
+    tee?: TCloudSandboxTee;
+    intervalMs?: number;
+    signal?: AbortSignal;
+    immediate?: boolean;
+    continueOnFailure?: boolean;
+    sessionId?: string;
+    attestationPolicy?: Omit<AsyncAttestationPolicy, 'expectedNonce'>;
+    onSuccess?: (sample: TCloudTeeAttestationHeartbeatSample) => void;
+    onFailure?: (error: unknown) => void;
+}
+interface TCloudTeeAttestationHeartbeat {
+    stop(): void;
+    ping(context?: string): Promise<TCloudTeeAttestationHeartbeatSample>;
+    readonly stopped: boolean;
+    readonly failures: number;
+    readonly latest: TCloudTeeAttestationHeartbeatSample | undefined;
+    readonly done: Promise<void>;
+}
+interface TCloudSandboxConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+declare class TCloudSandbox {
+    private readonly client;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(config: TCloudSandboxConfig);
+    create(options: TCloudSandboxCreateOptions): Promise<TCloudSandboxCreateResult>;
+    private attachTeeApiFallbacks;
+    private fetchTeeAttestation;
+    private fetchTeePublicKey;
+    private fetchSandboxApi;
+}
+declare function createTeeAttestationChallenge(context?: string | Uint8Array): TCloudTeeAttestationChallenge;
+declare function startTeeAttestationHeartbeat(sandbox: unknown, options?: TCloudTeeAttestationHeartbeatOptions): TCloudTeeAttestationHeartbeat;
+declare function buildSandboxCreateOptions(options: TCloudSandboxCreateOptions): any;
+declare function shouldVerifyAttestation(options: Pick<TCloudSandboxCreateOptions, 'tee' | 'verify'>): boolean;
+declare function generateAttestationNonce(bytes?: number): string;
+
+export { TCloudSandbox, type TCloudSandboxAttestationStatus, type TCloudSandboxConfig, type TCloudSandboxCreateOptions, type TCloudSandboxCreateResult, type TCloudSandboxTee, type TCloudTeeAttestationChallenge, type TCloudTeeAttestationHeartbeat, type TCloudTeeAttestationHeartbeatOptions, type TCloudTeeAttestationHeartbeatSample, buildSandboxCreateOptions, createTeeAttestationChallenge, generateAttestationNonce, shouldVerifyAttestation, startTeeAttestationHeartbeat };

package/dist/sandbox.d.ts

@@ -0,0 +1,90 @@
+import { AsyncAttestationPolicy, AttestationVerificationResult } from '@tangle-network/tcloud-attestation';
+
+type TCloudSandboxTee = 'any' | 'tdx' | 'nitro' | 'sev-snp' | 'phala-dstack' | 'gcp' | 'azure' | (string & {});
+interface TCloudSandboxCreateOptions {
+    name?: string;
+    image?: string;
+    environment?: string;
+    ssh?: boolean;
+    cpu?: number;
+    memoryMb?: number;
+    diskGb?: number;
+    gitUrl?: string;
+    gitRef?: string;
+    backend?: 'opencode' | 'claude-code' | 'codex' | 'amp' | (string & {});
+    tee?: TCloudSandboxTee;
+    sealed?: boolean;
+    attestationNonce?: string | 'auto';
+    verify?: boolean;
+    attestationPolicy?: Omit<AsyncAttestationPolicy, 'expectedNonce'>;
+}
+interface TCloudSandboxAttestationStatus {
+    requested: boolean;
+    evidenceReturned: boolean;
+    verified: boolean;
+    nonceBound: boolean;
+    errors: string[];
+}
+interface TCloudSandboxCreateResult {
+    sandbox: unknown;
+    attestation?: unknown;
+    verification?: AttestationVerificationResult;
+    attestationNonce?: string;
+    attestationStatus: TCloudSandboxAttestationStatus;
+}
+interface TCloudTeeAttestationChallenge {
+    nonce: string;
+    randomHex: string;
+    contextHashHex?: string;
+}
+interface TCloudTeeAttestationHeartbeatSample {
+    sequence: number;
+    nonce: string;
+    context: string;
+    attestation: unknown;
+    verification: AttestationVerificationResult;
+    checkedAt: Date;
+}
+interface TCloudTeeAttestationHeartbeatOptions {
+    tee?: TCloudSandboxTee;
+    intervalMs?: number;
+    signal?: AbortSignal;
+    immediate?: boolean;
+    continueOnFailure?: boolean;
+    sessionId?: string;
+    attestationPolicy?: Omit<AsyncAttestationPolicy, 'expectedNonce'>;
+    onSuccess?: (sample: TCloudTeeAttestationHeartbeatSample) => void;
+    onFailure?: (error: unknown) => void;
+}
+interface TCloudTeeAttestationHeartbeat {
+    stop(): void;
+    ping(context?: string): Promise<TCloudTeeAttestationHeartbeatSample>;
+    readonly stopped: boolean;
+    readonly failures: number;
+    readonly latest: TCloudTeeAttestationHeartbeatSample | undefined;
+    readonly done: Promise<void>;
+}
+interface TCloudSandboxConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+declare class TCloudSandbox {
+    private readonly client;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(config: TCloudSandboxConfig);
+    create(options: TCloudSandboxCreateOptions): Promise<TCloudSandboxCreateResult>;
+    private attachTeeApiFallbacks;
+    private fetchTeeAttestation;
+    private fetchTeePublicKey;
+    private fetchSandboxApi;
+}
+declare function createTeeAttestationChallenge(context?: string | Uint8Array): TCloudTeeAttestationChallenge;
+declare function startTeeAttestationHeartbeat(sandbox: unknown, options?: TCloudTeeAttestationHeartbeatOptions): TCloudTeeAttestationHeartbeat;
+declare function buildSandboxCreateOptions(options: TCloudSandboxCreateOptions): any;
+declare function shouldVerifyAttestation(options: Pick<TCloudSandboxCreateOptions, 'tee' | 'verify'>): boolean;
+declare function generateAttestationNonce(bytes?: number): string;
+
+export { TCloudSandbox, type TCloudSandboxAttestationStatus, type TCloudSandboxConfig, type TCloudSandboxCreateOptions, type TCloudSandboxCreateResult, type TCloudSandboxTee, type TCloudTeeAttestationChallenge, type TCloudTeeAttestationHeartbeat, type TCloudTeeAttestationHeartbeatOptions, type TCloudTeeAttestationHeartbeatSample, buildSandboxCreateOptions, createTeeAttestationChallenge, generateAttestationNonce, shouldVerifyAttestation, startTeeAttestationHeartbeat };

package/dist/sandbox.js

@@ -0,0 +1,16 @@
+import {
+  TCloudSandbox,
+  buildSandboxCreateOptions,
+  createTeeAttestationChallenge,
+  generateAttestationNonce,
+  shouldVerifyAttestation,
+  startTeeAttestationHeartbeat
+} from "./chunk-DBIT227N.js";
+export {
+  TCloudSandbox,
+  buildSandboxCreateOptions,
+  createTeeAttestationChallenge,
+  generateAttestationNonce,
+  shouldVerifyAttestation,
+  startTeeAttestationHeartbeat
+};

package/dist/shielded.cjs

@@ -51,6 +51,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",
@@ -196,6 +198,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;
@@ -253,6 +260,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) {
@@ -350,6 +358,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(/\/$/, "");
@@ -665,10 +721,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;
@@ -1170,6 +1254,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 });
@@ -1239,6 +1325,7 @@ var TCloudError = class extends Error {
     this.status = status;
     this.name = "TCloudError";
   }
+  status;
 };
 
 // src/shielded.ts

package/dist/shielded.d.cts

@@ -1,5 +1,5 @@
 import { Hex } from 'viem';
-import { a as TCloudConfig, T as TCloudClient, H as SpendAuth } from './client-D7_hFedn.cjs';
+import { a as TCloudConfig, T as TCloudClient, N as SpendAuth } from './client-DkQugNHH.cjs';
 
 /**
  * tcloud/shielded — Ephemeral wallet generation, SpendAuth signing, private inference.

package/dist/shielded.d.ts

@@ -1,5 +1,5 @@
 import { Hex } from 'viem';
-import { a as TCloudConfig, T as TCloudClient, H as SpendAuth } from './client-D7_hFedn.js';
+import { a as TCloudConfig, T as TCloudClient, N as SpendAuth } from './client-DkQugNHH.js';
 
 /**
  * tcloud/shielded — Ephemeral wallet generation, SpendAuth signing, private inference.

package/dist/shielded.js

@@ -3,8 +3,8 @@ import {
   estimateCost,
   generateWallet,
   signSpendAuth
-} from "./chunk-A7AEPV2G.js";
-import "./chunk-B22AH4JH.js";
+} from "./chunk-4ZUVGKVH.js";
+import "./chunk-M5K3EFNP.js";
 export {
   createShieldedClient,
   estimateCost,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/tcloud",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "TypeScript SDK and CLI for Tangle AI Cloud — decentralized LLM inference",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -20,6 +20,26 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./attestation": {
+      "import": {
+        "types": "./dist/attestation.d.ts",
+        "default": "./dist/attestation.js"
+      },
+      "require": {
+        "types": "./dist/attestation.d.cts",
+        "default": "./dist/attestation.cjs"
+      }
+    },
+    "./sandbox": {
+      "import": {
+        "types": "./dist/sandbox.d.ts",
+        "default": "./dist/sandbox.js"
+      },
+      "require": {
+        "types": "./dist/sandbox.d.cts",
+        "default": "./dist/sandbox.cjs"
+      }
+    },
     "./shielded": {
       "import": {
         "types": "./dist/shielded.d.ts",
@@ -44,26 +64,28 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts src/cli.ts src/shielded.ts src/instance.ts --format esm,cjs --dts --clean --external socks-proxy-agent",
+    "build": "tsup src/index.ts src/cli.ts src/shielded.ts src/instance.ts src/attestation.ts src/sandbox.ts --format esm,cjs --dts --clean --external socks-proxy-agent",
     "docs": "typedoc src/index.ts --out docs --name tcloud --readme README.md",
     "test": "vitest run",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "dev": "tsx src/cli.ts",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@scure/bip32": "^2.0.1",
-    "@scure/bip39": "^2.0.1",
-    "@tangle-network/sandbox": "^0.0.3",
-    "commander": "^13.0.0",
-    "viem": "^2.0.0"
+    "@scure/bip32": "^2.2.0",
+    "@scure/bip39": "^2.2.0",
+    "@tangle-network/sandbox": "^0.1.2",
+    "@tangle-network/tcloud-attestation": "^0.1.0",
+    "commander": "^14.0.3",
+    "viem": "^2.48.4"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "tsup": "^8.0.0",
+    "tsup": "^8.5.1",
     "tsx": "^4.0.0",
-    "typedoc": "^0.28.18",
+    "typedoc": "^0.28.19",
     "typescript": "^5.0.0",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.5"
   },
   "files": [
     "dist",