@sogni-ai/sogni-protocol 1.0.0-alpha.6 → 1.0.0-alpha.7

package/manifests/generation-tools.json

@@ -165,7 +165,7 @@
                 "seedance2",
                 "seedance2-fast"
               ],
-              "description": "Video model. \"ltx23\" (default): LTX 2.3 with native audio; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"wan22\": Fast 4-step, simple motion, no audio. Default: \"ltx23\". For ordinary Seedance 2.0 video requests, use seedance2-fast by default: 720p unless Default Media Quality is Fast, which should use 480p. Use seedance2 when the user explicitly asks for 1080p / the non-standard full-quality version, or whenever a generated/uploaded video storyboard image is the Seedance reference unless the user explicitly asks for a draft or the Seedance fast model/version. Storyboard-reference Seedance requests default to High Quality: set targetResolution 720 even when Default Media Quality is Fast, unless the user explicitly asks for another named resolution such as 480p. Default Media Quality Pro alone is not an explicit 1080p request; keep default Seedance resolution at 720p unless the user asks for 1080p or another resolution. Seedance supports multimodal loose reference assets: images (up to 9), videos (up to 3), and audios (up to 3), with no more than 12 asset files total. Use @Image1/@Video1/@Audio1 style references in creative briefs when assigning roles. Assign every useful reference asset a role and prefer positive preservation constraints. If an uploaded video is the source clip to transform, upscale, enhance, restyle, or remaster, use video_to_video with controlMode=\"seedance-v2v\" instead of generate_video referenceVideoIndices."
+              "description": "Video model. \"ltx23\" (default): LTX 2.3 with native audio; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"wan22\": Fast 4-step, simple motion, no audio. Default: \"ltx23\". Seedance quality is selected only by model: use \"seedance2-fast\" when the user asks for Seedance Fast / seedance-fast / faster draft iteration, and use \"seedance2\" for the full Seedance 2.0 model, explicit non-fast/full-quality requests, 1080p/4K requests, or generated/uploaded storyboard images unless the user explicitly asks for a draft or the fast model. Do not use Default Media Quality Fast/HQ/Pro or targetResolution to represent Seedance quality. Seedance supports multimodal loose reference assets: images (up to 9), videos (up to 3), and audios (up to 3), with no more than 12 asset files total. Use @Image1/@Video1/@Audio1 style references in creative briefs when assigning roles. Assign every useful reference asset a role and prefer positive preservation constraints. If an uploaded video is the source clip to transform, upscale, enhance, restyle, or remaster, use video_to_video with controlMode=\"seedance-v2v\" instead of generate_video referenceVideoIndices."
             },
             "generateAudio": {
               "type": "boolean",
@@ -202,7 +202,7 @@
             },
             "targetResolution": {
               "type": "number",
-              "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact pixels or an output orientation. Also set for default Seedance 2.0 requests: 480 when Default Media Quality is Fast, otherwise 720, including Pro unless the user explicitly asks for 1080p or another resolution. For generated/uploaded storyboard images used as Seedance references, default to 720 even when Default Media Quality is Fast; only use 480 when the user explicitly asks for 480p. This preserves/inherits the current video shape instead of forcing landscape. Do NOT set width, height, or exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\" or \"720p landscape\", use exact width/height/aspectRatio instead."
+              "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact pixels or an output orientation. This is resolution only, not a Seedance quality tier: Seedance quality is selected by videoModel (\"seedance2\" vs \"seedance2-fast\"). Seedance 2.0 full supports 4K; Seedance Fast supports 480p/720p only. Do not set targetResolution from Default Media Quality Fast/HQ/Pro. If omitted for Seedance, the host uses the selected model default. This preserves/inherits the current video shape instead of forcing landscape. Do NOT set width, height, or exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\", \"720p landscape\", \"4K portrait\", or \"4K landscape\", use exact width/height/aspectRatio instead."
             },
             "numberOfVariations": {
               "type": "number",
@@ -531,7 +531,7 @@
             },
             "targetResolution": {
               "type": "number",
-              "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact pixels or an output orientation. This preserves the source image aspect ratio. Do NOT set width, height, or exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\" or \"720p landscape\", use exact-pixel aspectRatio instead."
+              "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact pixels or an output orientation. This preserves the source/reference aspect ratio. Do NOT set exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\", \"720p landscape\", \"4K portrait\", or \"4K landscape\", use exact-pixel aspectRatio instead."
             },
             "sourceImageIndex": {
               "type": "number",
@@ -682,7 +682,7 @@
             },
             "targetResolution": {
               "type": "number",
-              "description": "Seedance V2V only. Short-side output resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact dimensions. For Seedance V2V fast, 480p and 720p are supported; preserve the source video shape instead of forcing landscape pixels."
+              "description": "Seedance V2V only. Short-side output resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact dimensions. Seedance V2V full supports 4K; Seedance V2V fast supports 480p and 720p. Preserve the source video shape instead of forcing landscape pixels."
             },
             "sourceImageIndex": {
               "type": "number",
@@ -923,7 +923,7 @@
                 "ltx23-ia2v",
                 "ltx23-a2v"
               ],
