@sogni-ai/sogni-protocol 1.0.0-alpha.10

package/schemas/billing/workflow-authorization.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/billing/workflow-authorization.schema.json",
+  "title": "Workflow authorization ticket",
+  "schemaVersion": "2026-05-20.1",
+  "description": "Umbrella authorization ticket recorded once at workflow run start. The executor consults it before dispatching each stage and pauses for re-authorization if cumulative settled + reserved + next-estimate would exceed authorizedCapacityUnits. Per-job settlement continues through the existing sogni-socket 'project + N identical jobs' path; the workflow layer is an authorization umbrella, not a new transaction ledger.",
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "StageSettlementStatus": {
+      "type": "string",
+      "enum": ["pending", "in_flight", "settled", "failed", "cancelled"]
+    },
+    "StageSettlement": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Per-stage ledger row. estimatedUnits comes from the WorkflowCostPreview; settledUnits is filled in as the sogni-socket worker(s) for this stage finish.",
+      "properties": {
+        "stageId": { "type": "string" },
+        "projectId": {
+          "type": "string",
+          "description": "sogni-socket project id. Null until dispatched."
+        },
+        "jobIds": {
+          "type": "array",
+          "description": "sogni-socket job ids. Empty until dispatched. May have multiple entries for fan-out stages.",
+          "items": { "type": "string" }
+        },
+        "estimatedUnits": { "type": "number", "minimum": 0 },
+        "settledUnits": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Cumulative settled units for this stage. Null until at least one worker completes."
+        },
+        "status": { "$ref": "#/$defs/StageSettlementStatus" }
+      },
+      "required": ["stageId", "estimatedUnits", "status"]
+    }
+  },
+  "properties": {
+    "workflowRunId": { "type": "string" },
+    "authorizedCapacityUnits": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Umbrella cap. Per-job settlements stay within this; if next dispatch would exceed by more than the documented drift tolerance the run pauses for re-authorization."
+    },
+    "tokenType": {
+      "type": "string",
+      "enum": ["spark", "sogni"]
+    },
+    "authorizedAt": { "type": "string", "format": "date-time" },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Past expiry, the run pauses with cost_approval_required for re-authorization. Template declares an expected duration; expiry is duration + retry grace."
+    },
+    "cumulativeSettledUnits": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Sum of stageSettlements[].settledUnits to date."
+    },
+    "cumulativeReservedUnits": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Estimated units for in-flight jobs not yet settled."
+    },
+    "stageSettlements": {
+      "type": "array",
+      "description": "Per-stage ledger. May be empty pre-dispatch; populated as the executor dispatches each stage.",
+      "items": { "$ref": "#/$defs/StageSettlement" }
+    }
+  },
+  "required": [
+    "workflowRunId",
+    "authorizedCapacityUnits",
+    "tokenType",
+    "authorizedAt",
+    "expiresAt",
+    "cumulativeSettledUnits",
+    "cumulativeReservedUnits",
+    "stageSettlements"
+  ]
+}

package/schemas/errors/error.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/errors/error.schema.json",
+  "title": "Creative agent error",
+  "schemaVersion": "2026-04-27.1",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "code": { "type": "string" },
+    "message": { "type": "string" },
+    "classification": {
+      "type": "string",
+      "enum": ["validation", "auth", "billing", "rate_limit", "transient", "provider", "policy", "cancelled", "unknown"]
+    },
+    "retryable": { "type": "boolean" },
+    "toolName": { "type": "string" },
+    "stepId": { "type": "string" },
+    "details": { "type": "object", "additionalProperties": true }
+  },
+  "required": ["code", "message", "classification", "retryable"]
+}

package/schemas/errors/repair-control.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/errors/repair-control.schema.json",
+  "title": "Creative agent repair control payload",
+  "schemaVersion": "2026-04-27.1",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "error": { "type": "string" },
+    "message": { "type": "string" },
+    "controlAction": {
+      "type": "string",
+      "enum": ["execute_tool", "wait_for_user", "finish_response", "none"]
+    },
+    "retryPolicy": {
+      "type": "string",
+      "enum": [
+        "auto_tool_call",
+        "auto",
+        "auto_repair",
+        "llm_repair",
+        "manual_ui_only",
+        "manual_user_confirmation",
+        "none",
+        "no_retry",
+        "terminal"
+      ]
+    },
+    "requiredTool": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]{1,40}$"
+    },
+    "suggestedArgs": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "nextAction": { "type": "string" }
+  },
+  "required": ["controlAction"]
+}

