@sogni-ai/sogni-client 5.1.0-alpha.2 → 5.1.0-alpha.20

package/AGENTS.md

@@ -36,6 +36,7 @@ The SDK wraps the public Sogni Intelligence endpoints used for text chat, hosted
 
 - `sogni.chat.completions.create()` maps to socket-native chat completions and supports text, streaming, vision input, custom function tools, Sogni tool injection, structured outputs, and `think` / `taskProfile` controls.
 - `sogni.chat.hosted.create()` maps to `POST /v1/chat/completions`, the OpenAI-compatible REST chat endpoint. It can execute Sogni media-generation and composition tools server-side.
+- `sogni.chat.hosted.executeTool()` maps to `POST /v1/creative-agent/tools/execute` for direct execution of known synchronous composition/planning tools (`enhance_prompt`, `compose_script`, `compose_lyrics`, `compose_instrumental`, `compose_workflow`, `compose_workflow_template`) without an LLM dispatcher round.
 - `sogni.chat.runs` maps to `/v1/chat/runs`, a durable hosted-chat turn with persisted state, event replay, cancellation, and recovery across client disconnects.
 - `sogni.workflows` maps to `/v1/creative-agent/workflows`, where callers submit exact multi-step creative plans and observe durable execution through snapshots, event logs, or SSE.
 - `sogni.workflows.templates` maps to `/v1/creative-agent/workflows/templates`, the CRUD and fork API for saved, parameterized workflow recipes.
@@ -49,7 +50,7 @@ Public chat and workflow media rules:
 
 ## Overview
 
-This is the **Sogni SDK for JavaScript/Node.js** - a TypeScript client library for the Sogni Supernet, a DePIN protocol for creative AI inference. The SDK supports image generation (Stable Diffusion, Flux, Z-Image, Qwen image-edit models, GPT Image 2), video generation (WAN 2.2, LTX-2.3, Seedance 2.0), audio generation (ACE-Step 1.5), LLM chat with tool calling, hosted creative tools, durable creative workflows, replay records, and multimodal vision chat (Qwen3.6 35B VLM, default `qwen3.6-35b-a3b-gguf-iq4xs`).
+This is the **Sogni SDK for JavaScript/Node.js** - a TypeScript client library for the Sogni Supernet, a DePIN protocol for creative AI inference. The SDK supports image generation (Stable Diffusion, Flux, Flux.2, Z-Image / Z-Image Turbo, Krea 2 Turbo, Krea 2 Identity Edit, Chroma v.46 Flash / v.48 Detail / Chroma1-HD, Qwen image-edit models, GPT Image 2, plus community fine-tunes such as Dark Beast Z-Image Turbo v9, Dark Beast KREA 2, Dark Beast Krea 2 Identity Edit, and One Obsession v22), video generation (WAN 2.2, LTX-2.3, Seedance 2.0, HappyHorse 1.1), audio generation (ACE-Step 1.5), LLM chat with tool calling, hosted creative tools, durable creative workflows, replay records, and multimodal vision chat (Qwen3.6 35B VLM, default `qwen3.6-35b-a3b-gguf-iq4xs`). The model catalog is discovered dynamically at runtime (`sogni.projects.getAvailableModels()`); model ids listed here are illustrative.
 
 Runtime and packaging:
 
@@ -201,6 +202,14 @@ The SDK supports two families of video models with **fundamentally different FPS
 - **Frame calculation**: `duration * 16 + 1` (always uses 16, ignores fps)
 - Example: 5 seconds at 32fps = 81 frames generated → interpolated to 161 output frames
 
+### External-API Partner Models (Seedance 2.0, Happy Horse 1.1)
+
+**Seedance 2.0** (`seedance-2-0` / `-mini` / `-fast`) and **Happy Horse 1.1** (`happyhorse-1.1-t2v` / `-i2v` / `-r2v`) run on partner external APIs, not Sogni GPU workers:
+- **Spark-only** billing, **fixed 24fps**, and **native audio** (no separate audio params to set).
+- No local diffusion steps — progress is provider/ETA-derived (still a finite 0-100). Results can arrive as direct hosted URLs, preserved on `job.resultUrl` / `job.getResultUrl()`.
+- **Seedance** accepts image + video + audio references (up to 9 / 3 / 3, 12 total) via `referenceImage*` / `referenceImageUrls` / `referenceVideoUrls` / `referenceAudioUrls`. **Happy Horse** accepts **image-only** references (r2v takes 1-9 images via `referenceImage` / `referenceImageUrls`).
+- Family predicates: `isSeedanceModel()`, `isHappyhorseModel()`, `isExternalApiVideoModel()` in `src/Projects/utils/index.ts`.
+
 ### Key Files
 - `src/Projects/utils/index.ts` - `isWanModel()`, `isLtx2Model()`, `calculateVideoFrames()`
 - `src/Projects/createJobRequestMessage.ts` - Uses `calculateVideoFrames()` for duration→frames conversion