-              "description": "Video model. \"ltx23-ia2v\" (default when image available): LTX 2.3 image+audio to video, audio-reactive with a reference image; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"ltx23-a2v\" (default when no image): LTX 2.3 audio-only to video, no image needed, creates video purely from text prompt + audio with the same quality-tier routing. \"wan-s2v\": WAN 2.2 sound-to-video, best for lip-sync with a face image, fast 4-step. \"seedance2\": Seedance 2.0 audio-reference video, 4-15s; this tool supplies the audio plus a required reference image because Seedance text+audio without image/video is unsupported. \"seedance2-fast\": Seedance 2.0 Fast (720p cap) — pick this whenever the user says \"Seedance fast\", \"seedance-fast\", or asks for 480p/720p; pick \"seedance2\" only when they explicitly request 1080p or the full Seedance variant. For Seedance audio-reference prompts, preserve exact spoken dialogue when the user supplied it, and assign @Image1/@Audio1 roles. If the user asks for speech without words, describe the vocal performance without inventing quoted dialogue. Treat lip-sync, voice cloning, and real-human reference behavior as provider-sensitive rather than guaranteed. Omit to auto-select based on whether an image is present."
+              "description": "Video model. \"ltx23-ia2v\" (default when image available): LTX 2.3 image+audio to video, audio-reactive with a reference image; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"ltx23-a2v\" (default when no image): LTX 2.3 audio-only to video, no image needed, creates video purely from text prompt + audio with the same quality-tier routing. \"wan-s2v\": WAN 2.2 sound-to-video, best for lip-sync with a face image, fast 4-step. \"seedance2\": full Seedance 2.0 audio-reference video, 4-15s; this tool supplies the audio plus a required reference image because Seedance text+audio without image/video is unsupported. \"seedance2-fast\": Seedance 2.0 Fast for faster/lower-cost iteration. Seedance quality is selected only by this model value: pick \"seedance2-fast\" when the user says Seedance Fast / seedance-fast / faster draft, and pick \"seedance2\" for full/non-fast Seedance or 1080p/4K. Do not infer the Seedance model from Default Media Quality Fast/HQ/Pro. For Seedance audio-reference prompts, preserve exact spoken dialogue when the user supplied it, and assign @Image1/@Audio1 roles. If the user asks for speech without words, describe the vocal performance without inventing quoted dialogue. Treat lip-sync, voice cloning, and real-human reference behavior as provider-sensitive rather than guaranteed. Omit to auto-select based on whether an image is present."
             },
             "generateAudio": {
               "type": "boolean",
@@ -937,7 +937,7 @@
             },
             "targetResolution": {
               "type": "number",
-              "description": "Short-side video resolution target in pixels. Use ONLY when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact pixels or an output orientation. This preserves the source/reference aspect ratio. Do NOT set exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\" or \"720p landscape\", use exact-pixel aspectRatio instead."
+              "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact pixels or an output orientation. This preserves the source/reference aspect ratio. Do NOT set exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\", \"720p landscape\", \"4K portrait\", or \"4K landscape\", use exact-pixel aspectRatio instead."
             },
             "aspectRatio": {
               "type": "string",

package/manifests/openai-tools.json

@@ -146,7 +146,7 @@
                 "seedance2",
                 "seedance2-fast"
               ],