package/schemas/events/artifact-reference.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/events/artifact-reference.schema.json",
+  "title": "Creative agent artifact reference",
+  "schemaVersion": "2026-04-27.1",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string" },
+    "kind": { "type": "string", "enum": ["image", "video", "audio", "archive", "json", "text", "other"] },
+    "url": { "type": "string" },
+    "mimeType": { "type": "string" },
+    "width": { "type": "number" },
+    "height": { "type": "number" },
+    "durationSeconds": { "type": "number" },
+    "sizeBytes": { "type": "number" },
+    "toolName": { "type": "string" },
+    "stepId": { "type": "string" },
+    "metadata": { "type": "object", "additionalProperties": true }
+  },
+  "required": ["id", "kind", "url"]
+}

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

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/events/progress-event.schema.json",
+  "title": "Creative agent progress event",
+  "schemaVersion": "2026-04-27.1",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string" },
+    "workflowId": { "type": "string" },
+    "stepId": { "type": "string" },
+    "sequence": { "type": "integer", "minimum": 0 },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "type": {
+      "type": "string",
+      "enum": ["started", "progress", "completed", "error", "artifact", "tool_call", "llm_request", "cancelled", "custom"]
+    },
+    "toolName": { "type": "string" },
+    "progress": { "type": "number", "minimum": 0, "maximum": 1 },
+    "message": { "type": "string" },
+    "artifacts": {
+      "type": "array",
+      "items": { "type": "object", "additionalProperties": true }
+    },
+    "data": { "type": "object", "additionalProperties": true }
+  },
+  "required": ["id", "workflowId", "sequence", "timestamp", "type"]
+}

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

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/events/run-event.schema.json",
+  "title": "Unified run event",
+  "schemaVersion": "2026-05-20.1",
+  "description": "Single event vocabulary across chat runs and workflow runs. Both persist into the shared `runs` substrate (plan §13.5) and differ only by the runKind discriminator. SSE replay key is (runId, sequence). idempotencyKey covers reentrant transitions such as cost confirmation. Per-event-type payload shapes are deliberately not enforced at this layer — payload shapes are documented per type and tightened in a Phase 1 follow-up to avoid an enormous union in this round.",
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "RunEventType": {
+      "type": "string",
+      "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",
+        "run_cancelled",
+        "llm_round_started",
+        "llm_token",
+        "llm_round_completed",
+        "assistant_message_delta",
+        "assistant_message_completed",
+        "tool_call_proposed",
+        "tool_call_dispatched",
+        "tool_call_progress",
+        "tool_call_resolved",
+        "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",
+        "run_awaiting_cost_confirmation",
+        "run_cost_confirmation_resolved",
+        "stage_started",
+        "stage_completed",
+        "stage_failed",
+        "stage_waiting_for_user",
+        "audit_evaluated",
+        "repair_requested"
+      ]
+    },
+    "RunStatus": {
+      "type": "string",
+      "description": "Unified status enum across chat and workflow runs.",
+      "enum": [
+        "queued",
+        "running",
+        "completed",
+        "partial_failure",
+        "waiting_for_user",
+        "failed",
+        "cancelled"
+      ]
+    },
+    "WaitingReason": {
+      "type": "string",
+      "description": "Why a run paused. Carried inside the payload of a run_waiting_for_user event (and stage_waiting_for_user where applicable).",
+      "enum": [
+        "ask_clarifying_question",
+        "select_media_required",
+        "cost_approval_required",
+        "safety_review_required",
+        "workflow_user_input_required",
+        "insufficient_credit",
+        "other"
+      ]
+    }
+  },
+  "properties": {
+    "runId": { "type": "string" },
+    "runKind": {
+      "type": "string",
+      "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",
+      "minimum": 0,
+      "description": "Strictly increasing per runId. SSE replay key is (runId, sequence)."
+    },
+    "type": { "$ref": "#/$defs/RunEventType" },
+    "status": { "$ref": "#/$defs/RunStatus" },
+    "payload": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Per-type payload. Documented shapes: run_waiting_for_user -> { reason: WaitingReason, ... }; tool_call_proposed/_dispatched/_progress/_resolved -> { toolCallId, toolName, ... }; artifact_* -> { artifactId, ... }; spend_* -> { gateId, scope, ... }; audit_evaluated -> { toolCallId, passed, ... }; repair_requested -> { toolCallId, reason, retryCount }; stage_* -> { stageId, ... }. Schema-level enforcement of these shapes is intentionally deferred to Phase 1 to avoid an unwieldy union here."
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "resumable": {
+      "type": "boolean",
+      "description": "True when the run is in a state the client can resume from (typically paired with run_waiting_for_user)."
+    },
+    "terminal": {
+      "type": "boolean",
+      "description": "True for the final event of a run (run_completed / run_failed / run_cancelled / run_partial_failure)."
+    },
+    "idempotencyKey": {
+      "type": "string",
+      "description": "Stable key for reentrant transitions (e.g. POST /confirm-cost). Re-submitting the same key MUST be a no-op."
+    }
+  },
+  "required": [
+    "runId",
+    "runKind",
+    "sequence",
+    "type",
+    "payload",
+    "createdAt"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/events/workflow-event.schema.json",
+  "title": "Creative agent workflow event",
+  "schemaVersion": "2026-04-27.1",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string" },
+    "workflowId": { "type": "string" },
+    "sequence": { "type": "integer", "minimum": 0 },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "type": {
+      "type": "string",
+      "enum": ["workflow_started", "workflow_progress", "workflow_completed", "workflow_failed", "workflow_cancelled", "workflow_waiting_for_user", "step_started", "step_completed", "step_failed", "step_waiting_for_user", "artifact_created", "custom"]
+    },
+    "status": { "type": "string", "enum": ["queued", "running", "completed", "partial_failure", "waiting_for_user", "failed", "cancelled"] },
+    "message": { "type": "string" },
+    "data": { "type": "object", "additionalProperties": true }
+  },
+  "required": ["id", "workflowId", "sequence", "timestamp", "type"]
+}

