@tangle-network/tcloud 0.4.6 → 0.4.8

package/dist/{client-DkQugNHH.d.cts → client-CF-tpVsi.d.cts}

@@ -1,4 +1,7 @@
+import { AgentProfile } from '@tangle-network/sandbox';
+
 /** Core types for the tcloud SDK */
+
 interface TCloudConfig {
     /** API base URL (default: https://router.tangle.tools/v1) */
     baseURL?: string;
@@ -94,6 +97,39 @@ interface ImageGenerateOptions {
     quality?: string;
     response_format?: 'url' | 'b64_json';
 }
+/**
+ * OpenAI-compatible /v1/images/edits request. Accepts one or more
+ * reference images + a prompt describing how to transform them.
+ *
+ * For gpt-image-2, the supplied images are passed as `image[]` (the
+ * model supports multi-image composition); for dall-e-2 only a single
+ * image is honored. The optional `mask` is the OpenAI inpainting mask
+ * (PNG with alpha) used to constrain where edits are applied.
+ *
+ * Carrying both shapes here lets callers point at the same `imagesEdit`
+ * method regardless of upstream model; cli-bridge / tangle-router
+ * decide what to forward.
+ */
+interface ImageEditOptions {
+    model?: string;
+    prompt: string;
+    /** One or more reference images. Pass as Blob (browser/Node 22+),
+     *  ArrayBuffer (will be wrapped in a Blob), or `{data, mediaType}`
+     *  for base64 + explicit mime. The first form is preferred. */
+    image: ImageEditAttachment | ImageEditAttachment[];
+    /** Optional inpainting mask — PNG with transparent pixels marking
+     *  the editable region (OpenAI dall-e-2 / gpt-image-2 inpaint mode). */
+    mask?: ImageEditAttachment;
+    n?: number;
+    size?: string;
+    quality?: string;
+    response_format?: 'url' | 'b64_json';
+}
+type ImageEditAttachment = Blob | ArrayBuffer | {
+    data: string /** base64 */;
+    mediaType: string;
+    filename?: string;
+};
 interface ImageResponse {
     created: number;
     data: {
@@ -189,9 +225,18 @@ interface BatchJobResponse {
 }
 interface VideoGenerateOptions {
     model?: string;
+    provider?: string | Record<string, unknown>;
     prompt: string;
     duration?: number;
     resolution?: string;
+    aspect_ratio?: string;
+    size?: string;
+    image_url?: string;
+    frame_images?: Array<Record<string, unknown>>;
+    input_references?: Array<Record<string, unknown>>;
+    generate_audio?: boolean;
+    seed?: number;
+    callback_url?: string;
 }
 interface VideoResponse {
     id: string;
@@ -338,8 +383,8 @@ interface BridgeOptions {
     harness: 'claude-code' | 'claudish' | 'codex' | 'opencode' | 'kimi-code' | 'sandbox' | 'openai' | 'anthropic' | 'moonshot' | 'zai';
     /** Model id inside the harness (e.g. `sonnet`, `kimi-for-coding`, `gpt-5-codex`). Omit for harness default. */
     model?: string;
-    /** Router-issued unlock token. Required unless operator has disabled the gate. */
-    unlock: string;
+    /** Router-issued unlock token. Required for router-mediated bridge calls; unused by direct cli-bridge clients. */
+    unlock?: string;
     /** Stable caller-owned id for session resume. Map one id per logical conversation. */
     resume?: string;
     /** BYOB: point at your own cli-bridge instance. Router must have BYOB enabled. */
@@ -347,6 +392,12 @@ interface BridgeOptions {
     /** BYOB: bearer your cli-bridge expects. */
     bridgeBearer?: string;
 }
+interface SandboxChatOptions {
+    /** Inline sandbox AgentProfile. Serialized as cli-bridge/sandbox-api `agent_profile`. */
+    agentProfile?: AgentProfile;
+    /** Direct sandbox or cli-bridge session id. Serialized as `session_id`. */
+    sessionId?: string;
+}
 interface ChatOptions {
     /** Model to use */
     model?: string;
@@ -386,10 +437,15 @@ interface ChatOptions {
     gateway?: GatewayOptions;
     /**
      * Provider-specific parameters passed through to the upstream API.
-     * These are spread into the request body alongside standard fields.
+     * Protected OpenAI/Tangle fields cannot be overridden from this escape hatch.
      * Example: `{ thinking: { type: 'enabled', budget_tokens: 8000 } }`
      */
     providerOptions?: Record<string, unknown>;
+    /**
+     * Typed sandbox/cli-bridge extensions. Use this instead of smuggling
+     * `agent_profile` or `session_id` through providerOptions.
+     */
+    sandbox?: SandboxChatOptions;
     /**
      * Route this call through the Tangle Router's cli-bridge short-circuit.
      * See {@link BridgeOptions}. When set, `model` is rewritten to
@@ -696,9 +752,10 @@ declare 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: {
         /** cli-bridge base URL — `http://127.0.0.1:3344` for default local; can be any reachable URL. */
@@ -718,7 +775,7 @@ declare 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')
@@ -816,6 +873,7 @@ declare class TCloudClient {
      * a rotating client throws.
      */
     bridge(cfg: BridgeOptions): BridgeSession;
+    private _isDirectCliBridge;
     /**
      * Rotation stats — populated only on clients created via
      * {@link TCloudClient.rotating}. Non-rotating clients return an empty
@@ -897,6 +955,18 @@ declare class TCloudClient {
     embeddings(options: EmbeddingOptions): Promise<EmbeddingResponse>;
     /** Generate images */
     imageGenerate(options: ImageGenerateOptions): Promise<ImageResponse>;
+    /**
+     * 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.
+     */
+    imagesEdit(options: ImageEditOptions): Promise<ImageResponse>;
     /** Rerank documents by relevance to a query */
     rerank(options: RerankOptions): Promise<RerankResponse>;
     /** Text-to-speech */
@@ -1167,7 +1237,8 @@ declare class TCloudClient {
 declare class BridgeSession {
     private readonly client;
     private readonly cfg;
-    constructor(client: TCloudClient, cfg: BridgeOptions);
+    private readonly direct;
+    constructor(client: TCloudClient, cfg: BridgeOptions, direct?: boolean);
     /** Full chat completion (non-streaming). */
     chat(options: Omit<ChatOptions, 'bridge'>): Promise<ChatCompletion>;
     /** Stream OpenAI chat.completion.chunks. */
@@ -1215,4 +1286,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 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 };
+export { type VideoGenerateOptions as $, type ApiKeyInfo as A, type BatchJobResponse as B, type ChatCompletion as C, type RerankResponse as D, type EmbeddingOptions as E, type FineTuningJob as F, type GatewayOptions as G, type RetryConfig as H, type ImageEditAttachment as I, type JobEvent as J, type RotatingRoutingConfig as K, type RotationStats as L, type Model as M, type RoutingConfig as N, type Operator as O, type PricingTier as P, type RoutingStrategy as Q, type RotatingClientConfig as R, type SandboxChatOptions as S, TCloudClient as T, type ShieldedConfig as U, type SpendAuth as V, type SpendingLimits as W, TCloudError as X, type TierConfig as Y, type TranscriptionResponse as Z, type UpdateKeyOptions as _, type TCloudConfig as a, type VideoResponse as a0, type WatchJobOptions as a1, 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 ImageEditOptions as s, type ImageGenerateOptions as t, type ImageResponse as u, type OperatorInfo as v, type PrivacyConfig as w, PrivateRouter as x, type PrivateRouterConfig as y, type RerankOptions as z };

package/dist/{client-DkQugNHH.d.ts → client-CF-tpVsi.d.ts}

@@ -1,4 +1,7 @@
+import { AgentProfile } from '@tangle-network/sandbox';
+
 /** Core types for the tcloud SDK */
+
 interface TCloudConfig {
     /** API base URL (default: https://router.tangle.tools/v1) */
     baseURL?: string;
@@ -94,6 +97,39 @@ interface ImageGenerateOptions {
     quality?: string;
     response_format?: 'url' | 'b64_json';
 }
+/**
+ * OpenAI-compatible /v1/images/edits request. Accepts one or more
+ * reference images + a prompt describing how to transform them.
+ *
+ * For gpt-image-2, the supplied images are passed as `image[]` (the
+ * model supports multi-image composition); for dall-e-2 only a single
+ * image is honored. The optional `mask` is the OpenAI inpainting mask
+ * (PNG with alpha) used to constrain where edits are applied.
+ *
+ * Carrying both shapes here lets callers point at the same `imagesEdit`
+ * method regardless of upstream model; cli-bridge / tangle-router
+ * decide what to forward.
+ */
+interface ImageEditOptions {
+    model?: string;
+    prompt: string;
+    /** One or more reference images. Pass as Blob (browser/Node 22+),
+     *  ArrayBuffer (will be wrapped in a Blob), or `{data, mediaType}`
+     *  for base64 + explicit mime. The first form is preferred. */
+    image: ImageEditAttachment | ImageEditAttachment[];
+    /** Optional inpainting mask — PNG with transparent pixels marking
+     *  the editable region (OpenAI dall-e-2 / gpt-image-2 inpaint mode). */
+    mask?: ImageEditAttachment;
+    n?: number;
+    size?: string;
+    quality?: string;
+    response_format?: 'url' | 'b64_json';
+}
+type ImageEditAttachment = Blob | ArrayBuffer | {
+    data: string /** base64 */;
+    mediaType: string;
+    filename?: string;
+};
 interface ImageResponse {
     created: number;
     data: {
@@ -189,9 +225,18 @@ interface BatchJobResponse {
 }
 interface VideoGenerateOptions {
     model?: string;
+    provider?: string | Record<string, unknown>;
     prompt: string;
     duration?: number;
     resolution?: string;
+    aspect_ratio?: string;
+    size?: string;
+    image_url?: string;
+    frame_images?: Array<Record<string, unknown>>;
+    input_references?: Array<Record<string, unknown>>;
+    generate_audio?: boolean;
+    seed?: number;
+    callback_url?: string;
 }
 interface VideoResponse {
     id: string;
@@ -338,8 +383,8 @@ interface BridgeOptions {
     harness: 'claude-code' | 'claudish' | 'codex' | 'opencode' | 'kimi-code' | 'sandbox' | 'openai' | 'anthropic' | 'moonshot' | 'zai';
     /** Model id inside the harness (e.g. `sonnet`, `kimi-for-coding`, `gpt-5-codex`). Omit for harness default. */
     model?: string;
-    /** Router-issued unlock token. Required unless operator has disabled the gate. */
-    unlock: string;
+    /** Router-issued unlock token. Required for router-mediated bridge calls; unused by direct cli-bridge clients. */
+    unlock?: string;
     /** Stable caller-owned id for session resume. Map one id per logical conversation. */
     resume?: string;
     /** BYOB: point at your own cli-bridge instance. Router must have BYOB enabled. */
@@ -347,6 +392,12 @@ interface BridgeOptions {
     /** BYOB: bearer your cli-bridge expects. */
     bridgeBearer?: string;
 }
+interface SandboxChatOptions {
+    /** Inline sandbox AgentProfile. Serialized as cli-bridge/sandbox-api `agent_profile`. */
+    agentProfile?: AgentProfile;
+    /** Direct sandbox or cli-bridge session id. Serialized as `session_id`. */
+    sessionId?: string;
+}
 interface ChatOptions {
     /** Model to use */
     model?: string;
@@ -386,10 +437,15 @@ interface ChatOptions {
     gateway?: GatewayOptions;
     /**
      * Provider-specific parameters passed through to the upstream API.
-     * These are spread into the request body alongside standard fields.
+     * Protected OpenAI/Tangle fields cannot be overridden from this escape hatch.
      * Example: `{ thinking: { type: 'enabled', budget_tokens: 8000 } }`
      */
     providerOptions?: Record<string, unknown>;
+    /**
+     * Typed sandbox/cli-bridge extensions. Use this instead of smuggling
+     * `agent_profile` or `session_id` through providerOptions.
+     */
+    sandbox?: SandboxChatOptions;
     /**
      * Route this call through the Tangle Router's cli-bridge short-circuit.
      * See {@link BridgeOptions}. When set, `model` is rewritten to
@@ -696,9 +752,10 @@ declare 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: {
         /** cli-bridge base URL — `http://127.0.0.1:3344` for default local; can be any reachable URL. */
@@ -718,7 +775,7 @@ declare 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')
@@ -816,6 +873,7 @@ declare class TCloudClient {
      * a rotating client throws.
      */
     bridge(cfg: BridgeOptions): BridgeSession;
+    private _isDirectCliBridge;
     /**
      * Rotation stats — populated only on clients created via
      * {@link TCloudClient.rotating}. Non-rotating clients return an empty
@@ -897,6 +955,18 @@ declare class TCloudClient {
     embeddings(options: EmbeddingOptions): Promise<EmbeddingResponse>;
     /** Generate images */
     imageGenerate(options: ImageGenerateOptions): Promise<ImageResponse>;
+    /**
+     * 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.
+     */
+    imagesEdit(options: ImageEditOptions): Promise<ImageResponse>;
     /** Rerank documents by relevance to a query */
     rerank(options: RerankOptions): Promise<RerankResponse>;
     /** Text-to-speech */
@@ -1167,7 +1237,8 @@ declare class TCloudClient {
 declare class BridgeSession {
     private readonly client;
     private readonly cfg;
-    constructor(client: TCloudClient, cfg: BridgeOptions);
+    private readonly direct;
+    constructor(client: TCloudClient, cfg: BridgeOptions, direct?: boolean);
     /** Full chat completion (non-streaming). */
     chat(options: Omit<ChatOptions, 'bridge'>): Promise<ChatCompletion>;
     /** Stream OpenAI chat.completion.chunks. */
@@ -1215,4 +1286,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 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 };
+export { type VideoGenerateOptions as $, type ApiKeyInfo as A, type BatchJobResponse as B, type ChatCompletion as C, type RerankResponse as D, type EmbeddingOptions as E, type FineTuningJob as F, type GatewayOptions as G, type RetryConfig as H, type ImageEditAttachment as I, type JobEvent as J, type RotatingRoutingConfig as K, type RotationStats as L, type Model as M, type RoutingConfig as N, type Operator as O, type PricingTier as P, type RoutingStrategy as Q, type RotatingClientConfig as R, type SandboxChatOptions as S, TCloudClient as T, type ShieldedConfig as U, type SpendAuth as V, type SpendingLimits as W, TCloudError as X, type TierConfig as Y, type TranscriptionResponse as Z, type UpdateKeyOptions as _, type TCloudConfig as a, type VideoResponse as a0, type WatchJobOptions as a1, 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 ImageEditOptions as s, type ImageGenerateOptions as t, type ImageResponse as u, type OperatorInfo as v, type PrivacyConfig as w, PrivateRouter as x, type PrivateRouterConfig as y, type RerankOptions as z };