-              "description": "Video model. \"ltx23\" (default): LTX 2.3 with native audio; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"wan22\": Fast 4-step, simple motion, no audio. Default: \"ltx23\". For ordinary Seedance 2.0 video requests, use seedance2-fast by default: 720p unless Default Media Quality is Fast, which should use 480p. Use seedance2 when the user explicitly asks for 1080p / the non-standard full-quality version, or whenever a generated/uploaded video storyboard image is the Seedance reference unless the user explicitly asks for a draft or the Seedance fast model/version. Storyboard-reference Seedance requests default to High Quality: set targetResolution 720 even when Default Media Quality is Fast, unless the user explicitly asks for another named resolution such as 480p. Default Media Quality Pro alone is not an explicit 1080p request; keep default Seedance resolution at 720p unless the user asks for 1080p or another resolution. Seedance supports multimodal loose reference assets: images (up to 9), videos (up to 3), and audios (up to 3), with no more than 12 asset files total. Use @Image1/@Video1/@Audio1 style references in creative briefs when assigning roles. Assign every useful reference asset a role and prefer positive preservation constraints. If an uploaded video is the source clip to transform, upscale, enhance, restyle, or remaster, use video_to_video with controlMode=\"seedance-v2v\" instead of generate_video referenceVideoIndices."
+              "description": "Video model. \"ltx23\" (default): LTX 2.3 with native audio; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"wan22\": Fast 4-step, simple motion, no audio. Default: \"ltx23\". Seedance quality is selected only by model: use \"seedance2-fast\" when the user asks for Seedance Fast / seedance-fast / faster draft iteration, and use \"seedance2\" for the full Seedance 2.0 model, explicit non-fast/full-quality requests, 1080p/4K requests, or generated/uploaded storyboard images unless the user explicitly asks for a draft or the fast model. Do not use Default Media Quality Fast/HQ/Pro or targetResolution to represent Seedance quality. Seedance supports multimodal loose reference assets: images (up to 9), videos (up to 3), and audios (up to 3), with no more than 12 asset files total. Use @Image1/@Video1/@Audio1 style references in creative briefs when assigning roles. Assign every useful reference asset a role and prefer positive preservation constraints. If an uploaded video is the source clip to transform, upscale, enhance, restyle, or remaster, use video_to_video with controlMode=\"seedance-v2v\" instead of generate_video referenceVideoIndices."
             },
             "generateAudio": {
               "type": "boolean",
@@ -183,7 +183,7 @@
             },
             "targetResolution": {
               "type": "number",
-              "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact pixels or an output orientation. Also set for default Seedance 2.0 requests: 480 when Default Media Quality is Fast, otherwise 720, including Pro unless the user explicitly asks for 1080p or another resolution. For generated/uploaded storyboard images used as Seedance references, default to 720 even when Default Media Quality is Fast; only use 480 when the user explicitly asks for 480p. This preserves/inherits the current video shape instead of forcing landscape. Do NOT set width, height, or exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\" or \"720p landscape\", use exact width/height/aspectRatio instead."
+              "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact pixels or an output orientation. This is resolution only, not a Seedance quality tier: Seedance quality is selected by videoModel (\"seedance2\" vs \"seedance2-fast\"). Seedance 2.0 full supports 4K; Seedance Fast supports 480p/720p only. Do not set targetResolution from Default Media Quality Fast/HQ/Pro. If omitted for Seedance, the host uses the selected model default. This preserves/inherits the current video shape instead of forcing landscape. Do NOT set width, height, or exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\", \"720p landscape\", \"4K portrait\", or \"4K landscape\", use exact width/height/aspectRatio instead."
             },
             "numberOfVariations": {
               "type": "number",
@@ -512,7 +512,7 @@
             },
             "targetResolution": {
               "type": "number",
-              "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact pixels or an output orientation. This preserves the source image aspect ratio. Do NOT set width, height, or exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\" or \"720p landscape\", use exact-pixel aspectRatio instead."
+              "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact pixels or an output orientation. This preserves the source/reference aspect ratio. Do NOT set exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\", \"720p landscape\", \"4K portrait\", or \"4K landscape\", use exact-pixel aspectRatio instead."
             },
             "sourceImageIndex": {
               "type": "number",
@@ -663,7 +663,7 @@
             },
             "targetResolution": {
               "type": "number",
-              "description": "Seedance V2V only. Short-side output resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact dimensions. For Seedance V2V fast, 480p and 720p are supported; preserve the source video shape instead of forcing landscape pixels."
+              "description": "Seedance V2V only. Short-side output resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact dimensions. Seedance V2V full supports 4K; Seedance V2V fast supports 480p and 720p. Preserve the source video shape instead of forcing landscape pixels."
             },
             "sourceImageIndex": {
               "type": "number",
@@ -904,7 +904,7 @@
                 "ltx23-ia2v",
                 "ltx23-a2v"
               ],
