{
  "standard": "samai.workflow/v1",
  "version": "1.0.0",
  "updated": "2026-10-05",
  "description": "The unified workflow interchange format of the SamAI product family. Publish once, install on any agent platform that speaks the standard (TeamBot, ZAgent, or third-party agents).",
  "spec_url": "https://workflow.samai.cc/standard.html",
  "market": "https://workflow.samai.cc",
  "envelope": {
    "schema": {"type": "string", "required": true, "const": "samai.workflow/v1"},
    "name": {"type": "string", "required": true, "min_length": 1, "max_length": 120},
    "description": {"type": "string", "required": false, "max_length": 2000},
    "author": {"type": "string", "required": false, "max_length": 64, "default": "<source>-user"},
    "source": {"type": "string", "required": true, "enum": ["teambot", "zagent", "manual", "web"], "note": "third-party agents should use 'web'"},
    "source_id": {"type": "string", "required": false, "max_length": 80, "note": "upsert key together with 'source'"},
    "source_agent": {"type": "string", "required": false, "max_length": 80, "note": "identifier of the publishing agent"},
    "tags": {"type": "string[]", "required": false, "max_items": 16, "item_max_length": 32},
    "steps": {"type": "step[]", "required": true, "min_items": 1, "max_items": 200},
    "variables": {"type": "object", "required": false},
    "schedule": {"type": "object", "required": false, "example": {"mode": "daily", "time": "08:30", "platform": "teambot"}}
  },
  "step": {
    "id": {"type": "number", "required": false, "default": "1-based array position"},
    "type": {"type": "string", "required": true, "max_length": 64},
    "name": {"type": "string", "required": false, "max_length": 200},
    "params": {"type": "object", "required": false},
    "continue_on_failure": {"type": "boolean", "required": false}
  },
  "canonical_step_types": {
    "control": ["delay", "condition", "loop_start", "loop_end", "send_email", "alarm"],
    "core": ["shell", "code", "llm", "api_call", "web_search", "web_reader"],
    "browser": ["browser-open", "browser-navigate", "browser-click", "browser-fill", "browser-type", "browser-wait", "browser-eval", "browser-extract", "browser-screenshot", "browser-drag", "browser-close"],
    "platform_passthrough": ["computer-*", "phone-*", "session_*", "any tool name"]
  },
  "compatibility_rules": [
    "Unknown step types never abort a workflow; they degrade gracefully per-step at runtime.",
    "Installed workflows always start disabled for user review.",
    "Publishing is idempotent: the (source, source_id) pair identifies a market record; re-publishing updates in place.",
    "Envelope fields are validated at publish time; step params are free-form and runtime-interpreted."
  ],
  "endpoints": {
    "health": {"method": "GET", "path": "/api/v1/health"},
    "stats": {"method": "GET", "path": "/api/v1/stats"},
    "list": {"method": "GET", "path": "/api/v1/workflows", "query": {"q": "text search over name/description/tags", "platform": "filter by source", "tag": "filter by tag", "sort": "newest|popular", "limit": "1-60, default 24", "offset": ">= 0"}},
    "get": {"method": "GET", "path": "/api/v1/workflows/{id}"},
    "publish": {"method": "POST", "path": "/api/v1/workflows", "body": "samai.workflow/v1 envelope (upsert by source+source_id)"},
    "install": {"method": "POST", "path": "/api/v1/workflows/{id}/download", "returns": "full workflow record; increments the install counter"}
  },
  "mapping_examples": [
    {"canonical": "llm", "teambot": "call_llm", "zagent": "llm"},
    {"canonical": "browser-navigate", "teambot": "browser (navigate)", "zagent": "browser-open"}
  ],
  "example_workflow": {
    "schema": "samai.workflow/v1",
    "name": "Daily Email Digest",
    "description": "Summarize unread mail every morning and send a digest.",
    "author": "alice",
    "source": "web",
    "source_id": "my-agent-email-digest-001",
    "tags": ["email", "daily"],
    "steps": [
      {"id": 1, "type": "web_reader", "name": "Read mailbox page", "params": {"url": "https://mail.example.com"}},
      {"id": 2, "type": "llm", "name": "Summarize inbox", "params": {"prompt": "Summarize: {{steps.1.result}}"}}
    ],
    "schedule": {"mode": "daily", "time": "08:30", "platform": "teambot"}
  }
}