@@ -290,6 +299,7 @@ const urls = await project.waitForCompletion();
 |----------|---------------|-----------------|
 | Text-to-Video | `*_t2v*` | None |
 | Image-to-Video | `*_i2v*` | `referenceImage` (and/or `referenceImageEnd`) |
+| Reference-to-Video | `*_r2v*` (Happy Horse) | 1-9 images via `referenceImage`/`referenceImageUrls` |
 | Video-to-Video | `*_v2v*` (LTX-2.3) | `referenceVideo` + `controlNet` |
 | Sound-to-Video | `*_s2v*` (WAN only) | `referenceImage` + `referenceAudio` |
 | Image+Audio-to-Video | `*_ia2v*` (LTX-2.3) | `referenceImage` + `referenceAudio` |

package/CHANGELOG.md

@@ -1,3 +1,150 @@
+# [5.1.0-alpha.20](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.19...v5.1.0-alpha.20) (2026-07-18)
+
+
+### Features
+
+* add Krea identity edit awareness ([bcb7cc3](https://github.com/Sogni-AI/sogni-client/commit/bcb7cc3068f30233ded5f1f546ed9604c2d98743))
+
+# [5.1.0-alpha.19](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.18...v5.1.0-alpha.19) (2026-07-11)
+
+
+### Features
+
+* add chat safe-content routing flag ([822a863](https://github.com/Sogni-AI/sogni-client/commit/822a863c7a6888defd67ce79b63751bc92c23b7c))
+
+# [5.1.0-alpha.18](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.17...v5.1.0-alpha.18) (2026-07-11)
+
+
+### Features
+
+* **chat:** add direct hosted tool execution ([d5c182a](https://github.com/Sogni-AI/sogni-client/commit/d5c182a14d31a8fdb661c67682fa6cc2401188d3))
+
+# [5.1.0-alpha.17](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.16...v5.1.0-alpha.17) (2026-07-10)
+
+
+### Bug Fixes
+
+* **workflows:** pass billing mode through durable workflows ([70ad0ad](https://github.com/Sogni-AI/sogni-client/commit/70ad0ad45c36810397f7c7e83925c94150d909ba))
+
+# [5.1.0-alpha.16](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.15...v5.1.0-alpha.16) (2026-06-30)
+
+
+### Features
+
+* **examples:** expose Krea 2 style LoRA in text-to-image example ([62aa174](https://github.com/Sogni-AI/sogni-client/commit/62aa17416bd1868e2a62b02993a169a06cd8e9a7))
+
+# [5.1.0-alpha.15](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.14...v5.1.0-alpha.15) (2026-06-28)
+
+
+### Bug Fixes
+
+* **deps:** bump @sogni-ai/sogni-protocol to 1.0.0-alpha.9 ([05008b9](https://github.com/Sogni-AI/sogni-client/commit/05008b9fc62f326f52c72d43a1b71e8b9cd3f1f3))
+
+
+### Features
+
+* **models:** add Krea 2 Turbo image model support ([19572e2](https://github.com/Sogni-AI/sogni-client/commit/19572e214390b79af0138a687c45ec37b26eb4ac))
+* **video:** add HappyHorse 1.1 video model routing ([75f2ebe](https://github.com/Sogni-AI/sogni-client/commit/75f2ebea4be8a65d2a055e22d6625c3c1cfcd053))
+
+# [5.1.0-alpha.14](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.13...v5.1.0-alpha.14) (2026-06-25)
+
+
+### Bug Fixes
+
+* **deps:** bump sogni protocol alpha ([e2f9a4b](https://github.com/Sogni-AI/sogni-client/commit/e2f9a4b012340a4501145dcb33db9227c4347ff7))
+
+# [5.1.0-alpha.13](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.12...v5.1.0-alpha.13) (2026-06-25)
+
+
+### Features
+
+* add Seedance Mini routing ([11c2855](https://github.com/Sogni-AI/sogni-client/commit/11c28552ed4834a0861201b305420c9e930f5daf))
+
+# [5.1.0-alpha.12](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.11...v5.1.0-alpha.12) (2026-06-25)
+
+
+### Features
+
+* **subscription:** add paymentPending to entitlement snapshot ([#17](https://github.com/Sogni-AI/sogni-client/issues/17)) ([792d959](https://github.com/Sogni-AI/sogni-client/commit/792d959710fac8daaf5ea358c2746de916e650e2))
+
+# [5.1.0-alpha.11](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.10...v5.1.0-alpha.11) (2026-06-25)
+
+
+### Features
+
+* **video:** expose Seedance 4K client metadata ([19e1dd5](https://github.com/Sogni-AI/sogni-client/commit/19e1dd5319bd0a859cbae8fb8ff6672ef068fddc))
+
+# [5.1.0-alpha.10](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.9...v5.1.0-alpha.10) (2026-06-18)
+
+
+### Features
+
+* **audio:** prefer ACE-Step XL music models ([ec5a715](https://github.com/Sogni-AI/sogni-client/commit/ec5a71579d04b42863ce9627c8ea4935b0190f70))
+* **projects:** expose LTX-2.3 v2v outpaint and inpaint controls ([1a60576](https://github.com/Sogni-AI/sogni-client/commit/1a605766e42b6fa5cdedf0a64425deb51cbf81b1))
+
+# [5.1.0-alpha.9](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.8...v5.1.0-alpha.9) (2026-06-16)
+
+
+### Features
+
+* **subscription:** expose frontier vendor discount in types ([1e06f99](https://github.com/Sogni-AI/sogni-client/commit/1e06f99e54e39c2d09d65263c0ed6a5f52dbac18))
+
+# [5.1.0-alpha.8](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.7...v5.1.0-alpha.8) (2026-06-16)
+
+
+### Features
+
+* **chat:** carry subscription-limit fields on ChatJobError ([33c7ecd](https://github.com/Sogni-AI/sogni-client/commit/33c7ecdab22c571f6983fbb479bdbb5eb885a672))
+* **chat:** forward 4081 limit fields at error call sites ([ef5b66a](https://github.com/Sogni-AI/sogni-client/commit/ef5b66a8b28dd52755f22cf76609258ecf2fe6dc))
+* **projects:** surface 4081 limit fields on render errors ([13fa158](https://github.com/Sogni-AI/sogni-client/commit/13fa158f00c4e4415bb4d0f3c7eaf9979f1f7d40))
+* **socket:** type 4081 limit fields on job error events ([0026438](https://github.com/Sogni-AI/sogni-client/commit/0026438ccbfb1cefe5be38861372d1430ade0eb2))
+* **subscription:** add isSubscriptionLimitError helper ([139953b](https://github.com/Sogni-AI/sogni-client/commit/139953bc003aefc2f3ba09f8e4000982a071f7e8))
+* **subscription:** recognize 4081 feature-gate denial code ([c513fe6](https://github.com/Sogni-AI/sogni-client/commit/c513fe67243c91e0ca8ccb5d301a3be20dcf1486))
+
+# [5.1.0-alpha.7](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.6...v5.1.0-alpha.7) (2026-06-12)
+
+
+### Bug Fixes
+
+* **account:** map real socket entitlement status domain without dropping fields ([c2e7499](https://github.com/Sogni-AI/sogni-client/commit/c2e7499c5d254e8ce61da257b44307bca97ea56c))
+
+
+### Features
+
+* **account:** accept chat checkout redirect target ([3900336](https://github.com/Sogni-AI/sogni-client/commit/390033692aaa46eff521030d80ba712f15bd3302))
+* **account:** guard subscription writes against stale transports ([c60af1f](https://github.com/Sogni-AI/sogni-client/commit/c60af1ff4e4a9a8af1a8e2393899026f176a3f53))
+* **chat:** preserve job error codes via typed ChatJobError ([dd5ad1d](https://github.com/Sogni-AI/sogni-client/commit/dd5ad1d585c709382547bfa4cff2aa98d734414c))
+* **chat:** serialize billingMode on all three chat transports ([787dd43](https://github.com/Sogni-AI/sogni-client/commit/787dd4391dee1735a6d3d3a7953f25ec6c722a4d))
+* **types:** export subscription billing socket error-code constants ([2fd5af4](https://github.com/Sogni-AI/sogni-client/commit/2fd5af49ffa76d6f1a304c6a06577468f5865c2e))
+
+# [5.1.0-alpha.6](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.5...v5.1.0-alpha.6) (2026-06-12)
+
+
+### Features
+
+* sync socket subscription entitlement ([fa5d24d](https://github.com/Sogni-AI/sogni-client/commit/fa5d24d307992993ac312c3b1e8ab94277529aa4))
+
+# [5.1.0-alpha.5](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.4...v5.1.0-alpha.5) (2026-06-11)
+
+
+### Features
+
+* **subscription:** pending plan-change snapshot fields and grace-period doc fix ([596e4a0](https://github.com/Sogni-AI/sogni-client/commit/596e4a030dc1114e5fdd90d3dce3dd799c5f1ede))
+
+# [5.1.0-alpha.4](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.3...v5.1.0-alpha.4) (2026-06-11)
+
+
+### Bug Fixes
+
+* **projects:** forward billing mode metadata ([975fdb0](https://github.com/Sogni-AI/sogni-client/commit/975fdb09adcbd74c11fa6786edb6f1d2392583eb))
+
+# [5.1.0-alpha.3](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.2...v5.1.0-alpha.3) (2026-06-10)
+
+
+### Features
+
+* **subscription:** mirror term, google productId, and manual provider ([78b3114](https://github.com/Sogni-AI/sogni-client/commit/78b311457c71448578b8f561cc7865e7bcaf9f20))
+
 # [5.1.0-alpha.2](https://github.com/Sogni-AI/sogni-client/compare/v5.1.0-alpha.1...v5.1.0-alpha.2) (2026-06-10)
 
 

package/README.md

@@ -189,7 +189,19 @@ if (sogni.account.currentAccount.isUnlimited) {
 }
 ```
 
-`currentAccount.isUnlimited` is `true` when the latest entitlement snapshot has `active: true` and `tier` is either `unlimited` or `unlimited_pro`. The server keeps `active` true for entitled states such as trials, grace periods, and cancel-at-period-end windows until access actually ends. Period dates are ISO timestamp strings.
+`currentAccount.isUnlimited` is `true` when the latest entitlement snapshot has `active: true` and `tier` is either `unlimited` or `unlimited_pro`. The server keeps `active` true for entitled states until access actually ends: trials and cancel-at-period-end windows remain entitled, with `currentPeriodEnd` reflecting the paid-through date. Canceling during a free trial is the exception: it ends Unlimited access immediately by default, so the next snapshot reports `active: false`. A `grace_period` snapshot is never entitled and returns `active: false`: it means the provider (Apple billing grace / Google Play grace / Stripe retries) is retrying the renewal payment, and unlimited render access is paused while the retry is in progress — render submissions under the plan return a specific error from the platform explaining that the renewal payment is being retried and that unlimited access resumes once it succeeds. Renders can still be paid with Spark/SOGNI in the meantime, and unlimited access resumes automatically when the renewal succeeds. During grace the snapshot's effective period end indicates the payment-retry window, not access. Period dates are ISO timestamp strings.
+
+A canceled-but-still-paid subscription carries `cancelAtPeriodEnd: true` and keeps access until `currentPeriodEnd`. When a downgrade or plan switch is scheduled for the next renewal, the snapshot may also carry `scheduledTier`, `scheduledTerm`, and `scheduledChangeAt` (ISO timestamp) — absent when no change is pending — so UIs can render "Your plan will change to X on date" messaging while the current tier keeps its benefits.
+
+When a job is explicitly submitted with `billingMode: 'subscription'` and the subscription cannot cover it, the platform rejects the job with a subscription-specific error code, exported as `SUBSCRIPTION_ERROR_CODES` from the package root:
+
+- `4078` (`NOT_ENTITLED`) — no active subscription entitlement covers the job.
+- `4079` (`QUEUE_CAP`) — the subscription's concurrent job queue cap was reached.
+- `4080` (`GRACE_RETRY`) — the subscription is in its billing-grace window: the renewal payment is being retried and unlimited access is paused until it succeeds. On `4080`, offer the user a "pay with Spark/SOGNI" fallback (token billing) instead of auto-retrying the subscription job in a loop — it will keep failing until the renewal succeeds.
+
+`billingMode` (`'auto' | 'subscription' | 'tokens'`, exported as `BillingMode`) is accepted by project params, creative workflows (`sogni.workflows.start()`, `resume()`, and `reseed()`, where it serializes as `billing_mode`), and all three chat transports: `sogni.chat.completions.create()` (socket), `sogni.chat.hosted.create()` (REST `/v1/chat/completions`), and `sogni.chat.runs.create()` (durable runs, where it serializes as `billing_mode`).
+
+Chat job failures preserve this error contract. Streamed and non-streaming chat completions, hosted REST chat, and durable chat runs fail with a `ChatJobError` (exported from the package root): `.message` stays the human-readable server message, while `code`/`errorCode` carry the wire code string (e.g. `'4080'`), `errorType` carries the server's tag (e.g. `'subscription_unavailable'`), and the `subscriptionErrorCode` getter maps the code back to the numeric `SUBSCRIPTION_ERROR_CODES` value when applicable — so apps can branch without string-matching.
 
 Unlimited fair-use accounting and enforcement are handled dynamically by the Sogni socket service. The SDK does not expose per-period usage counters or plan limit tables for clients to store or display as durable user-facing limits.
 
@@ -613,7 +625,7 @@ export interface ControlNetParams {
 }
 ```
 
-## Video Generation with Wan 2.2 Models
+## Video Generation (WAN 2.2, LTX-2.3, Seedance 2.0 & Happy Horse 1.1)
 
 The Sogni SDK supports advanced video generation workflows powered by **Wan 2.2 14B FP8** models. These models are available on the `fast` network and support various video generation workflows.
 
@@ -634,7 +646,7 @@ WAN workflows have two model variants optimized for different use cases:
 - **Speed variant** (with `_lightx2v` suffix) - Faster inference (4-step), good quality
 - **Quality variant** (without `_lightx2v`) - Slower inference, best quality
 
-LTX-2.3 models use `distilled` and `dev` variants for fast/high-quality generation with native audio. Seedance 2.0 models use the external API path and are available through two canonical multimodal model IDs: `seedance-2-0` and `seedance-2-0-fast`. Both accept optional image, video, and audio references, run at fixed 24fps, and require Spark billing; the Fast model caps output at 720p.
+LTX-2.3 models use `distilled` and `dev` variants for fast/high-quality generation with native audio. Seedance 2.0 models use the external API path and are available through three canonical multimodal model IDs: `seedance-2-0`, `seedance-2-0-mini`, and `seedance-2-0-fast`. All accept optional image, video, and audio references, run at fixed 24fps, and require Spark billing; the full model supports up to 4K, while Mini and Fast cap output at 720p. Happy Horse 1.1 is an external-API video model with text-to-video, image-to-video, and reference-to-video modes (`happyhorse-1.1-t2v` / `-i2v` / `-r2v`); it accepts image-only references (no video or audio reference assets), and is Spark-only.
 
 Example model IDs:
 
@@ -649,8 +661,12 @@ Example model IDs:
 - `ltx23-22b-fp8_t2v_distilled` (LTX-2.3 Text-to-Video, fast)
 - `ltx23-22b-fp8_i2v_distilled` (LTX-2.3 Image-to-Video, fast)
 - `ltx23-22b-fp8_v2v_distilled` (LTX-2.3 Video-to-Video ControlNet, fast)
-- `seedance-2-0` (Seedance 2.0 multimodal video, external API)
+- `seedance-2-0` (Seedance 2.0 multimodal video, external API, 4K capable)
+- `seedance-2-0-mini` (Seedance 2.0 Mini multimodal video, external API, 720p cap)
 - `seedance-2-0-fast` (Seedance 2.0 Fast multimodal video, external API, 720p cap)
+- `happyhorse-1.1-t2v` (Happy Horse 1.1 Text-to-Video, external API, image-only references)
+- `happyhorse-1.1-i2v` (Happy Horse 1.1 Image-to-Video, external API, one first-frame image)
+- `happyhorse-1.1-r2v` (Happy Horse 1.1 Reference-to-Video, external API, 1-9 reference images)
 
 ### Video Parameters
 
@@ -666,7 +682,7 @@ When creating video projects, you can specify:
 - `referenceImage` - Reference image for workflows that require it (i2v, s2v, animate-move, animate-replace)
 - `referenceVideo` - Reference video for animate and v2v workflows
 - `referenceAudio` - Reference audio for sound-to-video workflow
-- `referenceImageUrls` - Seedance-only loose image context URLs; combined with `referenceImage`/`referenceImageEnd`, max 9 image assets
+- `referenceImageUrls` - Loose image context URLs for Seedance and Happy Horse (Happy Horse r2v takes 1-9 reference images here); combined with `referenceImage`/`referenceImageEnd`, max 9 image assets
 - `referenceVideoUrls` - Seedance-only video context URLs; combined with `referenceVideo`, max 3 video assets
 - `referenceAudioUrls` - Seedance-only audio context URLs; combined with `referenceAudio`/`referenceAudioIdentity`, max 3 audio assets
 - `hasVideoInput` - Estimate-only flag for `estimateVideoCost`; set this when estimating a canonical Seedance video-input job without passing `referenceVideo`/`referenceVideoUrls`
@@ -702,7 +718,7 @@ const project = await sogni.projects.create({
   duration: 5,
   fps: 24,
   width: 1920,
-  height: 1088,
+  height: 1080,
   tokenType: 'spark'
 });
 
@@ -721,7 +737,7 @@ const project = await sogni.projects.create({
   duration: 8,
   fps: 24,
   width: 1920,
-  height: 1088,
+  height: 1080,
   referenceImageUrls: [
     'https://cdn.example.com/product-front.png',
     'https://cdn.example.com/product-detail.png'
@@ -890,9 +906,24 @@ Combine LLM intelligence with Sogni's media generation capabilities. The SDK exp
 
 Pass `SogniTools.all` (or individual definitions like `generateImageTool`, `animatePhotoTool`, `composeScriptTool`) to an LLM via the `tools` parameter, then route tool calls through `sogni.chat.hosted.create()` / `sogni.chat.runs.create()` for server-side execution. Generated artifacts are threaded through a per-request media context so later rounds can reference earlier outputs by index (`sourceImageIndex`, `videoIndices`, `audioIndex`, etc.).
 
+When your app already knows the exact synchronous composition/planning tool and JSON arguments, skip the dispatcher round and call `sogni.chat.hosted.executeTool()` directly. Direct execution supports `enhance_prompt`, `compose_script`, `compose_lyrics`, `compose_instrumental`, `compose_workflow`, and `compose_workflow_template`; long-running media generation still belongs on hosted chat/runs or `sogni.workflows`.
+
+```javascript
+const direct = await sogni.chat.hosted.executeTool({
+  tool: 'enhance_prompt',
+  arguments: {
+    prompt: 'A cinematic portrait of a glass robot',
+    destination_tool: 'generate_image'
+  },
+  tokenType: 'spark'
+});
+
+console.log(direct.data.message);
+```
+
 For direct `/v1/chat/completions` hosted-tool execution, media-bearing tool arguments use inline `data:` URIs. For user-uploaded image/audio/video inputs, use the SDK video project examples or the `sogni.workflows` wrapper for `/v1/creative-agent/workflows`; these can consume HTTPS artifact URLs produced by Sogni's upload endpoints. Durable workflows validate explicit steps before the workflow starts and can bind SDK request-level `mediaReferences` into tool arguments with `sourceStepId: "$input_media"`.
 
-The `workflow_text_chat_sogni_tools.mjs` example demonstrates the core text-to-image, text-to-video, and text-to-music composition flows. Dedicated workflow examples like `workflow_image_edit.mjs`, `workflow_sound_to_video.mjs`, and `workflow_video_to_video.mjs` cover the asset-backed workflows directly.
+The `workflow_text_chat_sogni_tools.mjs` example demonstrates the core text-to-image, text-to-video, and text-to-music composition flows. `workflow_direct_creative_tool.mjs` demonstrates direct one-call execution for known synchronous tools. Dedicated workflow examples like `workflow_image_edit.mjs`, `workflow_sound_to_video.mjs`, and `workflow_video_to_video.mjs` cover the asset-backed workflows directly.
 
 ### Hosted Tool Surfaces — `sogni_tools` parameter
 
@@ -938,6 +969,8 @@ const result = await sogni.chat.hosted.create({
 
 See `examples/workflow_creative_agent_tools.mjs` for a runnable REST API-key example that can toggle tool surface and server-side execution.
 
+See `examples/workflow_direct_creative_tool.mjs` when you already know the hosted synchronous tool to run and want to call it without asking the LLM to select a tool first.
+
 For focused partner Seedance video tests, `examples/workflow_partner_seedance_video.mjs` starts with a guided workflow picker when run with no arguments. The guided path covers T2V, I2V, IA2V, V2V, the full and fast Seedance tiers where available, hosted workflow execution, native audio, keyframe interpolation, multimodal context, and cost estimation. The command-line path still supports direct scripted calls:
 
 ```bash
@@ -1058,11 +1091,20 @@ The workflow examples showcase a few powerful open-source frontier models suppor
 | ------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
 | `z_image_turbo_bf16`                 | **Z-Image Turbo** - Ultra-fast 8-step generation      | Quick text-to-image prototyping and iteration                                                                |
 | `z_image_bf16`                       | **Z-Image** - High quality 20-step generation         | Detailed, high quality image output                                                                          |
+| `krea2_turbo_fp8_scaled`             | **Krea 2 Turbo** - Fast 8-step, strong in-image text  | Text-heavy images and fast iteration, up to 2K                                                               |
+| `krea2_identity_edit_v1_2`           | **Krea 2 Identity Edit LoRA v1.2** - Identity editing | Preserve a subject across edits with 1-2 reference images                                                    |
+| `chroma1-hd_fp8_scaled`              | **Chroma1-HD** - Final high-res Chroma (uncensored)   | Highest-fidelity Chroma output, LoRA-capable                                                                 |
+| `flux2_dev_fp8`                      | **Flux.2 \[dev\]** - Pro quality, context images      | Professional images and reference-guided editing (up to 6 context images)                                    |
 | `qwen_image_edit_2511_fp8_lightning` | **Qwen Image Edit Lightning** - Fast 4-step editing   | Rapid reference-based image generation                                                                       |
 | `qwen_image_edit_2511_fp8`           | **Qwen Image Edit** - High quality 20-step editing    | Professional image editing with context awareness                                                            |
 | `wan_v2.2-14b-fp8_t2v_lightx2v`      | **Wan 2.2 T2V** - Text-to-video                       | Generate videos from text prompts                                                                            |
-| `seedance-2-0`                       | **Seedance 2.0** - External API multimodal video      | Full Seedance 2.0 24fps video generation with optional image, video, and audio context                       |
-| `seedance-2-0-fast`                  | **Seedance 2.0 Fast** - 720p external API video       | Faster 24fps video generation where fast tiers are enabled                                                   |
+| `seedance-2-0`                       | **Seedance 2.0** - 4K external API multimodal video   | Full Seedance 2.0 24fps video generation with optional image, video, and audio context                       |
+| `seedance-2-0-mini`                  | **Seedance 2.0 Mini** - 720p external API video       | Fastest, lower-cost 24fps Seedance video generation                                                          |
+| `seedance-2-0-fast`                  | **Seedance 2.0 Fast** - 720p external API video       | Legacy faster 24fps video generation where fast tiers are enabled                                            |
+| `dark_beast_z_image_turbo_v9_bf16`   | **Dark Beast Z-Image Turbo v9** - Community (uncensored) | Uncensored, fast Z-Image fine-tune (2K output needs a 24GB+ VRAM worker)                                    |
+| `dark_beast_krea2_fp8`               | **Dark Beast KREA 2** - Community (uncensored)        | Uncensored Krea 2 fine-tune (2K output needs a 24GB+ VRAM worker)                                            |
+| `dark_beast_krea2_identity_edit_v1_2` | **Dark Beast Krea 2 Identity Edit** - Community       | Uncensored identity-preserving Krea 2 edit LoRA with 1-2 reference images                                    |
+| `one_obsession_v22_fp16`             | **One Obsession v22** - Community (Illustrious/anime) | Anime/illustration checkpoint, LoRA-capable                                                                  |
 | `qwen3.6-35b-a3b-gguf-iq4xs`         | **Qwen3.6 35B VLM** - LLM chat, tool calling & vision | Latest model with 262,144 native context length, reasoning, tool calling, and multimodal image understanding |
 
 All workflow examples include:

package/dist/Account/CurrentAccount.d.ts

@@ -23,8 +23,9 @@ export interface AccountData {
     email?: string;
     /**
      * The most recently fetched subscription entitlement snapshot.
-     * `undefined` until {@link AccountApi.getSubscriptionStatus} or
-     * {@link AccountApi.refreshSubscription} has been called.
+     * `undefined` until the account receives a socket entitlement snapshot or
+     * {@link AccountApi.getSubscriptionStatus} / {@link AccountApi.refreshSubscription}
+     * has been called.
      *
      * Subscribe to the `'updated'` event (inherited from `DataEntity`) to react
      * to changes; the `changedKeys` array will include `'subscription'` when
@@ -48,8 +49,9 @@ declare class CurrentAccount extends DataEntity<AccountData> {
     get email(): string | undefined;
     /**
      * The most recently cached subscription entitlement snapshot.
-     * `undefined` until {@link AccountApi.getSubscriptionStatus} or
-     * {@link AccountApi.refreshSubscription} has been called.
+     * `undefined` until the account receives a socket entitlement snapshot or
+     * {@link AccountApi.getSubscriptionStatus} / {@link AccountApi.refreshSubscription}
+     * has been called.
      */
     get subscription(): SubscriptionEntitlementSnapshot | undefined;
     /**
@@ -59,8 +61,8 @@ declare class CurrentAccount extends DataEntity<AccountData> {
      *
      * Returns `false` when no entitlement snapshot has been fetched yet, when
      * the server reports no active entitlement, or when the tier is not an
-     * Unlimited tier. Call {@link AccountApi.refreshSubscription} to populate the
-     * snapshot first.
+     * Unlimited tier. Call {@link AccountApi.refreshSubscription} to force a REST
+     * refresh when no socket entitlement snapshot has been received yet.
      */
     get isUnlimited(): boolean;
 }

package/dist/Account/CurrentAccount.js

@@ -62,8 +62,9 @@ class CurrentAccount extends DataEntity_js_1.default {
     }
     /**
      * The most recently cached subscription entitlement snapshot.
-     * `undefined` until {@link AccountApi.getSubscriptionStatus} or
-     * {@link AccountApi.refreshSubscription} has been called.
+     * `undefined` until the account receives a socket entitlement snapshot or
+     * {@link AccountApi.getSubscriptionStatus} / {@link AccountApi.refreshSubscription}
+     * has been called.
      */
     get subscription() {
         return this.data.subscription;
@@ -75,8 +76,8 @@ class CurrentAccount extends DataEntity_js_1.default {
      *
      * Returns `false` when no entitlement snapshot has been fetched yet, when
      * the server reports no active entitlement, or when the tier is not an
-     * Unlimited tier. Call {@link AccountApi.refreshSubscription} to populate the
-     * snapshot first.
+     * Unlimited tier. Call {@link AccountApi.refreshSubscription} to force a REST
+     * refresh when no socket entitlement snapshot has been received yet.
      */
     get isUnlimited() {
         const sub = this.data.subscription;

package/dist/Account/CurrentAccount.js.map

@@ -1 +1 @@
-{"version":3,"file":"CurrentAccount.js","sourceRoot":"","sources":["../../src/Account/CurrentAccount.ts"],"names":[],"mappings":";;;;;AAAA,yEAA8C;AAmC9C,SAAS,WAAW;IAClB,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,OAAO,EAAE,IAAI;QACb,OAAO,EAAE;YACP,KAAK,EAAE;gBACL,MAAM,EAAE,GAAG;gBACX,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,GAAG;gBACR,OAAO,EAAE,GAAG;aACb;YACD,KAAK,EAAE;gBACL,MAAM,EAAE,GAAG;gBACX,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,GAAG;gBACR,OAAO,EAAE,GAAG;gBACZ,aAAa,EAAE,GAAG;aACnB;SACF;QACD,aAAa,EAAE,SAAS;QACxB,QAAQ,EAAE,SAAS;QACnB,YAAY,EAAE,SAAS;KACxB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,cAAe,SAAQ,uBAAuB;IAClD,YAAY,IAAkB;QAC5B,KAAK,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,cAAc;QAChB,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACnC,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;IAC5B,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;IAChC,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,WAAW;QACb,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;QACnC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACtC,OAAO,GAAG,CAAC,IAAI,KAAK,WAAW,IAAI,GAAG,CAAC,IAAI,KAAK,eAAe,CAAC;IAClE,CAAC;CACF;AAED,kBAAe,cAAc,CAAC"}
+{"version":3,"file":"CurrentAccount.js","sourceRoot":"","sources":["../../src/Account/CurrentAccount.ts"],"names":[],"mappings":";;;;;AAAA,yEAA8C;AAoC9C,SAAS,WAAW;IAClB,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,OAAO,EAAE,IAAI;QACb,OAAO,EAAE;YACP,KAAK,EAAE;gBACL,MAAM,EAAE,GAAG;gBACX,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,GAAG;gBACR,OAAO,EAAE,GAAG;aACb;YACD,KAAK,EAAE;gBACL,MAAM,EAAE,GAAG;gBACX,KAAK,EAAE,GAAG;gBACV,GAAG,EAAE,GAAG;gBACR,OAAO,EAAE,GAAG;gBACZ,aAAa,EAAE,GAAG;aACnB;SACF;QACD,aAAa,EAAE,SAAS;QACxB,QAAQ,EAAE,SAAS;QACnB,YAAY,EAAE,SAAS;KACxB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,cAAe,SAAQ,uBAAuB;IAClD,YAAY,IAAkB;QAC5B,KAAK,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,cAAc;QAChB,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACnC,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;IAC3B,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC;IAC5B,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;IAChC,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,WAAW;QACb,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC;QACnC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACtC,OAAO,GAAG,CAAC,IAAI,KAAK,WAAW,IAAI,GAAG,CAAC,IAAI,KAAK,eAAe,CAAC;IAClE,CAAC;CACF;AAED,kBAAe,cAAc,CAAC"}

package/dist/Account/index.d.ts

@@ -18,12 +18,44 @@ import { SupernetType } from '../ApiClient/WebSocketClient/types.js';
  */
 declare class AccountApi extends ApiGroup {
     readonly currentAccount: CurrentAccount;
+    /**
+     * Highest entitlement `version` applied to `currentAccount.subscription`.
+     * Socket payloads carry a monotonically increasing version; writes that
+     * carry an older version than the one already applied are discarded instead
+     * of overwriting fresher data.
+     */
+    private lastAppliedSubscriptionVersion;
+    /**
+     * Logical clock counting applied socket entitlement writes. A REST refresh
+     * captures this counter before its request goes on the wire; if it advanced
+     * by the time the response arrives, a fresher socket push landed mid-flight
+     * and the REST snapshot is discarded as stale.
+     */
+    private appliedSubscriptionSocketWrites;
     constructor(config: ApiConfig);
     private handleBalanceUpdate;
     private handleChangeNetwork;
     private handleServerConnected;
     private handleServerConnecting;
     private handleServerDisconnected;
+    private mapSocketSubscriptionEntitlement;
+    /**
+     * Single chokepoint through which every subscription entitlement writer
+     * (REST refresh, socket entitlement push, socket authenticated seeding)
+     * must route.
+     *
+     * Guards against last-writer-wins races between the two transports: writes
+     * carrying an older `version` than the one already applied are discarded,
+     * and an unversioned REST snapshot whose request started before a socket
+     * push was applied is discarded as stale. Snapshots deep-equal to the
+     * current one are accepted without re-applying, so reconnect re-seeds and
+     * tab replays do not emit redundant 'updated' events.
+     *
+     * @returns `true` when the snapshot was accepted (even if identical to the
+     * current one), `false` when it was discarded as stale.
+     */
+    private applySubscriptionSnapshot;
+    private handleSubscriptionEntitlementUpdated;
     private handleSocketAuthenticated;
     private handleAuthUpdated;
     /**