-              "description": "Video model. \"ltx23-ia2v\" (default when image available): LTX 2.3 image+audio to video, audio-reactive with a reference image; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"ltx23-a2v\" (default when no image): LTX 2.3 audio-only to video, no image needed, creates video purely from text prompt + audio with the same quality-tier routing. \"wan-s2v\": WAN 2.2 sound-to-video, best for lip-sync with a face image, fast 4-step. \"seedance2\": Seedance 2.0 audio-reference video, 4-15s; this tool supplies the audio plus a required reference image because Seedance text+audio without image/video is unsupported. \"seedance2-fast\": Seedance 2.0 Fast (720p cap) — pick this whenever the user says \"Seedance fast\", \"seedance-fast\", or asks for 480p/720p; pick \"seedance2\" only when they explicitly request 1080p or the full Seedance variant. For Seedance audio-reference prompts, preserve exact spoken dialogue when the user supplied it, and assign @Image1/@Audio1 roles. If the user asks for speech without words, describe the vocal performance without inventing quoted dialogue. Treat lip-sync, voice cloning, and real-human reference behavior as provider-sensitive rather than guaranteed. Omit to auto-select based on whether an image is present."
+              "description": "Video model. \"ltx23-ia2v\" (default when image available): LTX 2.3 image+audio to video, audio-reactive with a reference image; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"ltx23-a2v\" (default when no image): LTX 2.3 audio-only to video, no image needed, creates video purely from text prompt + audio with the same quality-tier routing. \"wan-s2v\": WAN 2.2 sound-to-video, best for lip-sync with a face image, fast 4-step. \"seedance2\": full Seedance 2.0 audio-reference video, 4-15s; this tool supplies the audio plus a required reference image because Seedance text+audio without image/video is unsupported. \"seedance2-fast\": Seedance 2.0 Fast for faster/lower-cost iteration. Seedance quality is selected only by this model value: pick \"seedance2-fast\" when the user says Seedance Fast / seedance-fast / faster draft, and pick \"seedance2\" for full/non-fast Seedance or 1080p/4K. Do not infer the Seedance model from Default Media Quality Fast/HQ/Pro. For Seedance audio-reference prompts, preserve exact spoken dialogue when the user supplied it, and assign @Image1/@Audio1 roles. If the user asks for speech without words, describe the vocal performance without inventing quoted dialogue. Treat lip-sync, voice cloning, and real-human reference behavior as provider-sensitive rather than guaranteed. Omit to auto-select based on whether an image is present."
             },
             "generateAudio": {
               "type": "boolean",
@@ -918,7 +918,7 @@
             },
             "targetResolution": {
               "type": "number",
-              "description": "Short-side video resolution target in pixels. Use ONLY when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact pixels or an output orientation. This preserves the source/reference aspect ratio. Do NOT set exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\" or \"720p landscape\", use exact-pixel aspectRatio instead."
+              "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact pixels or an output orientation. This preserves the source/reference aspect ratio. Do NOT set exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\", \"720p landscape\", \"4K portrait\", or \"4K landscape\", use exact-pixel aspectRatio instead."
             },
             "aspectRatio": {
               "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sogni-ai/sogni-protocol",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.7",
   "description": "Language-neutral protocol artifacts for the Sogni ecosystem: tool schemas, prompts, OpenAI tool manifests, and enums. Consumed by every Sogni SDK (TypeScript, Swift, and future Python/Kotlin/Rust SDKs) so contracts stay in lockstep across languages.",
   "keywords": [
     "sogni",

package/schemas/billing/spend-gate.schema.json

@@ -3,9 +3,8 @@
   "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/billing/spend-gate.schema.json",
   "title": "Spend gate request and state",
   "schemaVersion": "2026-05-20.1",
-  "description": "Single shared spend-approval state machine for both atomic tool calls (scope='tool_call') and workflow authorizations (scope='workflow_run'). One envelope, one state enum, one transition log. Per-job settlement remains on the sogni-socket project+N path — this gate authorizes spend, it does not move funds.",
+  "description": "Single shared spend-approval state machine for atomic tool calls (scope='tool_call'), grouped concurrent dispatches (scope='parallel_batch'), and workflow authorizations (scope='workflow_run'). One envelope, one state enum, one transition log. Per-job settlement remains on the sogni-socket project+N path — this gate authorizes spend, it does not move funds. Note: additionalProperties:false is applied per oneOf branch, not at the root — a root-level additionalProperties has no sibling properties to whitelist against and would reject every payload.",
   "type": "object",
-  "additionalProperties": false,
   "$defs": {
     "SpendGateState": {
       "type": "string",
@@ -23,12 +22,13 @@
     },
     "SpendGateDecision": {
       "type": "string",
-      "enum": ["confirm", "cancel"]
+      "description": "Decision recorded when the gate leaves waiting_for_user. Three historical vocabularies are accepted: 'confirm'/'cancel' (canonical), 'approved'/'rejected' (pre-2026-05-20 aliases still emitted by sogni-api and sogni-creative-agent durable runs), and 'cancelled' (alternate past-tense spelling collapsing to 'cancel'). Consumers normalize via normalizeSpendDecision so business logic only sees the canonical pair.",
+      "enum": ["confirm", "cancel", "approved", "rejected", "cancelled"]
     },
     "SpendEstimateLineItem": {
       "type": "object",
       "additionalProperties": false,
-      "description": "One row of the spend estimate breakdown. Sum of (units * model price) across line items yields the totalEstimatedCapacityUnits.",
+      "description": "One row of the spend estimate breakdown. Sum of (units * model price) across line items yields the estimate's capacityUnits.",
       "properties": {
         "model": { "type": "string" },
         "units": { "type": "number", "minimum": 0 },
@@ -39,13 +39,33 @@
       },
       "required": ["model", "units", "tokenType"]
     },
+    "SpendGateEstimate": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Estimate payload carried on the gate itself. capacityUnits = sum of breakdown units; tokenType = denomination the breakdown is in; maxAcceptableUnits = optional caller-supplied cap.",
+      "properties": {
+        "capacityUnits": { "type": "number", "minimum": 0 },
+        "breakdown": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/SpendEstimateLineItem" }
+        },
+        "tokenType": {
+          "type": "string",
+          "enum": ["spark", "sogni"]
+        },
+        "maxAcceptableUnits": { "type": "number", "minimum": 0 }
+      },
+      "required": ["capacityUnits", "breakdown", "tokenType"]
+    },
     "PendingToolCall": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Minimal reference to a tool call this gate covers (when scope='tool_call' the array has one entry; when scope='workflow_run' the gate authorizes the umbrella and pendingToolCalls may be empty).",
+      "description": "Minimal reference to a tool call this gate covers (when scope='tool_call' the array has one entry; when scope='parallel_batch' it carries the constituent calls of the fan-out; when scope='workflow_run' the gate authorizes the umbrella and pendingToolCalls may be empty).",
       "properties": {
         "toolCallId": { "type": "string" },
-        "toolName": { "type": "string" }
+        "toolName": { "type": "string" },
+        "estimateUnits": { "type": "number", "minimum": 0 }
       },
       "required": ["toolCallId", "toolName"]
     },
