@sogni-ai/sogni-protocol 1.0.0-alpha.4 → 1.0.0-alpha.5

package/README.md

@@ -78,3 +78,12 @@ Tool prompt prose lives in `prompts/tools/*.json`. Each file is one [`PromptCont
 ## Editing schemas
 
 The JSON Schema files under `schemas/` are the authoritative wire-spec shape. Any change here is a protocol bump (minor or major depending on compatibility). Consumers regenerate their language-specific types via their codegen step.
+
+## v2 contract docs
+
+This branch carries the additive schemas for the Sogni Platform v2 execution architecture. Two markdown documents under [`docs/`](./docs/) describe the new surface for downstream consumers:
+
+- [`docs/v2-changes-summary.md`](./docs/v2-changes-summary.md) — concise map of the 8 new schemas (IntentInput, TurnAnalysis, ToolMetadata, ArtifactNode, ArtifactGraph, SpendGate, WorkflowAuthorization, RunEvent) and per-consumer impact.
+- [`docs/v2-consumer-contract.md`](./docs/v2-consumer-contract.md) — full integration contract for native `sogni` (Mac/iOS via SogniKit codegen) and `sogni-creative-agent-skill`. Covers transport choice, classifier/regex replacement plan, artifact-graph projection, tool-surface budget, preserved public API params, and the workflow charging model.
+
+v2 does not implement migration in the native or skill repos; their teams own implementation timing against this contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sogni-ai/sogni-protocol",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.5",
   "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/agent/intent-input.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/agent/intent-input.schema.json",
+  "title": "L1 IntentClassifier input packet",
+  "schemaVersion": "2026-05-20.1",
+  "description": "Compact context packet handed to the L1 IntentClassifier at the start of every user turn. Qwen3 256k context window comfortably holds 16-reference-image generations and multi-segment storyboard frames; the runtime never silently drops artifacts. Trim only when measured budget pressure forces it. This contract is built deterministically by the host (browser or cloud runner) from explicit runtime state; it never re-derives semantics from transcript regex.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "currentMessage": {
+      "type": "string",
+      "description": "Raw user message text for this turn. Verbatim; sanitization belongs to boundary code, not this contract."
+    },
+    "currentMessageDetails": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional structured form of the user's latest message. Producers MAY emit either currentMessage or this; consumers MUST handle BOTH. `text` is required so consumers can always derive a string-level view.",
+      "properties": {
+        "id": { "type": "string" },
+        "role": { "type": "string", "enum": ["user", "system"] },
+        "text": { "type": "string" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "localeHint": { "type": "string" }
+      },
+      "required": ["text"]
+    },
+    "runtimeFlags": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional runtime feature flags the planner reads to decide tool surface and confirmation policy.",
+      "properties": {
+        "surface": {
+          "type": "string",
+          "enum": ["browser", "hosted_chat", "durable_chat", "workflow", "native", "skill"],
+          "description": "Originating producer surface."
+        },
+        "allowPaidTools": { "type": "boolean" },
+        "allowMutatingTools": { "type": "boolean" },
+        "durableRequired": { "type": "boolean" }
+      }
+    },
+    "activeState": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Currently-resolved focus state owned by the runtime (artifact graph + workflow runner). Populated from explicit runtime references — never from prose extraction.",
+      "properties": {
+        "activeArtifactId": { "type": "string" },
+        "activeArtifactType": {
+          "type": "string",
+          "enum": ["image", "video", "audio", "text", "workflow", "collection"]
+        },
+        "pendingAction": {
+          "type": "object",
+          "description": "Opaque reference to a runtime-tracked pending action (e.g. proposed plan awaiting selection). Shape is owned by the runtime, not this schema.",
+          "additionalProperties": true
+        },
+        "awaitingConfirmation": { "type": "boolean" },
+        "lastToolResult": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "toolName": { "type": "string" },
+            "toolCallId": { "type": "string" },
+            "status": { "type": "string" }
+          },
+          "required": ["toolName", "toolCallId", "status"]
+        },
+        "activeWorkflowRunId": { "type": "string" }
+      }
+    },
+    "artifactState": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Stable artifact identifiers owned by the ArtifactGraph. Qwen3 256k context window comfortably holds 16-reference-image generations and multi-segment storyboard frames; the runtime never silently drops artifacts. Trim only when measured budget pressure forces it.",
+      "properties": {
+        "selectedArtifactIds": {
+          "type": "array",
+          "description": "Artifacts the user or planner has explicitly focused (e.g. multi-select for batch edit).",
+          "items": { "type": "string" }
+        },
+        "artifactIds": {
+          "type": "array",
+          "description": "Full conversation artifact id list. UNBOUNDED by default. Qwen3 256k context window comfortably holds 16-reference-image generations and multi-segment storyboard frames; the runtime never silently drops artifacts. Trim only when measured budget pressure forces it.",
+          "items": { "type": "string" }
+        },
+        "lastGeneratedArtifactId": { "type": "string" },
+        "lastEditedArtifactId": { "type": "string" }
+      },
+      "required": ["selectedArtifactIds", "artifactIds"]
+    },
+    "recentTurns": {
+      "type": "array",
+      "description": "Recent transcript window. UNBOUNDED by default. Qwen3 256k context window comfortably holds 16-reference-image generations and multi-segment storyboard frames; the runtime never silently drops artifacts. Trim only when measured budget pressure forces it. Sliding-window trimming from contextWindow.ts only fires after measured token budget pressure, and writes the trimmed prefix into conversationSummary.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "role": { "type": "string", "enum": ["user", "assistant", "tool", "system"] },
+          "content": { "type": "string" },
+          "sequence": { "type": "integer", "minimum": 0 }
+        },
+        "required": ["role", "content", "sequence"]
+      }
+    },
+    "conversationSummary": {
+      "type": "string",
+      "description": "Rolling summary of trimmed prefix. Empty string until the first measured-budget-pressure trim event."
+    },
+    "userPreferences": {
+      "type": "object",
+      "description": "Free-form preference payload (e.g. preferred model tier, default aspect ratio). Deliberate exception: additionalProperties is true here, mirroring the data/metadata pattern in other contracts, because preferences evolve faster than the schema.",
+      "additionalProperties": true
+    },
+    "availableCapabilitiesSummary": {
+      "type": "array",
+      "description": "Short human-readable capability strings the planner can quote when answering capability questions without invoking any tool.",
+      "items": { "type": "string" }
+    }
+  },
+  "required": [
+    "currentMessage",
+    "activeState",
+    "artifactState",
+    "recentTurns",
+    "conversationSummary",
+    "availableCapabilitiesSummary"
+  ]
+}

package/schemas/agent/turn-analysis.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/agent/turn-analysis.schema.json",
+  "title": "L1 IntentClassifier output",
+  "schemaVersion": "2026-05-20.1",
+  "description": "Structured output of the L1 IntentClassifier. Produced by an LLM-backed classifier, a typed planner, runtime state inspection, the artifact graph, or an explicit user signal — never by regex. Per the Codex reconciliation in v2 plan §1.A, the legacy SignalSource value 'regex' is intentionally absent from SignalProvenance; regex is demoted to bounded fact extraction (dimensions, durations, file types) which does not produce semantic intent.",
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "SignalProvenance": {
+      "type": "string",
+      "description": "Which layer authored this TurnAnalysis. The value 'regex' is intentionally absent — regex extracts bounded facts only and never decides intent, tool surface, or routing.",
+      "enum": [
+        "classifier",
+        "planner",
+        "runtime_state",
+        "artifact_graph",
+        "user_explicit"
+      ]
+    }
+  },
+  "properties": {
+    "domain": {
+      "type": "string",
+      "enum": ["chat", "image", "video", "audio", "analysis", "workflow", "memory", "settings", "unknown"]
+    },
+    "intent": {
+      "type": "string",
+      "enum": ["generate", "edit", "analyze", "transform", "question", "capability", "continue", "reference", "configure", "clarify", "unknown"]
+    },
+    "executionMode": {
+      "type": "string",
+      "enum": ["none", "tool", "multi_tool", "workflow"]
+    },
+    "userWantsExecution": { "type": "boolean" },
+    "isCapabilityQuestion": { "type": "boolean" },
+    "isFutureInstruction": { "type": "boolean" },
+    "isReferenceOnly": { "type": "boolean" },
+    "needsPriorContext": { "type": "boolean" },
+    "needsClarification": { "type": "boolean" },
+    "referencedArtifacts": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Artifact ids the classifier resolved from the user's message via the artifact graph (positional references like 'the second image' resolve to stable ids before this list is emitted)."
+    },
+    "requiredCapabilities": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Free-form capability tags the planner must satisfy (e.g. 'image_generation', 'video_stitch')."
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "provenance": {
+      "$ref": "#/$defs/SignalProvenance"
+    }
+  },
+  "required": [
+    "domain",
+    "intent",
+    "executionMode",
+    "userWantsExecution",
+    "isCapabilityQuestion",
+    "isFutureInstruction",
+    "isReferenceOnly",
+    "needsPriorContext",
+    "referencedArtifacts",
+    "requiredCapabilities",
+    "needsClarification",
+    "confidence",
+    "provenance"
+  ]
+}

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

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/artifacts/artifact-graph.schema.json",
+  "title": "Artifact graph serialization",
+  "schemaVersion": "2026-05-20.1",
+  "description": "Durable serialization of the in-memory ArtifactGraph. The same shape mirrors into ChatRunRecord.artifacts[] and WorkflowRunRecord.artifacts[] so cloud and hosted runners can reconstitute the graph on resume. The runtime Map<string, ArtifactNode> serializes as a positional nodes[] array; artifactId uniqueness is a runtime invariant, not expressible cheaply in JSON Schema.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "nodes": {
+      "type": "array",
+      "description": "All artifact nodes in the graph. Uniqueness on artifactId is enforced by the runtime, not the schema.",
+      "items": {
+        "$ref": "./artifact-node.schema.json"
+      }
+    },
+    "selectedId": {
+      "type": "string",
+      "description": "Optional currently-selected artifact id. When present, MUST match an artifactId in nodes."
+    },
+    "compatibilityProjections": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Read-only legacy projections derived from nodes[]. Populated during the Phase 1-4 transition so existing chat-side code that still reads positional URL arrays keeps working. Deleted after plan Phase 5.",
+      "properties": {
+        "resultUrls": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "videoResultUrls": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "audioResultUrls": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  },
+  "required": ["nodes"]
+}

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,130 @@
+{
+  "$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 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.",
+  "type": "object",
+  "additionalProperties": false,
+  "$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",
+      "enum": ["confirm", "cancel"]
+    },
+    "SpendEstimateLineItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "One row of the spend estimate breakdown. Sum of (units * model price) across line items yields the totalEstimatedCapacityUnits.",
+      "properties": {
+        "model": { "type": "string" },
+        "units": { "type": "number", "minimum": 0 },
+        "tokenType": {
+          "type": "string",
+          "enum": ["spark", "sogni"]
+        }
+      },
+      "required": ["model", "units", "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).",
+      "properties": {
+        "toolCallId": { "type": "string" },
+        "toolName": { "type": "string" }
+      },
+      "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": {
+          "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"]
+        },
+        "state": { "$ref": "#/$defs/SpendGateState" },
+        "reason": { "type": "string" },
+        "decision": { "$ref": "#/$defs/SpendGateDecision" },
+        "decidedAt": { "type": "string", "format": "date-time" },
+        "lastTransitionAt": { "type": "string", "format": "date-time" }
+      },
+      "required": ["gateId", "scope", "toolCallId", "estimate", "state", "lastTransitionAt"]
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gateId": { "type": "string" },
+        "runId": { "type": "string" },
+        "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"]
+        },
+        "state": { "$ref": "#/$defs/SpendGateState" },
+        "reason": { "type": "string" },
+        "decision": { "$ref": "#/$defs/SpendGateDecision" },
+        "decidedAt": { "type": "string", "format": "date-time" },
+        "lastTransitionAt": { "type": "string", "format": "date-time" }
+      },
+      "required": ["gateId", "scope", "workflowRunId", "estimate", "state", "lastTransitionAt"]
+    }
+  ]
+}

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,111 @@
+{
+  "$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. 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).",
+      "enum": [
+        "run_queued",
+        "run_started",
+        "run_completed",
+        "run_partial_failure",
+        "run_failed",
+        "run_cancelled",
+        "llm_round_started",
+        "llm_token",
+        "llm_round_completed",
+        "tool_call_proposed",
+        "tool_call_dispatched",
+        "tool_call_progress",
+        "tool_call_resolved",
+        "artifact_created",
+        "artifact_updated",
+        "artifact_referenced",
+        "run_waiting_for_user",
+        "spend_preview_emitted",
+        "spend_confirmed",
+        "spend_cancelled",
+        "spend_insufficient",
+        "audit_evaluated",
+        "repair_requested",
+        "stage_started",
+        "stage_completed",
+        "stage_failed",
+        "stage_waiting_for_user"
+      ]
+    },
+    "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"],
+      "description": "Substrate discriminator (plan §13.5). chat and workflow runs share persistence, lease, heartbeat, event log, waiting semantics, cancellation, cost confirmation, and resume."
+    },
+    "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/tools/tool-metadata.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/tools/tool-metadata.schema.json",
+  "title": "Tool catalog metadata",
+  "schemaVersion": "2026-05-20.1",
+  "description": "Metadata that accompanies each tool definition in the v2 catalog. Drives tool surfacing decisions (which family/execution mode is visible this turn), spend gating (costClass + requiresConfirmation), retry behavior (retrySafety), and durable-run observability (mutatesData, producesArtifacts). Input/output schema refs point at sogni-protocol argument and result contracts so the validator and the planner share one source of truth.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Canonical tool name (snake_case, matches the OpenAI-format tool definition exposed to the LLM)."
+    },
+    "family": {
+      "type": "string",
+      "enum": ["creative", "composition", "artifact", "memory", "settings", "analysis", "control"],
+      "description": "Coarse grouping used by the planner to pick a minimal visible tool subset."
+    },
+    "executionMode": {
+      "type": "string",
+      "enum": ["hosted", "client", "app", "workflow", "internal"],
+      "description": "Where the tool runs. 'hosted' = sogni-api durable runner. 'client' = browser tool dispatch. 'app' = native shell. 'workflow' = synthetic tool that creates a WorkflowRun. 'internal' = runtime-only (e.g. L1 hidden resolver) — never surfaced to the LLM directly."
+    },
+    "inputSchemaRef": {
+      "type": "string",
+      "description": "URI or repo-relative path. MUST resolve to a sogni-protocol tool argument JSON Schema (e.g. schemas/tools/generate_image.schema.json)."
+    },
+    "outputSchemaRef": {
+      "type": "string",
+      "description": "URI or repo-relative path. MUST resolve to a sogni-protocol tool result envelope schema."
+    },
+    "costClass": {
+      "type": "string",
+      "enum": ["free", "low", "medium", "high", "variable"],
+      "description": "Indicative cost tier. Concrete unit estimates live on the SpendGate request, not here."
+    },
+    "latencyClass": {
+      "type": "string",
+      "enum": ["inline", "interactive", "long_running"],
+      "description": "Indicative wall-clock tier. 'long_running' tools generally belong inside a Workflow Template, not a synchronous chat turn."
+    },
+    "mutatesData": {
+      "type": "boolean",
+      "description": "True when the tool changes persisted user state (e.g. manage_memory write, settings update)."
+    },
+    "producesArtifacts": {
+      "type": "boolean",
+      "description": "True when the tool emits one or more ArtifactNodes that must be registered in the ArtifactGraph."
+    },
+    "requiresConfirmation": {
+      "type": "string",
+      "enum": ["never", "paid", "destructive", "always"],
+      "description": "Confirmation policy. 'paid' defers to SpendGate. 'destructive' requires an explicit user yes regardless of cost. 'always' is reserved for atomic operations with no other gate."
+    },
+    "retrySafety": {
+      "type": "string",
+      "enum": ["idempotent", "dedupe_key_required", "not_safe"],
+      "description": "Whether the runner may retry the tool call on a transient failure. 'dedupe_key_required' tools must be called with a stable dedupe token (e.g. sogni-socket project id)."
+    },
+    "hiddenFromModel": {
+      "type": "boolean",
+      "description": "Optional. L1 hidden context tools (resolve_*, inspect_*) set this true so the runner can call them directly without surfacing them to the LLM."
+    }
+  },
+  "required": [
+    "name",
+    "family",
+    "executionMode",
+    "inputSchemaRef",
+    "outputSchemaRef",
+    "costClass",
+    "latencyClass",
+    "mutatesData",
+    "producesArtifacts",
+    "requiresConfirmation",
+    "retrySafety"
+  ]
+}