feat: ScenarioBundle JSON Schema (request + response v1)

schemas/public_api/api.scenarios.bundle.request.v1.json

@@ -0,0 +1,274 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://axme.dev/schemas/public_api/api.scenarios.bundle.request.v1.json",
+  "title": "ApiScenariosBundleRequestV1",
+  "description": "ScenarioBundle — one JSON document submitted to POST /v1/scenarios/apply that provisions agents, compiles a workflow, and submits an intent in a single atomic operation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["scenario_id", "intent"],
+  "properties": {
+    "scenario_id": {
+      "type": "string",
+      "description": "Stable identifier for this scenario definition, e.g. 'approval.nginx_rollout.v1'.",
+      "pattern": "^[a-z0-9_]+(?:\\.[a-z0-9_]+)*$",
+      "minLength": 3,
+      "maxLength": 255
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1000
+    },
+    "idempotency_key": {
+      "type": "string",
+      "description": "If provided, duplicate submissions with the same key return the original intent instead of creating a new one.",
+      "maxLength": 255
+    },
+    "agents": {
+      "type": "array",
+      "description": "Service-account agents that participate in this scenario.",
+      "items": { "$ref": "#/$defs/AgentSpec" },
+      "maxItems": 50
+    },
+    "humans": {
+      "type": "array",
+      "description": "Human participants (org members) that may be assigned approval or task steps.",
+      "items": { "$ref": "#/$defs/HumanSpec" },
+      "maxItems": 20
+    },
+    "workflow": {
+      "$ref": "#/$defs/WorkflowSpec",
+      "description": "Inline workflow definition or reference to a pre-compiled macro."
+    },
+    "intent": {
+      "$ref": "#/$defs/IntentSpec",
+      "description": "Intent submission settings — type, payload, deadline, reminders, delivery limits."
+    }
+  },
+  "$defs": {
+    "AgentSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["role", "address"],
+      "properties": {
+        "role": {
+          "type": "string",
+          "description": "Logical role alias used to reference this agent in workflow steps.",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "address": {
+          "type": "string",
+          "description": "Agent address — either a short SA name or full agent:// URI.",
+          "minLength": 1,
+          "maxLength": 383
+        },
+        "create_if_missing": {
+          "type": "boolean",
+          "description": "If true, a service account is automatically created when the address is not registered.",
+          "default": false
+        },
+        "display_name": {
+          "type": "string",
+          "maxLength": 255
+        }
+      }
+    },
+    "HumanSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["role", "contact"],
+      "properties": {
+        "role": {
+          "type": "string",
+          "description": "Logical role alias used to reference this human in workflow steps.",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "contact": {
+          "type": "string",
+          "description": "Email address or org_member_id of the human participant.",
+          "minLength": 1,
+          "maxLength": 255
+        },
+        "display_name": {
+          "type": "string",
+          "maxLength": 255
+        }
+      }
+    },
+    "WorkflowSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "macro_id": {
+          "type": "string",
+          "description": "ID of a pre-registered macro template to use. When set, 'steps' are used as parameter overrides only.",
+          "maxLength": 255
+        },
+        "steps": {
+          "type": "array",
+          "description": "Ordered list of workflow steps. Required when macro_id is not provided.",
+          "items": { "$ref": "#/$defs/WorkflowStepSpec" },
+          "minItems": 1,
+          "maxItems": 100
+        }
+      }
+    },
+    "WorkflowStepSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["step_id", "tool_id"],
+      "properties": {
+        "step_id": {
+          "type": "string",
+          "description": "Unique step identifier within this workflow.",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "tool_id": {
+          "type": "string",
+          "description": "Tool to execute at this step.",
+          "minLength": 1,
+          "maxLength": 255
+        },
+        "assigned_to": {
+          "type": "string",
+          "description": "Role alias or agent address that owns this step. Used to update pending_with on each workflow tick.",
+          "maxLength": 383
+        },
+        "requires_approval": {
+          "type": "boolean",
+          "description": "When true, the workflow pauses at this step until a human submits resume_intent with task_result.",
+          "default": false
+        },
+        "step_deadline_seconds": {
+          "type": "integer",
+          "description": "Maximum seconds this step may run before being failed with 'step_timeout'.",
+          "minimum": 1
+        },
+        "retry": {
+          "$ref": "#/$defs/RetryPolicy"
+        },
+        "human_task": {
+          "$ref": "#/$defs/HumanTaskSpec",
+          "description": "Structured task description shown to the human when requires_approval=true."
+        },
+        "remind_after_seconds": {
+          "type": "integer",
+          "description": "Seconds to wait before sending the first reminder to the human assigned to this step.",
+          "minimum": 1
+        },
+        "remind_interval_seconds": {
+          "type": "integer",
+          "description": "Seconds between subsequent reminders after the first.",
+          "minimum": 1
+        },
+        "max_reminders": {
+          "type": "integer",
+          "description": "Maximum number of reminders before escalating to escalate_to.",
+          "minimum": 1
+        },
+        "escalate_to": {
+          "type": "string",
+          "description": "Role alias or address to escalate to once max_reminders is reached.",
+          "maxLength": 383
+        },
+        "on_success": {
+          "type": "string",
+          "description": "step_id to transition to on success. Omit to end the workflow.",
+          "maxLength": 100
+        },
+        "on_failure": {
+          "type": "string",
+          "description": "step_id to transition to on failure. Omit to fail the workflow.",
+          "maxLength": 100
+        }
+      }
+    },
+    "RetryPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "max_retries": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        },
+        "retry_delay_seconds": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 30
+        }
+      }
+    },
+    "HumanTaskSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title"],
+      "properties": {
+        "title": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 2000
+        },
+        "form_schema": {
+          "type": "object",
+          "description": "JSON Schema (draft 2020-12) for validating task_result submitted by the human.",
+          "additionalProperties": true
+        }
+      }
+    },
+    "IntentSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Intent type identifier, e.g. 'approval.change.v1'.",
+          "pattern": "^[a-z0-9_]+(?:\\.[a-z0-9_]+)*$",
+          "minLength": 3,
+          "maxLength": 255
+        },
+        "payload": {
+          "type": "object",
+          "description": "Domain-specific data for this intent.",
+          "additionalProperties": true
+        },
+        "deadline_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO-8601 UTC datetime after which the intent is automatically transitioned to TIMED_OUT."
+        },
+        "remind_after_seconds": {
+          "type": "integer",
+          "description": "Seconds after which the first reminder is sent to the human holder.",
+          "minimum": 1
+        },
+        "remind_interval_seconds": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_reminders": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "escalate_to": {
+          "type": "string",
+          "maxLength": 383
+        },
+        "max_delivery_attempts": {
+          "type": "integer",
+          "description": "Maximum agent delivery failures before transitioning to FAILED.",
+          "minimum": 1
+        },
+        "human_task": {
+          "$ref": "#/$defs/HumanTaskSpec"
+        }
+      }
+    }
+  }
+}

