@tangle-network/tcloud 0.4.6 → 0.4.8

package/README.md

@@ -94,7 +94,7 @@ for await (const chunk of client.askStream('write a haiku', 'kimi-code/kimi-for-
 }
 ```
 
-See [`examples/14-direct-cli-bridge.ts`](./examples/14-direct-cli-bridge.ts) for the full pattern. For session-resumable agentic dispatches (file edits, multi-turn coding), see [`examples/12-bridge-sessions.ts`](./examples/12-bridge-sessions.ts) which uses the router-mediated `tcloud.bridge({...})` API.
+See [`examples/14-direct-cli-bridge.ts`](./examples/14-direct-cli-bridge.ts) for the full pattern. Direct cli-bridge clients also support `client.bridge({ harness, model, resume })`; in direct mode the SDK sends `<harness>/<model>` and maps `resume` to cli-bridge's `session_id`.
 
 ### Model Selection
 
@@ -379,9 +379,10 @@ tcloud config --model gpt-4o-mini
 ```
 
 Environment variables:
-- `TCLOUD_API_KEY` — API key (primary)
-- `OPENAI_API_KEY` — Fallback API key (works because the API is OpenAI-compatible)
-- `TCLOUD_BASE_URL` — Override API base URL
+- `TANGLE_API_KEY` — API key (primary). One key for router + sandbox + all Tangle products.
+- `TCLOUD_API_KEY` — Deprecated alias, still honored for backwards compatibility.
+- `OPENAI_API_KEY` — Fallback API key (works because the API is OpenAI-compatible).
+- `TCLOUD_BASE_URL` — Override API base URL.
 
 ## OpenAI SDK Compatibility
 
@@ -439,7 +440,7 @@ See the [`examples/`](./examples/) directory — each is a self-contained script
 
 Run any example:
 ```bash
-TCLOUD_API_KEY=sk-tan-... npx tsx examples/01-quick-start.ts
+TANGLE_API_KEY=sk-tan-... npx tsx examples/01-quick-start.ts
 ```
 
 ## License

package/dist/{chunk-F6OVKJG3.js → chunk-27OTTDMZ.js}

@@ -1,10 +1,13 @@
+import {
+  TCloudSandbox
+} from "./chunk-DRCOPW7D.js";
 import {
   createShieldedClient,
   generateWallet
-} from "./chunk-4ZUVGKVH.js";
+} from "./chunk-YWN4JOCW.js";
 import {
   TCloudClient
-} from "./chunk-M5K3EFNP.js";
+} from "./chunk-CVWEKCQ3.js";
 
 // src/index.ts
 import {
@@ -54,7 +57,7 @@ var TCloud = class _TCloud extends TCloudClient {
    *
    * ```ts
    * const client = TCloud.rotating({
-   *   apiKey: process.env.TCLOUD_API_KEY,
+   *   apiKey: process.env.TANGLE_API_KEY,
    *   routing: { strategy: 'min-exposure' },
    * })
    * const stats = client.getRotationStats()
@@ -72,6 +75,23 @@ var TCloud = class _TCloud extends TCloudClient {
    * ```
    */
   static generateWallet = generateWallet;
+  /**
+   * Create a Sandbox SDK client using this TCloud client's API key by default.
+   *
+   * ```ts
+   * const tcloud = new TCloud({ apiKey })
+   * const sandbox = await tcloud.sandbox().create({ name: 'runner' })
+   * ```
+   */
+  sandbox(config = {}) {
+    const apiKey = config.apiKey ?? this.apiKey;
+    if (!apiKey) throw new Error("TCloud.sandbox() requires an apiKey");
+    return new TCloudSandbox({ ...config, apiKey });
+  }
+  /** Create a standalone Sandbox SDK client. */
+  static sandbox(config) {
+    return new TCloudSandbox(config);
+  }
 };
 
 export {

package/dist/{chunk-M5K3EFNP.js → chunk-CVWEKCQ3.js}

@@ -220,6 +220,7 @@ var PrivateRouter = class {
 
 // src/client.ts
 var ROTATING_MARKER = "__tcloudRotating";
+var DIRECT_CLI_BRIDGE_MARKER = "__tcloudDirectCliBridge";
 var DEFAULT_BASE_URL = "https://router.tangle.tools/v1";
 var SDK_VERSION = "0.4.0";
 async function proxiedFetch(privacy, url, init, streaming) {
@@ -269,6 +270,43 @@ var DEFAULT_RETRY = {
 };
 var DEFAULT_TIMEOUT_MS = 6e4;
 var DEFAULT_PLATFORM_URL = "https://id.tangle.tools";
+var PROTECTED_PROVIDER_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "model",
+  "messages",
+  "temperature",
+  "max_tokens",
+  "maxTokens",
+  "stream",
+  "stop",
+  "top_p",
+  "topP",
+  "frequency_penalty",
+  "frequencyPenalty",
+  "presence_penalty",
+  "presencePenalty",
+  "response_format",
+  "responseFormat",
+  "tools",
+  "tool_choice",
+  "toolChoice",
+  "gateway",
+  "bridge",
+  "agent_profile",
+  "agentProfile",
+  "session_id",
+  "sessionId"
+]);
+function sanitizeProviderOptions(providerOptions) {
+  if (!providerOptions) return {};
+  for (const key of Object.keys(providerOptions)) {
+    if (PROTECTED_PROVIDER_OPTION_KEYS.has(key)) {
+      throw new Error(
+        `providerOptions cannot override protected chat field "${key}"; use the typed ChatOptions field instead`
+      );
+    }
+  }
+  return providerOptions;
+}
 var TCloudClient = class _TCloudClient {
   baseURL;
   platformURL;
@@ -309,13 +347,21 @@ var TCloudClient = class _TCloudClient {
    * const reply = await client.ask('explain X', 'claude-code/sonnet')
    * ```
    *
-   * For session-resumable agentic dispatches (file edits, multi-turn
-   * coding), use the router-mediated `tcloud.bridge({...})` API instead
-   * (or POST to cli-bridge directly with `session_id` in the body).
+   * For session-resumable agentic dispatches, use `client.bridge(...)` on
+   * the returned direct client. `resume` is serialized to cli-bridge's
+   * `session_id` body field and the model wire format stays
+   * `<harness>/<model>` without the router-only `bridge/` prefix.
    */
   static fromCliBridge(opts) {
     const baseURL = opts.url.replace(/\/+$/, "") + "/v1";
-    return new _TCloudClient({ ...opts.config ?? {}, apiKey: opts.bearer, baseURL });
+    const client = new _TCloudClient({ ...opts.config ?? {}, apiKey: opts.bearer, baseURL });
+    Object.defineProperty(client, DIRECT_CLI_BRIDGE_MARKER, {
+      value: true,
+      enumerable: false,
+      configurable: false,
+      writable: false
+    });
+    return client;
   }
   /**
    * Build a client that rotates which operator serves each call. Mirrors
@@ -327,7 +373,7 @@ var TCloudClient = class _TCloudClient {
    *
    * ```ts
    * const tcloud = TCloudClient.rotating({
-   *   apiKey: process.env.TCLOUD_API_KEY,
+   *   apiKey: process.env.TANGLE_API_KEY,
    *   routing: { strategy: 'min-exposure' },
    * })
    * await tcloud.ask('hello')
@@ -368,7 +414,7 @@ var TCloudClient = class _TCloudClient {
   constructor(config = {}) {
     this.baseURL = (config.baseURL || DEFAULT_BASE_URL).replace(/\/$/, "");
     this.platformURL = (config.platformURL || DEFAULT_PLATFORM_URL).replace(/\/$/, "");
-    this.apiKey = config.apiKey || process.env.TCLOUD_API_KEY;
+    this.apiKey = config.apiKey || process.env.TANGLE_API_KEY || process.env.TCLOUD_API_KEY;
     this.model = config.model || "gpt-4o-mini";
     this.privacy = config.privacy;
     this.limits = config.limits;
@@ -577,8 +623,8 @@ var TCloudClient = class _TCloudClient {
         delete headers["Authorization"];
       }
     }
-    if (bridge) {
-      headers["X-Bridge-Unlock"] = bridge.unlock;
+    if (bridge && !this._isDirectCliBridge()) {
+      headers["X-Bridge-Unlock"] = bridge.unlock ?? "";
       if (bridge.resume) headers["X-Resume"] = bridge.resume;
       if (bridge.bridgeUrl) headers["X-Bridge-Url"] = bridge.bridgeUrl;
       if (bridge.bridgeBearer) headers["X-Bridge-Bearer"] = bridge.bridgeBearer;
@@ -591,13 +637,24 @@ var TCloudClient = class _TCloudClient {
    */
   _effectiveModel(options) {
     if (options.bridge) {
+      if (this._isDirectCliBridge()) {
+        return options.bridge.model ? `${options.bridge.harness}/${options.bridge.model}` : options.bridge.harness;
+      }
       return options.bridge.model ? `bridge/${options.bridge.harness}/${options.bridge.model}` : `bridge/${options.bridge.harness}`;
     }
     return options.model || this.model;
   }
   /** Build the chat completions request body */
   _chatBody(options, stream) {
+    const providerOptions = sanitizeProviderOptions(options.providerOptions);
+    const sandboxBody = {};
+    if (options.sandbox?.agentProfile) sandboxBody.agent_profile = options.sandbox.agentProfile;
+    if (options.sandbox?.sessionId) sandboxBody.session_id = options.sandbox.sessionId;
+    if (this._isDirectCliBridge() && options.bridge?.resume && !sandboxBody.session_id) {
+      sandboxBody.session_id = options.bridge.resume;
+    }
     return JSON.stringify({
+      ...providerOptions,
       model: this._effectiveModel(options),
       messages: options.messages,
       temperature: options.temperature,
@@ -611,7 +668,7 @@ var TCloudClient = class _TCloudClient {
       tools: options.tools,
       tool_choice: options.toolChoice,
       ...options.gateway ? { gateway: options.gateway } : {},
-      ...options.providerOptions
+      ...sandboxBody
     });
   }
   /** Chat completion (non-streaming) */
@@ -692,7 +749,13 @@ var TCloudClient = class _TCloudClient {
         "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);
+    if (!this._isDirectCliBridge() && cfg.unlock == null) {
+      throw new Error("Bridge unlock is required for router-mediated bridge sessions");
+    }
+    return new BridgeSession(this, cfg, this._isDirectCliBridge());
+  }
+  _isDirectCliBridge() {
+    return this[DIRECT_CLI_BRIDGE_MARKER] === true;
   }
   /**
    * Rotation stats — populated only on clients created via
@@ -858,6 +921,49 @@ var TCloudClient = class _TCloudClient {
       })
     });
   }
+  /**
+   * Edit / inpaint / variate an existing image with a text prompt.
+   * Sibling to `imageGenerate`; routes to `/v1/images/edits` via
+   * multipart/form-data per the OpenAI spec.
+   *
+   * Reference image attachments may be passed as `Blob`, `ArrayBuffer`,
+   * or `{data: base64, mediaType, filename?}`. Multi-image composition
+   * (e.g. gpt-image-2 with two reference frames + a prompt that fuses
+   * them) is supported by passing an array; for legacy models only the
+   * first image is honored upstream.
+   */
+  async imagesEdit(options) {
+    const formData = new FormData();
+    formData.append("prompt", options.prompt);
+    formData.append("model", options.model || "gpt-image-2");
+    if (options.n != null) formData.append("n", String(options.n));
+    if (options.size) formData.append("size", options.size);
+    if (options.quality) formData.append("quality", options.quality);
+    if (options.response_format) formData.append("response_format", options.response_format);
+    if (options.mask) formData.append("mask", toEditBlob(options.mask, "mask.png"), "mask.png");
+    const images = Array.isArray(options.image) ? options.image : [options.image];
+    if (images.length === 0) {
+      throw new TCloudError(400, "imagesEdit requires at least one image attachment");
+    }
+    images.forEach((img, idx) => {
+      const blob = toEditBlob(img, `image-${idx + 1}.png`);
+      formData.append("image[]", blob, blobFilename(img, `image-${idx + 1}.png`));
+    });
+    const headers = { ...this.headers };
+    delete headers["Content-Type"];
+    this.checkLimits();
+    const res = await proxiedFetch(this.privacy, `${this.baseURL}/images/edits`, {
+      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();
+  }
   /** Rerank documents by relevance to a query */
   async rerank(options) {
     return this._request(`${this.baseURL}/rerank`, {
@@ -949,7 +1055,7 @@ var TCloudClient = class _TCloudClient {
   }
   /** Get video generation status */
   async videoStatus(id) {
-    return this._fetch(`${this.baseURL}/video?id=${id}`);
+    return this._fetch(`${this.baseURL}/video/${encodeURIComponent(id)}`);
   }
   /** Generate an avatar video (lip-synced talking head from audio + face image).
    *  Returns 202 with a job_id for async polling via avatarJobStatus(). */
@@ -1209,12 +1315,14 @@ var ALL_TIERS = [
   { name: "max-gpu-tee", cpu: 64, ramGb: 256, gpu: 4, tee: true }
 ];
 var BridgeSession = class _BridgeSession {
-  constructor(client, cfg) {
+  constructor(client, cfg, direct = false) {
     this.client = client;
     this.cfg = cfg;
+    this.direct = direct;
   }
   client;
   cfg;
+  direct;
   /** Full chat completion (non-streaming). */
   async chat(options) {
     return this.client.chat({ ...options, bridge: this.cfg });
@@ -1248,15 +1356,16 @@ var BridgeSession = class _BridgeSession {
   }
   /** Clone with a new resume id — same harness, different logical conversation. */
   withResume(resume) {
-    return new _BridgeSession(this.client, { ...this.cfg, resume });
+    return new _BridgeSession(this.client, { ...this.cfg, resume }, this.direct);
   }
   /** Clone with a different model inside the same harness. */
   withModel(model) {
-    return new _BridgeSession(this.client, { ...this.cfg, model });
+    return new _BridgeSession(this.client, { ...this.cfg, model }, this.direct);
   }
   /** The effective model id that will land on the router (`bridge/<harness>/<model>`). */
   get model() {
-    return this.cfg.model ? `bridge/${this.cfg.harness}/${this.cfg.model}` : `bridge/${this.cfg.harness}`;
+    const prefix = this.direct ? "" : "bridge/";
+    return this.cfg.model ? `${prefix}${this.cfg.harness}/${this.cfg.model}` : `${prefix}${this.cfg.harness}`;
   }
   /** The resume id currently bound to this session, if any. */
   get resume() {
@@ -1278,6 +1387,32 @@ function selectTiers(all, n) {
 function formatPrice(pricePerToken) {
   return `$${(pricePerToken * 1e3).toFixed(6)}/1K tokens`;
 }
+function toEditBlob(input, defaultFilename) {
+  if (input instanceof Blob) return input;
+  if (input instanceof ArrayBuffer) return new Blob([input], { type: "image/png" });
+  const binary = base64ToUint8Array(input.data);
+  const copy = new Uint8Array(binary.byteLength);
+  copy.set(binary);
+  return new Blob([copy.buffer], { type: input.mediaType || "image/png" });
+  void defaultFilename;
+}
+function blobFilename(input, fallback) {
+  if (typeof input === "object" && !(input instanceof Blob) && !(input instanceof ArrayBuffer)) {
+    if (input.filename) return input.filename;
+  }
+  return fallback;
+}
+function base64ToUint8Array(b64) {
+  const m = /^data:[^;,]*(?:;[^,]*)?,(.+)$/.exec(b64);
+  const raw = m ? m[1] : b64;
+  const bin = typeof atob === "function" ? atob(raw) : (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    globalThis.Buffer.from(raw, "base64").toString("binary")
+  );
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
 var TCloudError = class extends Error {
   constructor(status, message) {
     super(message);

package/dist/{chunk-DBIT227N.js → chunk-DRCOPW7D.js}

@@ -250,7 +250,14 @@ function buildSandboxCreateOptions(options) {
       memoryMB: options.memoryMb,
       diskGB: options.diskGb
     } : void 0,
-    backend: options.backend ? { type: options.backend } : void 0,
+    // backend: merge `backend` (type string) with `agentProfile` (carried
+    // as `backend.profile` on the underlying SDK). Either may be set
+    // independently; setting both produces `{ type, profile }`. Setting
+    // neither leaves `backend` undefined so the SDK applies its default.
+    backend: options.backend || options.agentProfile ? {
+      ...options.backend ? { type: options.backend } : {},
+      ...options.agentProfile ? { profile: options.agentProfile } : {}
+    } : void 0,
     confidential: options.tee ? {
       tee: options.tee,
       sealed: options.sealed || void 0,

package/dist/{chunk-4ZUVGKVH.js → chunk-YWN4JOCW.js}

@@ -1,6 +1,6 @@
 import {
   TCloudClient
-} from "./chunk-M5K3EFNP.js";
+} from "./chunk-CVWEKCQ3.js";
 
 // src/shielded.ts
 import { privateKeyToAccount } from "viem/accounts";