@@ -73,27 +93,39 @@
           "type": "array",
           "items": { "$ref": "#/$defs/PendingToolCall" }
         },
-        "estimate": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "totalEstimatedCapacityUnits": { "type": "number", "minimum": 0 },
-            "breakdown": {
-              "type": "array",
-              "minItems": 1,
-              "items": { "$ref": "#/$defs/SpendEstimateLineItem" }
-            },
-            "maxAcceptableUnits": { "type": "number", "minimum": 0 }
-          },
-          "required": ["totalEstimatedCapacityUnits", "breakdown"]
+        "estimate": { "$ref": "#/$defs/SpendGateEstimate" },
+        "state": { "$ref": "#/$defs/SpendGateState" },
+        "reason": { "type": "string" },
+        "decision": { "$ref": "#/$defs/SpendGateDecision" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "decidedAt": { "type": "string", "format": "date-time" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "failureReason": { "type": "string" }
+      },
+      "required": ["gateId", "scope", "toolCallId", "estimate", "state", "updatedAt"]
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gateId": { "type": "string" },
+        "runId": { "type": "string" },
+        "scope": { "const": "parallel_batch" },
+        "pendingToolCalls": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/PendingToolCall" }
         },
+        "estimate": { "$ref": "#/$defs/SpendGateEstimate" },
         "state": { "$ref": "#/$defs/SpendGateState" },
         "reason": { "type": "string" },
         "decision": { "$ref": "#/$defs/SpendGateDecision" },
+        "createdAt": { "type": "string", "format": "date-time" },
         "decidedAt": { "type": "string", "format": "date-time" },
-        "lastTransitionAt": { "type": "string", "format": "date-time" }
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "failureReason": { "type": "string" }
       },
-      "required": ["gateId", "scope", "toolCallId", "estimate", "state", "lastTransitionAt"]
+      "required": ["gateId", "scope", "pendingToolCalls", "estimate", "state", "updatedAt"]
     },
     {
       "type": "object",
@@ -104,27 +136,16 @@
         "scope": { "const": "workflow_run" },
         "workflowRunId": { "type": "string" },
         "pendingWorkflowPlan": { "$ref": "#/$defs/PendingWorkflowPlan" },
-        "estimate": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "totalEstimatedCapacityUnits": { "type": "number", "minimum": 0 },
-            "breakdown": {
-              "type": "array",
-              "minItems": 1,
-              "items": { "$ref": "#/$defs/SpendEstimateLineItem" }
-            },
-            "maxAcceptableUnits": { "type": "number", "minimum": 0 }
-          },
-          "required": ["totalEstimatedCapacityUnits", "breakdown"]
-        },
+        "estimate": { "$ref": "#/$defs/SpendGateEstimate" },
         "state": { "$ref": "#/$defs/SpendGateState" },
         "reason": { "type": "string" },
         "decision": { "$ref": "#/$defs/SpendGateDecision" },
