@sogni-ai/sogni-protocol 1.0.0-alpha.2 → 1.0.0-alpha.21

package/schemas/artifacts/artifact-node.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/artifacts/artifact-node.schema.json",
+  "title": "Artifact graph node",
+  "schemaVersion": "2026-05-20.1",
+  "description": "One node in the v2 ArtifactGraph. ArtifactNode replaces positional URL arrays (resultUrls / videoResultUrls / audioResultUrls) deleted in plan Phase 5. Every tool result auto-registers one node. Lineage edges resolve continuation ('use the second image', 'make it cinematic') without transcript scraping. Per-model token shape lives in modelRefs (gpt-image-2 'Image 1', seedance-2 '@Image1', ltx-2.3 'context_image_0').",
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "ArtifactEdge": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Typed lineage edge from this artifact to one of its parents.",
+      "properties": {
+        "parentId": { "type": "string" },
+        "relation": {
+          "type": "string",
+          "enum": [
+            "derived_from",
+            "edited_from",
+            "styled_from",
+            "animated_from",
+            "stitched_from",
+            "extended_from",
+            "segmented_from",
+            "reference_for"
+          ]
+        }
+      },
+      "required": ["parentId", "relation"]
+    },
+    "ArtifactVersion": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "One version of an artifact. Retries, refinements, and user-driven redos all append a version rather than mutating an existing one.",
+      "properties": {
+        "versionId": { "type": "string" },
+        "uri": { "type": "string" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "reason": {
+          "type": "string",
+          "enum": ["initial", "retry", "refinement", "audit_repair", "user_redo"]
+        },
+        "jobId": {
+          "type": "string",
+          "description": "Optional sogni-socket job id that produced this version."
+        }
+      },
+      "required": ["versionId", "createdAt", "reason"]
+    },
+    "ArtifactSource": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "upload" },
+            "uploadId": { "type": "string" }
+          },
+          "required": ["type", "uploadId"]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "tool_result" },
+            "runId": { "type": "string" },
+            "toolCallId": { "type": "string" }
+          },
+          "required": ["type", "toolCallId"]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "workflow_stage" },
+            "workflowRunId": { "type": "string" },
+            "stageId": { "type": "string" },
+            "itemId": { "type": "string" }
+          },
+          "required": ["type", "workflowRunId", "stageId"]
+        }
+      ]
+    }
+  },
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "pattern": "^art_(?:[0-9A-Z]{26}|[0-9a-fA-F]{32}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$",
+      "description": "Stable artifact id. ULID form (`art_` + 26-char Crockford base32 body) is RECOMMENDED for new ids — use `generateUlidArtifactId()` from `@sogni-ai/sogni-intelligence-client/artifacts`. Two legacy forms remain accepted so existing in-wild ids stay valid: `art_` + 32 hex chars (UUID with hyphens stripped, the historical `createArtifactNode` output) and `art_` + canonical UUID with hyphens. Read-side validators must keep accepting all three; write-side code SHOULD enforce ULID via `preferUlid()`."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["image", "video", "audio", "text", "workflow", "collection"]
+    },
+    "uri": {
+      "type": "string",
+      "description": "Canonical resolvable URI for the current version (mirrors versions[last].uri for convenience)."
+    },
+    "mimeType": { "type": "string" },
+    "userLabel": {
+      "type": "string",
+      "description": "Friendly label the user (or the system on the user's behalf) chose. Optional; planner falls back to artifactId + kind."
+    },
+    "modelRefs": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Per-model formatter mapping. Keys are model ids; values are the token that model expects in prompts. Examples: gpt-image-2 -> 'Image 1', seedance-2 -> '@Image1', ltx-2.3 -> 'context_image_0'. Use the asset-reference helpers in @sogni/creative-agent rather than hand-formatting."
+    },
+    "source": { "$ref": "#/$defs/ArtifactSource" },
+    "parents": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ArtifactEdge" }
+    },
+    "versions": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/ArtifactVersion" }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Free-form artifact metadata (width/height, durationSeconds, seed, prompt summary, etc.). Boundary code populates known fields; consumers must not assume any specific field is present."
+    },
+    "createdAt": { "type": "string", "format": "date-time" }
+  },
+  "required": [
+    "artifactId",
+    "kind",
+    "modelRefs",
+    "source",
+    "parents",
+    "versions",
+    "metadata",
+    "createdAt"
+  ]
+}

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

@@ -0,0 +1,151 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$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 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",
+  "$defs": {
+    "SpendGateState": {
+      "type": "string",
+      "description": "Canonical lifecycle states for a spend gate. 'not_required' = free / no-cost tool. 'preview_required' = estimate must be shown to the user. 'waiting_for_user' = awaiting confirm or cancel. 'confirmed' = user accepted; runner may dispatch. 'cancelled' = user declined. 'insufficient_credit' = wallet balance below estimate. 'safety_review_required' = blocked pending human or automated safety review. 'failed' = unrecoverable error in the gate itself.",
+      "enum": [
+        "not_required",
+        "preview_required",
+        "waiting_for_user",
+        "confirmed",
+        "cancelled",
+        "insufficient_credit",
+        "safety_review_required",
+        "failed"
+      ]
+    },
+    "SpendGateDecision": {
+      "type": "string",
+      "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 estimate's capacityUnits.",
+      "properties": {
+        "model": { "type": "string" },
+        "units": { "type": "number", "minimum": 0 },
+        "tokenType": {
+          "type": "string",
+          "enum": ["spark", "sogni"]
+        }
+      },
+      "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='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" },
+        "estimateUnits": { "type": "number", "minimum": 0 }
+      },
+      "required": ["toolCallId", "toolName"]
+    },
+    "PendingWorkflowPlan": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Reference to the workflow run this gate authorizes (only meaningful when scope='workflow_run').",
+      "properties": {
+        "workflowRunId": { "type": "string" },
+        "templateId": { "type": "string" }
+      },
+      "required": ["workflowRunId", "templateId"]
+    }
+  },
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gateId": { "type": "string" },
+        "runId": { "type": "string" },
+        "scope": { "const": "tool_call" },
+        "toolCallId": { "type": "string" },
+        "pendingToolCalls": {
+          "type": "array",
+          "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" },
+        "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" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "failureReason": { "type": "string" }
+      },
+      "required": ["gateId", "scope", "pendingToolCalls", "estimate", "state", "updatedAt"]
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gateId": { "type": "string" },
+        "runId": { "type": "string" },
+        "scope": { "const": "workflow_run" },
+        "workflowRunId": { "type": "string" },
+        "pendingWorkflowPlan": { "$ref": "#/$defs/PendingWorkflowPlan" },
+        "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", "workflowRunId", "estimate", "state", "updatedAt"]
+    }
+  ]
+}

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/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"
+  ]
+}