package/schemas/prompt-contract.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://sogni.ai/schemas/prompt-contract.schema.json",
+  "title": "PromptContract",
+  "description": "A PromptContract owns a tool's LLM-visible description and per-parameter docstrings. One contract per tool. Files in prompts/tools/*.json validate against this shape.",
+  "type": "object",
+  "required": ["contractId", "version", "toolName", "baseDescription", "parameterDocs"],
+  "additionalProperties": false,
+  "properties": {
+    "contractId": {
+      "type": "string",
+      "description": "Stable identifier for telemetry and registry lookup. Convention: <toolName>_v<n>."
+    },
+    "version": {
+      "type": "string",
+      "description": "Semver string. Bumped when the contract's data shape changes."
+    },
+    "toolName": {
+      "type": "string",
+      "description": "Tool the contract describes. Must match a registered tool name from enums/tool-names.json."
+    },
+    "baseDescription": {
+      "type": "string",
+      "description": "Default description shown to the LLM when this tool is visible."
+    },
+    "parameterDocs": {
+      "type": "object",
+      "description": "Per-parameter docstrings keyed by parameter name.",
+      "additionalProperties": { "type": "string" }
+    },
+    "voiceExamples": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Tool-specific voice or style examples (e.g. screenplay format for video)."
+    },
+    "conditionalNotes": {
+      "type": "object",
+      "description": "Conditional description fragments keyed by signal name. Appended to the baked description when the corresponding signal is present in the turn policy.",
+      "additionalProperties": { "type": "string" }
+    }
+  }
+}

package/schemas/storyboards/storyboard-planning-contract.schema.json