+        "createdAt": { "type": "string", "format": "date-time" },
         "decidedAt": { "type": "string", "format": "date-time" },
-        "lastTransitionAt": { "type": "string", "format": "date-time" }
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "failureReason": { "type": "string" }
       },
-      "required": ["gateId", "scope", "workflowRunId", "estimate", "state", "lastTransitionAt"]
+      "required": ["gateId", "scope", "workflowRunId", "estimate", "state", "updatedAt"]
     }
   ]
 }

package/schemas/events/run-event.schema.json

@@ -9,10 +9,12 @@
   "$defs": {
     "RunEventType": {
       "type": "string",
-      "description": "All event types. Clusters: lifecycle (run_queued, run_started, run_completed, run_partial_failure, run_failed, run_cancelled), LLM (llm_round_started, llm_token, llm_round_completed), tools (tool_call_proposed, tool_call_dispatched, tool_call_progress, tool_call_resolved), artifacts (artifact_created, artifact_updated, artifact_referenced), waiting (run_waiting_for_user), spend (spend_preview_emitted, spend_confirmed, spend_cancelled, spend_insufficient), audit (audit_evaluated, repair_requested), workflow-stage (stage_started, stage_completed, stage_failed, stage_waiting_for_user).",
+      "description": "All event types — superset of every type emitted by any current consumer (sogni-creative-agent-v2, sogni-chat, sogni-api) plus the schema-mandated set; mirrors RUN_EVENT_TYPES in sogni-intelligence-client src/events/runEvent.ts. Clusters: lifecycle (run_created, run_queued, run_started, run_resumed, run_completed, run_partial_failure, run_failed, run_cancelled), LLM (llm_round_started, llm_token, llm_round_completed, assistant_message_delta, assistant_message_completed), tools (tool_call_proposed, tool_call_dispatched, tool_call_progress, tool_call_resolved), artifacts (artifact_created, artifact_updated, artifact_referenced), media context (media_context_updated, media_turn_intent_classified, asset_manifest_updated), waiting (run_waiting_for_user), spend/billing (billing_preview_updated, spend_gate_opened, spend_preview_emitted, spend_confirmed, spend_cancelled, spend_insufficient, run_awaiting_cost_confirmation, run_cost_confirmation_resolved), workflow-stage (stage_started, stage_completed, stage_failed, stage_waiting_for_user), audit (audit_evaluated, repair_requested).",
       "enum": [
+        "run_created",
         "run_queued",
         "run_started",
+        "run_resumed",
         "run_completed",
         "run_partial_failure",
         "run_failed",
@@ -20,6 +22,8 @@
         "llm_round_started",
         "llm_token",
         "llm_round_completed",
+        "assistant_message_delta",
+        "assistant_message_completed",
         "tool_call_proposed",
         "tool_call_dispatched",
         "tool_call_progress",
@@ -27,17 +31,24 @@
         "artifact_created",
         "artifact_updated",
         "artifact_referenced",
+        "media_context_updated",
+        "media_turn_intent_classified",
+        "asset_manifest_updated",
         "run_waiting_for_user",
+        "billing_preview_updated",
+        "spend_gate_opened",
         "spend_preview_emitted",
         "spend_confirmed",
         "spend_cancelled",
         "spend_insufficient",
-        "audit_evaluated",
-        "repair_requested",
+        "run_awaiting_cost_confirmation",
+        "run_cost_confirmation_resolved",
         "stage_started",
         "stage_completed",
         "stage_failed",
-        "stage_waiting_for_user"
+        "stage_waiting_for_user",
+        "audit_evaluated",
+        "repair_requested"
       ]
     },
     "RunStatus": {
@@ -71,8 +82,8 @@
     "runId": { "type": "string" },
     "runKind": {
       "type": "string",
-      "enum": ["chat", "workflow"],
-      "description": "Substrate discriminator (plan §13.5). chat and workflow runs share persistence, lease, heartbeat, event log, waiting semantics, cancellation, cost confirmation, and resume."
+      "enum": ["chat", "workflow", "tool_batch"],
+      "description": "Substrate discriminator (plan §13.5). chat and workflow runs share persistence, lease, heartbeat, event log, waiting semantics, cancellation, cost confirmation, and resume. tool_batch is used by sogni-creative-agent-v2 for fan-out tool-call runs that share the same event substrate without being a full chat or workflow run."
     },
     "sequence": {
       "type": "integer",

package/schemas/tools/animate_photo.schema.json

@@ -37,7 +37,7 @@
     },
     "targetResolution": {
       "type": "number",
-      "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact pixels or an output orientation. This preserves the source image aspect ratio. Do NOT set width, height, or exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\" or \"720p landscape\", use exact-pixel aspectRatio instead."
+      "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact pixels or an output orientation. This preserves the source/reference aspect ratio. Do NOT set exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\", \"720p landscape\", \"4K portrait\", or \"4K landscape\", use exact-pixel aspectRatio instead."
     },
     "sourceImageIndex": {
       "type": "number",

package/schemas/tools/generate_video.schema.json

@@ -37,7 +37,7 @@
         "seedance2",
         "seedance2-fast"
       ],
-      "description": "Video model. \"ltx23\" (default): LTX 2.3 with native audio; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"wan22\": Fast 4-step, simple motion, no audio. Default: \"ltx23\". For ordinary Seedance 2.0 video requests, use seedance2-fast by default: 720p unless Default Media Quality is Fast, which should use 480p. Use seedance2 when the user explicitly asks for 1080p / the non-standard full-quality version, or whenever a generated/uploaded video storyboard image is the Seedance reference unless the user explicitly asks for a draft or the Seedance fast model/version. Storyboard-reference Seedance requests default to High Quality: set targetResolution 720 even when Default Media Quality is Fast, unless the user explicitly asks for another named resolution such as 480p. Default Media Quality Pro alone is not an explicit 1080p request; keep default Seedance resolution at 720p unless the user asks for 1080p or another resolution. Seedance supports multimodal loose reference assets: images (up to 9), videos (up to 3), and audios (up to 3), with no more than 12 asset files total. Use @Image1/@Video1/@Audio1 style references in creative briefs when assigning roles. Assign every useful reference asset a role and prefer positive preservation constraints. If an uploaded video is the source clip to transform, upscale, enhance, restyle, or remaster, use video_to_video with controlMode=\"seedance-v2v\" instead of generate_video referenceVideoIndices."
+      "description": "Video model. \"ltx23\" (default): LTX 2.3 with native audio; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"wan22\": Fast 4-step, simple motion, no audio. Default: \"ltx23\". Seedance quality is selected only by model: use \"seedance2-fast\" when the user asks for Seedance Fast / seedance-fast / faster draft iteration, and use \"seedance2\" for the full Seedance 2.0 model, explicit non-fast/full-quality requests, 1080p/4K requests, or generated/uploaded storyboard images unless the user explicitly asks for a draft or the fast model. Do not use Default Media Quality Fast/HQ/Pro or targetResolution to represent Seedance quality. Seedance supports multimodal loose reference assets: images (up to 9), videos (up to 3), and audios (up to 3), with no more than 12 asset files total. Use @Image1/@Video1/@Audio1 style references in creative briefs when assigning roles. Assign every useful reference asset a role and prefer positive preservation constraints. If an uploaded video is the source clip to transform, upscale, enhance, restyle, or remaster, use video_to_video with controlMode=\"seedance-v2v\" instead of generate_video referenceVideoIndices."
     },
     "generateAudio": {
       "type": "boolean",
@@ -74,7 +74,7 @@
     },
     "targetResolution": {
       "type": "number",
-      "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact pixels or an output orientation. Also set for default Seedance 2.0 requests: 480 when Default Media Quality is Fast, otherwise 720, including Pro unless the user explicitly asks for 1080p or another resolution. For generated/uploaded storyboard images used as Seedance references, default to 720 even when Default Media Quality is Fast; only use 480 when the user explicitly asks for 480p. This preserves/inherits the current video shape instead of forcing landscape. Do NOT set width, height, or exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\" or \"720p landscape\", use exact width/height/aspectRatio instead."
+      "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact pixels or an output orientation. This is resolution only, not a Seedance quality tier: Seedance quality is selected by videoModel (\"seedance2\" vs \"seedance2-fast\"). Seedance 2.0 full supports 4K; Seedance Fast supports 480p/720p only. Do not set targetResolution from Default Media Quality Fast/HQ/Pro. If omitted for Seedance, the host uses the selected model default. This preserves/inherits the current video shape instead of forcing landscape. Do NOT set width, height, or exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\", \"720p landscape\", \"4K portrait\", or \"4K landscape\", use exact width/height/aspectRatio instead."
     },
     "numberOfVariations": {
       "type": "number",

package/schemas/tools/sound_to_video.schema.json

@@ -43,7 +43,7 @@
         "ltx23-ia2v",
         "ltx23-a2v"
       ],
-      "description": "Video model. \"ltx23-ia2v\" (default when image available): LTX 2.3 image+audio to video, audio-reactive with a reference image; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"ltx23-a2v\" (default when no image): LTX 2.3 audio-only to video, no image needed, creates video purely from text prompt + audio with the same quality-tier routing. \"wan-s2v\": WAN 2.2 sound-to-video, best for lip-sync with a face image, fast 4-step. \"seedance2\": Seedance 2.0 audio-reference video, 4-15s; this tool supplies the audio plus a required reference image because Seedance text+audio without image/video is unsupported. \"seedance2-fast\": Seedance 2.0 Fast (720p cap) — pick this whenever the user says \"Seedance fast\", \"seedance-fast\", or asks for 480p/720p; pick \"seedance2\" only when they explicitly request 1080p or the full Seedance variant. For Seedance audio-reference prompts, preserve exact spoken dialogue when the user supplied it, and assign @Image1/@Audio1 roles. If the user asks for speech without words, describe the vocal performance without inventing quoted dialogue. Treat lip-sync, voice cloning, and real-human reference behavior as provider-sensitive rather than guaranteed. Omit to auto-select based on whether an image is present."
+      "description": "Video model. \"ltx23-ia2v\" (default when image available): LTX 2.3 image+audio to video, audio-reactive with a reference image; Fast/HQ use the distilled 8-step worker and Default Media Quality Pro uses the non-distilled dev worker. \"ltx23-a2v\" (default when no image): LTX 2.3 audio-only to video, no image needed, creates video purely from text prompt + audio with the same quality-tier routing. \"wan-s2v\": WAN 2.2 sound-to-video, best for lip-sync with a face image, fast 4-step. \"seedance2\": full Seedance 2.0 audio-reference video, 4-15s; this tool supplies the audio plus a required reference image because Seedance text+audio without image/video is unsupported. \"seedance2-fast\": Seedance 2.0 Fast for faster/lower-cost iteration. Seedance quality is selected only by this model value: pick \"seedance2-fast\" when the user says Seedance Fast / seedance-fast / faster draft, and pick \"seedance2\" for full/non-fast Seedance or 1080p/4K. Do not infer the Seedance model from Default Media Quality Fast/HQ/Pro. For Seedance audio-reference prompts, preserve exact spoken dialogue when the user supplied it, and assign @Image1/@Audio1 roles. If the user asks for speech without words, describe the vocal performance without inventing quoted dialogue. Treat lip-sync, voice cloning, and real-human reference behavior as provider-sensitive rather than guaranteed. Omit to auto-select based on whether an image is present."
     },
     "generateAudio": {
       "type": "boolean",
@@ -57,7 +57,7 @@
     },
     "targetResolution": {
       "type": "number",
-      "description": "Short-side video resolution target in pixels. Use ONLY when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact pixels or an output orientation. This preserves the source/reference aspect ratio. Do NOT set exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\" or \"720p landscape\", use exact-pixel aspectRatio instead."
+      "description": "Short-side video resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact pixels or an output orientation. This preserves the source/reference aspect ratio. Do NOT set exact-pixel aspectRatio for bare named resolution requests. If the user says \"720p portrait\", \"720p landscape\", \"4K portrait\", or \"4K landscape\", use exact-pixel aspectRatio instead."
     },
     "aspectRatio": {
       "type": "string",

package/schemas/tools/video_to_video.schema.json

@@ -52,7 +52,7 @@
     },
     "targetResolution": {
       "type": "number",
-      "description": "Seedance V2V only. Short-side output resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", or \"1080p\" without exact dimensions. For Seedance V2V fast, 480p and 720p are supported; preserve the source video shape instead of forcing landscape pixels."
+      "description": "Seedance V2V only. Short-side output resolution target in pixels. Use when the user asks for a bare named resolution such as \"480p\", \"720p\", \"1080p\", \"2160p\", or \"4K\" without exact dimensions. Seedance V2V full supports 4K; Seedance V2V fast supports 480p and 720p. Preserve the source video shape instead of forcing landscape pixels."
     },
     "sourceImageIndex": {
       "type": "number",

package/version.json

@@ -1,4 +1,4 @@
 {
-  "protocolVersion": "1.2.1",
+  "protocolVersion": "1.2.2",
   "description": "Sogni protocol artifact version. SDKs may refuse to operate against a protocolVersion they were not built for. Bump the major when removing or renaming any schema / enum / manifest field; bump the minor when adding new optional fields or new tools; bump the patch for description / prose changes only."
 }