schemas/public_api/api.scenarios.bundle.response.v1.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://axme.dev/schemas/public_api/api.scenarios.bundle.response.v1.json",
+  "title": "ApiScenariosBundleResponseV1",
+  "description": "Response from POST /v1/scenarios/bundle — returns the created (or idempotent-matched) intent plus provisioned agent addresses.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["intent_id", "scenario_id", "status"],
+  "properties": {
+    "intent_id": {
+      "type": "string",
+      "description": "UUID of the created or matched intent."
+    },
+    "scenario_id": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string",
+      "description": "Initial lifecycle status of the intent.",
+      "enum": ["DELIVERED", "IN_PROGRESS", "WAITING"]
+    },
+    "pending_with": {
+      "type": "string",
+      "description": "Agent address or human contact currently holding the intent."
+    },
+    "workflow_compile_id": {
+      "type": "string",
+      "description": "ID of the compiled workflow run, if a workflow was compiled and started."
+    },
+    "idempotent": {
+      "type": "boolean",
+      "description": "True when an existing intent was returned rather than a new one created."
+    },
+    "agents": {
+      "type": "array",
+      "description": "Resolved agent addresses for each role specified in the bundle.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["role", "address"],
+        "properties": {
+          "role": { "type": "string" },
+          "address": { "type": "string" },
+          "created": {
+            "type": "boolean",
+            "description": "True when the service account was freshly created by this request."
+          }
+        }
+      }
+    },
+    "deadline_at": {
+      "type": ["string", "null"],
+      "format": "date-time"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}