@@ -0,0 +1,108 @@
+{
+  "title": "storyboard planning contract",
+  "schemaVersion": "2026-05-12.1",
+  "description": "Typed planner payload for storyboard layout and text-rendering decisions. Renderable visible text is intentionally separate from non-renderable production metadata labels.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "source", "layout", "scenes", "endCard", "metadataLabels"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "storyboard-planning-contract/v1"
+    },
+    "source": {
+      "type": "string",
+      "enum": ["llm_schema", "assistant_metadata", "user_schema", "fallback_text"]
+    },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "storyboardCanvasAspectRatio", "storyboardCellAspectRatio", "targetVideoAspectRatio", "boardDimensions"],
+      "properties": {
+        "source": {
+          "type": "string",
+          "enum": ["llm_schema", "assistant_metadata", "user_schema", "fallback_text"]
+        },
+        "storyboardCanvasAspectRatio": {
+          "type": "string",
+          "description": "Aspect ratio for the composite storyboard sheet/page, such as 16:9 or 9:16."
+        },
+        "storyboardCellAspectRatio": {
+          "type": "string",
+          "description": "Aspect ratio for each cinematic video-frame artwork area inside the storyboard."
+        },
+        "targetVideoAspectRatio": {
+          "type": "string",
+          "description": "Final video aspect ratio, such as 9:16 for vertical social video."
+        },
+        "boardDimensions": {
+          "type": "string",
+          "description": "Optional exact storyboard board dimensions, such as 2560x1440 or 1440x2560."
+        }
+      }
+    },
+    "scenes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "index", "visibleText", "metadataLabels", "referenceUsage"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "index": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 24
+          },
+          "visibleText": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Only text that should actually appear inside the final video frame, such as brand copy, CTA text, signage, captions, or diegetic text."
+          },
+          "metadataLabels": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Production labels, timing notes, scene numbers, overlay markers, placeholders, and other notes that may guide the storyboard but must not be rendered inside a video scene or Seedance output."
+          },
+          "referenceUsage": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "endCard": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["visibleText", "metadataLabels"],
+      "properties": {
+        "visibleText": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "metadataLabels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "metadataLabels": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/schemas/tools/add_subtitles.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-04-27.1/tools/add_subtitles.schema.json",
+  "title": "add_subtitles arguments",
+  "schemaVersion": "2026-04-27.1",
+  "description": "Burn subtitles into a video from caller-supplied cues or an SRT/VTT string. Use when the user asks to add captions, subtitles, on-screen dialogue, or burned-in lyrics to a video. Either pass `cues` as an array of {startSeconds, endSeconds, text}, or pass a full `srt` string. Pace cues like real subtitles: split the script into multiple short cues (typically 1.5–4 seconds each, ~1–8 words per cue, roughly 15–20 characters per second of cue duration). Never burn a single cue that spans the entire clip — even a static image should get progressively revealed lines, not one paragraph held on screen the whole time. Auto-transcription (auto_transcribe=true) is not yet enabled and will return USER_INPUT_INCOMPLETE — when the user has not supplied lines, ask them for the cue text and timing instead of calling with auto_transcribe. If the user explicitly asks you to write, invent, improvise, or make up captions/subtitles, create a few short, generic cue lines yourself and call this tool with cues; do not ask a follow-up for exact wording in that case.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "sourceVideoIndex": {
+      "type": "number",
+      "description": "Which video to subtitle. Default: -1 (most recent generated or uploaded video). Non-negative values are 0-based indices into prior generated video results. Negative values reference uploaded videos."
+    },
+    "cues": {
+      "type": "array",
+      "description": "Ordered subtitle cues. Each cue has startSeconds, endSeconds, and the line of text to display. Provide either `cues` or `srt`, not both. Aim for multiple short cues (1.5–4s each, ~1–8 words) rather than one long cue spanning the full clip.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "startSeconds": {
+            "type": "number",
+            "minimum": 0
+          },
+          "endSeconds": {
+            "type": "number",
+            "minimum": 0
+          },
+          "text": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "startSeconds",
+          "endSeconds",
+          "text"
+        ]
+      }
+    },
+    "srt": {
+      "type": "string",
+      "description": "Full SRT (or VTT) document as a string, used in place of `cues`. Useful when the user pastes a subtitle file directly. Provide either `cues` or `srt`, not both."
+    },
+    "auto_transcribe": {
+      "type": "boolean",
+      "description": "Reserved for future speech-to-text support. Currently returns USER_INPUT_INCOMPLETE so the LLM can ask the user to supply cues. Do not set this — gather cue text from the user instead."
+    },
+    "style": {
+      "type": "object",
+      "description": "Optional styling overrides for the burned subtitles.",
+      "properties": {
+        "fontSizePct": {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 30,
+          "description": "Font size as a percentage of the video height. Default 6."
+        },
+        "color": {
+          "type": "string",
+          "description": "Subtitle fill color. Default \"#FFFFFF\"."
+        },
+        "outlineColor": {
+          "type": "string",
+          "description": "Subtitle outline color. Default \"#000000\"."
+        },
+        "position": {
+          "type": "string",
+          "enum": [
+            "bottom",
+            "top",
+            "center"
+          ],
+          "description": "Vertical placement of the subtitle line. Default \"bottom\"."
+        }
+      }
+    }
+  }
+}