@sogni-ai/sogni-client 4.2.0-alpha.2 → 4.2.0-alpha.21

package/CHANGELOG.md

@@ -1,3 +1,151 @@
+# [4.2.0-alpha.21](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.20...v4.2.0-alpha.21) (2026-05-14)
+
+
+### Bug Fixes
+
+* **chat:** align hosted creative tool surfaces ([6e9e094](https://github.com/Sogni-AI/sogni-client/commit/6e9e094803bad7fdda994103f12bd40f726ae08e))
+
+
+### Features
+
+* **chat:** expose hosted completions wrapper ([da3799d](https://github.com/Sogni-AI/sogni-client/commit/da3799d2e99877d4bdd1990741611bac6243cdad))
+
+# [4.2.0-alpha.20](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.19...v4.2.0-alpha.20) (2026-05-12)
+
+
+### Features
+
+* **sdk:** add socket event subscription controls ([a450acd](https://github.com/Sogni-AI/sogni-client/commit/a450acd22087a690657c82de8e20cda96cd81512))
+
+# [4.2.0-alpha.19](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.18...v4.2.0-alpha.19) (2026-05-11)
+
+
+### Features
+
+* **sdk:** re-export ChatResponseFormat type from package root ([b48849c](https://github.com/Sogni-AI/sogni-client/commit/b48849c517375d7879d55653398a65f0d93f161c))
+
+# [4.2.0-alpha.18](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.17...v4.2.0-alpha.18) (2026-05-09)
+
+
+### Bug Fixes
+
+* **examples:** prepare sound-to-video audio uploads ([52e6cc2](https://github.com/Sogni-AI/sogni-client/commit/52e6cc210e67da49742229a9d1ff2d0edd5e14fa))
+
+# [4.2.0-alpha.17](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.16...v4.2.0-alpha.17) (2026-05-09)
+
+
+### Features
+
+* **alpha:** merge agentic harness refactor ([e4e1ddc](https://github.com/Sogni-AI/sogni-client/commit/e4e1ddcc4b1cd1272ed7ccc8c4b68ee5a9f7df8c))
+* **chat:** plumb response_format through createCompletion ([b711a68](https://github.com/Sogni-AI/sogni-client/commit/b711a68e4dc7fc27d8d781f8cab40f74b23393eb))
+
+# [4.2.0-alpha.16](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.15...v4.2.0-alpha.16) (2026-05-06)
+
+
+### Bug Fixes
+
+* **client:** preserve external job progress ([6390c16](https://github.com/Sogni-AI/sogni-client/commit/6390c165b9c492b8fa0df07b331cb6193c8b3916))
+
+# [4.2.0-alpha.15](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.14...v4.2.0-alpha.15) (2026-05-04)
+
+
+### Bug Fixes
+
+* update gpt-image-2 hosted tool guidance ([e346969](https://github.com/Sogni-AI/sogni-client/commit/e346969d8898d5a78ffd026bb0f2839a68366428))
+
+# [4.2.0-alpha.14](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.13...v4.2.0-alpha.14) (2026-05-04)
+
+
+### Features
+
+* **chat:** update creative workflow client metadata ([bda4a28](https://github.com/Sogni-AI/sogni-client/commit/bda4a28a78dcce41c4bf0fd796767019f8d69ce8))
+
+# [4.2.0-alpha.13](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.12...v4.2.0-alpha.13) (2026-05-04)
+
+
+### Features
+
+* **client:** expose GPT Image 2 project options ([5f8ff31](https://github.com/Sogni-AI/sogni-client/commit/5f8ff31d147c6869b9d7a238a45b117fee80fea1))
+* **client:** route GPT Image 2 aliases ([a946fe2](https://github.com/Sogni-AI/sogni-client/commit/a946fe2ae556a1d9d788d3bc0c3c7c0e223996f1))
+
+# [4.2.0-alpha.12](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.11...v4.2.0-alpha.12) (2026-05-03)
+
+
+### Bug Fixes
+
+* align Seedance routing and estimates ([93c3315](https://github.com/Sogni-AI/sogni-client/commit/93c3315352b014ce04583bbf7342691f4b88b63f))
+
+# [4.2.0-alpha.11](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.10...v4.2.0-alpha.11) (2026-05-01)
+
+
+### Bug Fixes
+
+* document monthly free Spark credits ([9a89533](https://github.com/Sogni-AI/sogni-client/commit/9a89533d3c12d05eec8b2ddf61b654879fcef243))
+
+# [4.2.0-alpha.10](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.9...v4.2.0-alpha.10) (2026-05-01)
+
+
+### Features
+
+* **seedance:** add guided partner video workflow ([36b8880](https://github.com/Sogni-AI/sogni-client/commit/36b8880f6fd33e3cfc7eeb0a828a2f3663c57996))
+
+# [4.2.0-alpha.9](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.8...v4.2.0-alpha.9) (2026-04-30)
+
+
+### Bug Fixes
+
+* **seedance:** omit negative prompt in example workflow ([07a0973](https://github.com/Sogni-AI/sogni-client/commit/07a0973dfebd44b082ebc3b6883fd21b1761d576))
+
+# [4.2.0-alpha.8](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.7...v4.2.0-alpha.8) (2026-04-30)
+
+
+### Bug Fixes
+
+* **projects:** share negative prompt params ([9545e95](https://github.com/Sogni-AI/sogni-client/commit/9545e956ccedecff499d00e8ad02b8c877aacf11))
+
+
+### Features
+
+* **seedance:** support multimodal context references ([4f1a0ec](https://github.com/Sogni-AI/sogni-client/commit/4f1a0ecfbb958bfc8f5d4e2e43f79fee718314dc))
+
+# [4.2.0-alpha.7](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.6...v4.2.0-alpha.7) (2026-04-30)
+
+
+### Bug Fixes
+
+* align Seedance video tool handling ([337af3a](https://github.com/Sogni-AI/sogni-client/commit/337af3ad0aaf9e0ddc15d6f01c4f235691806e71))
+
+# [4.2.0-alpha.6](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.5...v4.2.0-alpha.6) (2026-04-30)
+
+
+### Features
+
+* centralize chat model routing ([51a0841](https://github.com/Sogni-AI/sogni-client/commit/51a084119966fa2239512fdad1e2b549b83bd098))
+* **chat:** align hosted tool routing helpers ([bf57eca](https://github.com/Sogni-AI/sogni-client/commit/bf57eca06e255429dd43a4e2614006be774967f3))
+* **chat:** expose server-side Sogni tool controls ([7218ee7](https://github.com/Sogni-AI/sogni-client/commit/7218ee7f7cd11b85e2f3c7c1dd42fc68c89734bf))
+* generate hosted chat tool definitions ([2e56f57](https://github.com/Sogni-AI/sogni-client/commit/2e56f57a9f1acb72ce6c2d4744edaa291fc19582))
+
+# [4.2.0-alpha.5](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.4...v4.2.0-alpha.5) (2026-04-22)
+
+
+### Bug Fixes
+
+* validate inline media inputs for tools and vision requests ([c4bd7c1](https://github.com/Sogni-AI/sogni-client/commit/c4bd7c15cd530896065cf5ed41cd280b5db63938))
+
+# [4.2.0-alpha.4](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.3...v4.2.0-alpha.4) (2026-04-22)
+
+
+### Features
+
+* expand chat sogni media tools ([fb0d6c7](https://github.com/Sogni-AI/sogni-client/commit/fb0d6c77e4b73fbbe57d8b64b4a37bb610eb8c68))
+
+# [4.2.0-alpha.3](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.2...v4.2.0-alpha.3) (2026-04-20)
+
+
+### Bug Fixes
+
+* use thinkingComplexDefault in LLMModelInfo cost estimates ([162011f](https://github.com/Sogni-AI/sogni-client/commit/162011f698b56229629cea8d09fad1b3e313294f))
+
 # [4.2.0-alpha.2](https://github.com/Sogni-AI/sogni-client/compare/v4.2.0-alpha.1...v4.2.0-alpha.2) (2026-04-20)
 
 

package/CLAUDE.md

@@ -13,9 +13,31 @@ For AI coding assistants working with this SDK, the following resources are avai
 
 When helping users with Sogni SDK tasks, consult `llms-full.txt` for complete parameter references, especially for video generation where WAN 2.2 and LTX-2.3 models have different behaviors.
 
+## Creative Agent Shared Contracts
+
+Hosted chat tools, creative-agent workflow helpers, generated tool manifests, and SDK-facing workflow docs should stay aligned with `../sogni-creative-agent`. Do not recreate chat-only or SDK-only regex guardrails for tool argument repair, storyboard planning, or workflow routing. Add reusable JSON schemas, typed repair/control semantics, and deterministic validation to the shared package first, then regenerate or copy the public SDK artifacts as appropriate.
+
+Use secondary LLM calls for semantic planning, creative adaptation, and audit/repair workflows, not as a substitute for schema validation of tool arguments or structured workflow control.
+
+When SDK examples or generated helpers expose hosted creative workflows, keep them generated from or aligned with shared `@sogni/creative-agent` contracts such as `compileCreativeWorkflowPlanToHostedSequence()`, `validateAndNormalizeHostedToolArguments()`, `getRepairControlDecision()`, and `summarizeGuardTelemetry()`.
+
+### Shared `@sogni/creative-agent` contracts
+
+`@sogni/creative-agent` ships several surfaces SDK consumers can import directly when implementing creative workflows:
+
+- **Per-turn tool gating**: the chat-side skill loader (`load_skill` / `unload_skill` / `list_active_skills`) was retired on 2026-05-10. Tool-surface composition is now owned by Structured Contracts v1 (see next bullet). SDK consumers building their own agent loop should construct a `ContractRegistry` and call `classifyTurn` / `compileToolsForTurn` / `dispatchToolCall` instead of advertising load/unload tools to the model. (The read-only `*_SKILL` manifest metadata used by the public Anthropic-style skill artifact is **not** a `@sogni/creative-agent` package export — it ships separately via `@sogni-ai/sogni-creative-agent-skill`.)
+- **Structured Contracts v1**: `ContractRegistry`, `ToolGatingPolicy`, `RepairRecipe`, `PromptContract`, `classifyTurn`, `compileToolsForTurn`, `dispatchToolCall`, plus the `ContractsTelemetrySink` event types. The chat product seeds a registry once per session and the three evaluators own visible-tool composition, repair-on-error, and prompt-bake.
+- **Asset manifest**: `createAssetManifest`, `addAsset`, `mapAssetsForModel`, `validateAssetReferences`, `formatModelRef` — three-layer asset references (`asset_id` / `user_label` / `model_ref`) so SDK consumers don't hand-format Seedance `@Image1` / GPT-Image-2 `[Image 1]` / LTX-2.3 `context_image_0` tokens.
+- **Storyboard adapters**: `compileForModel`, `storyboardAdapterRegistry`, `SEEDANCE_ADAPTER`, `GPT_IMAGE_2_ADAPTER`, `LTX23_ADAPTER`, `WAN_ADAPTER`. Resolution is liberal (`seedance2-fast` → seedance via prefix).
+- **Tool envelope**: `ToolResult`, `toolOk`, `toolErr`, `isToolResultOk`, `isToolResultErr`, `mapLegacyToolErrorCategory`, plus the canonical `ToolErrorCode` taxonomy.
+- **Constrained decoding (`response_format`)**: llama-server natively accepts OpenAI-standard `{ type: "json_schema", json_schema: { strict, schema } }`. Plumbed through `src/Chat/index.ts` and forwarded to the worker via `sogni-socket` (commit `b711a68`); the `ChatResponseFormat` type is re-exported from the SDK root for typed consumer usage.
+- **Default contract data**: `populateContractsDefaults(registry)` seeds a `ContractRegistry` with the canonical Phase 3 gating policies (7), Phase 4 repair recipes (157 across 11 `(toolName, ToolErrorCode)` families), and Phase 5 per-tool prompt contracts (12). SDK consumers calling `classifyTurn` / `compileToolsForTurn` / `dispatchToolCall` should seed off this one call instead of registering policies / recipes / contracts manually.
+- **Per-tool cost + permission**: `getToolCostMetadata(toolName)` returns `{ costClass, riskLevel, userVisibleCost, description }`; `getToolPermission(toolName)` returns the typed `ToolPermissionDecision` (`allow` / `require_user_approval` / `require_explicit_intent`). SDK consumers can use these for client-side billing UX or for enforcing destructive-tool gates in their own agent loop (chat + hosted both enforce `require_explicit_intent` via shared `EXPLICIT_INTENT_PATTERNS`).
+- **Replay record schema**: `RunRecord` (schema v2; `skills_loaded` dropped after the 2026-05-10 skill-loader retirement), `redactRunRecord`, `emptyRunRecord`, plus the canonical `RunRecordToolCall` / `RunRecordToolResult` / `RunRecordRound` / `RunRecordAuditResult` shapes. SDK consumers that emit their own RunRecord (instead of relying on sogni-chat) should call `redactRunRecord` defense-in-depth before persisting / posting. The chat product writes records to sogni-api's `POST /v1/replay/records` ingest endpoint; SDK consumers can POST the same shape to the same endpoint with their api-key auth.
+
 ## 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, etc.), video generation (WAN 2.2 and LTX-2.3 models), audio generation (ACE-Step 1.5), LLM chat with tool calling, and multimodal vision chat (Qwen3.5 VLM) via WebSocket communication.
+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, etc.), video generation (WAN 2.2 and LTX-2.3 models), audio generation (ACE-Step 1.5), LLM chat with tool calling, and multimodal vision chat (Qwen3.6 35B VLM, default `qwen3.6-35b-a3b-gguf-iq4xs`) via WebSocket communication.
 
 ## Build & Development Commands
 
@@ -224,7 +246,7 @@ The SDK receives `LLMModelInfo` per model including `maxContextLength`, `maxOutp
 
 **Caution**: `maxContextLength` from the server may not reflect the actual per-request limit on the worker (see sogni-socket and sogni-llm-nvidia CLAUDE.md for the llama-server `--parallel` slot division issue).
 
-### Thinking Models (Qwen3/3.5) — `chat_template_kwargs`
+### Thinking Models (Qwen3.x) — `chat_template_kwargs`
 
 Thinking mode is controlled via llama.cpp's `chat_template_kwargs: { enable_thinking }` per-request parameter. The SDK's `think` param maps to this:
 - `think: false` → `chat_template_kwargs: { enable_thinking: false }` (no thinking)
@@ -233,7 +255,7 @@ Thinking mode is controlled via llama.cpp's `chat_template_kwargs: { enable_thin
 
 The llama-server should run with default `--reasoning-budget -1` (unrestricted) so per-request control works.
 
-Qwen3/3.5 models generate thinking output in a separate `reasoning_content` field (OpenAI-compatible). The LLM worker wraps this in `<think>` tags inside `content` for the SDK. The SDK's `ChatCompletionChunk` type has NO `reasoning_content` field — only `content` and `tool_calls`.
+Qwen3.x models generate thinking output in a separate `reasoning_content` field (OpenAI-compatible). The LLM worker wraps this in `<think>` tags inside `content` for the SDK. The SDK's `ChatCompletionChunk` type has NO `reasoning_content` field — only `content` and `tool_calls`.
 
 **The solution for structured output**: Use **tool calling** (`tools` + `tool_choice: 'required'`). Tool call arguments are always forwarded by the worker regardless of thinking mode. The `workflow_text_chat_sogni_tools.mjs` example uses this pattern for all composition pipelines (video/image/audio prompt engineering).