agents.config.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "zed-orchestrator agents config",
  "type": "object",
  "anyOf": [
    { "required": ["agentGroups"] },
    { "required": ["subAgents", "reviewer"] }
  ],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Optional JSON Schema path for editor validation."
    },

    "maxTurns": {
      "type": "integer", "minimum": 1, "default": 5,
      "description": "Maximum review rounds before the orchestrator gives up."
    },
    "agentTimeoutMs": {
      "type": "integer", "minimum": 1000, "default": 120000,
      "description": "Per-agent wall-clock timeout in milliseconds."
    },
    "maxRetries": {
      "type": "integer", "minimum": 0, "default": 3,
      "description": "Retry attempts for transient failures (429, 503, timeouts)."
    },
    "retryDelayMs": {
      "type": "integer", "minimum": 0, "default": 5000,
      "description": "Base exponential-backoff delay in milliseconds."
    },
    "heartbeatMs": {
      "type": "integer", "minimum": 0, "default": 30000,
      "description": "How often to emit a 'still working' ping. 0 = disabled."
    },
    "maxRetryAfterMs": {
      "type": "integer", "minimum": 0, "default": 300000,
      "description": "Cap on the Retry-After sleep derived from upstream error messages."
    },
    "retryablePatterns": {
      "type": "array",
      "minItems": 1,
      "items": { "type": "string", "minLength": 1 },
      "description": "Case-insensitive regex patterns tested against error messages to decide if a failure is transient and worth retrying. Replaces the built-in defaults: [\"429\", \"rate.?limit\", \"too many requests\", \"overloaded\", \"503\", \"502\", \"529\", \"TIMEOUT\", \"ECONNRESET\", \"ECONNREFUSED\"]. Errors NOT matched here stop the task immediately when they contain an HTTP status code."
    },
    "maxLineBytes": {
      "type": "integer", "minimum": 1024, "default": 4194304,
      "description": "Max bytes for a single JSON-RPC line from a sub-agent (OOM guard)."
    },
    "maxOutputBytes": {
      "type": "integer", "minimum": 1024, "default": 10485760,
      "description": "Max total accumulated streamed or direct final text output per sub-agent (OOM guard)."
    },
    "reviewerAgentChars": {
      "type": "integer", "minimum": 1000, "default": 40000,
      "description": "Max characters of each sub-agent result included in the reviewer prompt."
    },
    "concurrency": {
      "type": "integer", "minimum": 1, "default": 4,
      "description": "Max sub-agents running simultaneously per group (fairness semaphore)."
    },
    "probeTimeoutMs": {
      "type": "integer", "minimum": 0, "default": 20000,
      "description": "Health-probe timeout per agent on round 1. Agents that fail are skipped. 0 disables probes."
    },
    "envIsolation": {
      "type": "boolean", "default": true,
      "description": "When true, sub-agents only inherit SAFE_ENV_KEYS plus explicit passEnv."
    },
    "debug": {
      "type": "boolean", "default": false,
      "description": "When true, every outgoing/incoming JSON-RPC frame and every line of sub-agent stderr is mirrored to the orchestrator's own stderr (visible in Zed under 'agent server logs' / 'dev: open acp logs' as stderr entries). Also enabled by setting the ORCHESTRATOR_DEBUG environment variable to any non-empty value other than '0' or 'false'. Use this to diagnose how a particular sub-agent (Claude, Copilot, etc.) reports provider failures."
    },
    "defaultGroup": {
      "type": "string", "minLength": 1,
      "description": "Initial agent group for each new Zed session."
    },
    "workflow": {
      "type": "array", "minItems": 1,
      "items": {
        "type": "string", "minLength": 1,
        "description": "Name of an agent group to run after the previous group is approved."
      },
      "description": "Ordered group progression after approval."
    },
    "artifactDir": {
      "$ref": "#/definitions/workspaceRelativePath",
      "description": "Workspace-relative directory for plan/report artifacts."
    },

    "rateLimits": {
      "type": "object",
      "description": "Token-bucket rate limits keyed by command or rateLimitKey.",
      "additionalProperties": {
        "type": "object",
        "required": ["requestsPerMinute"],
        "properties": {
          "requestsPerMinute": {
            "type": "number", "exclusiveMinimum": 0,
            "description": "Average token-bucket refill rate for this key, measured in requests per minute."
          },
          "burstSize": {
            "type": "integer", "minimum": 1,
            "description": "Maximum burst capacity for this key. Defaults to requestsPerMinute when omitted."
          }
        }
      }
    },

    "mcpServers": {
      "type": "array",
      "description": "MCP tool servers shared across all sub-agents.",
      "items": {
        "type": "object",
        "required": ["type", "name"],
        "allOf": [
          {
            "if": { "properties": { "type": { "const": "http" } } },
            "then": { "required": ["url"] }
          },
          {
            "if": { "properties": { "type": { "const": "stdio" } } },
            "then": { "required": ["command"] }
          }
        ],
        "properties": {
          "type":    { "type": "string", "enum": ["http", "stdio"], "description": "MCP transport type: http for URL servers, stdio for child-process servers." },
          "name":    { "type": "string", "minLength": 1, "description": "MCP server name forwarded to child agents." },
          "url":     { "type": "string", "minLength": 1, "description": "HTTP MCP endpoint URL. Required when type is http." },
          "command": { "type": "string", "minLength": 1, "description": "Executable for a stdio MCP server. Required when type is stdio." },
          "args":    {
            "type": "array",
            "items": { "type": "string", "description": "One command-line argument for the stdio MCP server." },
            "description": "Arguments passed to a stdio MCP server command."
          },
          "env": {
            "type": "array",
            "description": "Stdio MCP environment entries. Values support {env:ENV_VAR} and ${ENV_VAR} expansion.",
            "items": {
              "type": "object",
              "required": ["name", "value"],
              "additionalProperties": false,
              "properties": {
                "name":  { "type": "string", "minLength": 1, "description": "Environment variable name passed to the stdio MCP server." },
                "value": { "type": "string", "description": "Supports {env:ENV_VAR} and ${ENV_VAR} expansion." }
              }
            }
          },
          "headers": {
            "type": "array",
            "description": "HTTP headers forwarded to this MCP server. Values support {env:ENV_VAR} and ${ENV_VAR} expansion.",
            "items": {
              "type": "object",
              "required": ["name", "value"],
              "additionalProperties": false,
              "properties": {
                "name":  { "type": "string", "minLength": 1, "description": "HTTP header name sent to the MCP server." },
                "value": { "type": "string", "description": "Supports {env:ENV_VAR} and ${ENV_VAR} expansion." }
              }
            }
          }
        }
      }
    },

    "subAgents": {
      "type": "array", "minItems": 1,
      "description": "Legacy default group sub-agents.",
      "items": {
        "$ref": "#/definitions/agentSpec",
        "description": "Agent spec for the legacy default group."
      }
    },
    "reviewer": {
      "$ref": "#/definitions/agentSpec",
      "description": "Legacy default reviewer, or fallback for groups that omit their own."
    },
    "agentGroups": {
      "type": "object", "minProperties": 1,
      "description": "Named sub-agent groups.",
      "additionalProperties": {
        "$ref": "#/definitions/agentGroup",
        "description": "Agent group keyed by the group name used in defaultGroup, workflow, and @orchestrator group directives."
      }
    }
  },

  "definitions": {
    "agentGroup": {
      "type": "object",
      "required": ["subAgents"],
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "anyOf": [
              { "properties": { "strategy": { "const": "parallel_reports" } }, "required": ["strategy"] },
              { "not": { "required": ["strategy"] } }
            ]
          },
          "then": {
            "not": {
              "anyOf": [
                { "required": ["writer"] },
                { "required": ["writerPermissions"] }
              ]
            },
            "properties": {
              "permissions": { "$ref": "#/definitions/readOnlyPermissions" },
              "reviewerPermissions": { "$ref": "#/definitions/readOnlyPermissions" }
            }
          }
        },
        {
          "if": { "properties": { "strategy": { "const": "single_writer" } }, "required": ["strategy"] },
          "then": {
            "required": ["writer"],
            "properties": {
              "reviewerPermissions": { "$ref": "#/definitions/readOnlyPermissions" }
            }
          }
        }
      ],
      "properties": {
        "description": {
          "type": "string",
          "description": "Human-readable group purpose for operators reading the config."
        },
        "persist": {
          "type": "boolean",
          "description": "When false, the session resets to defaultGroup after this prompt. Defaults false for single_writer groups."
        },
        "strategy": {
          "type": "string",
          "enum": ["parallel_reports", "single_writer"],
          "default": "parallel_reports",
          "description": "parallel_reports runs read-only agents and synthesizes reports; single_writer allows one named writer."
        },
        "permissions":       { "$ref": "#/definitions/permissions", "description": "Default ACP proxy policy for sub-agents in this group." },
        "reviewerPermissions": { "$ref": "#/definitions/permissions", "description": "ACP proxy policy for the reviewer. Must remain read-only." },
        "writerPermissions":   { "$ref": "#/definitions/permissions", "description": "ACP proxy policy for the named writer in single_writer groups." },
        "writer": {
          "type": "string", "minLength": 1,
          "description": "Name of the single sub-agent allowed to mutate code in a single_writer group."
        },
        "attachApprovedPlanFrom": {
          "type": "string", "minLength": 1,
          "description": "Group name whose approved-plan.md should be auto-attached before this group runs."
        },
        "artifactDir": {
          "$ref": "#/definitions/workspaceRelativePath",
          "description": "Workspace-relative artifact directory override for this group."
        },
        "maxTurns": {
          "type": "integer", "minimum": 1,
          "description": "Review-round limit override for this group."
        },
        "concurrency": { "type": "integer", "minimum": 1,
          "description": "Override global concurrency for this group." },
        "subAgents": {
          "type": "array", "minItems": 1,
          "description": "Agents run for this group before the reviewer synthesizes results.",
          "items": { "$ref": "#/definitions/agentSpec" }
        },
        "reviewer": {
          "$ref": "#/definitions/agentSpec",
          "description": "Agent that reviews and synthesizes sub-agent outputs for this group."
        }
      }
    },

    "permissions": {
      "oneOf": [
        {
          "type": "string",
          "enum": ["read_only", "writer_only", "full", "allow_all"],
          "description": "Named ACP proxy policy shortcut."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "readFiles":  { "type": "boolean", "description": "Allow proxied ACP file-read requests." },
            "writeFiles": { "type": "boolean", "description": "Allow proxied ACP file-write requests." },
            "terminal":   { "type": "boolean", "description": "Allow proxied ACP terminal requests." },
            "mcp":        { "type": "boolean", "description": "Forward MCP servers to agents when child capabilities allow them." },
            "allowUnknownClientRequests": { "type": "boolean",
              "description": "Writer-only escape hatch: when true, unknown (non-fs/terminal/permission) child client methods are forwarded to Zed." }
          }
        }
      ]
    },

    "readOnlyPermissions": {
      "oneOf": [
        {
          "type": "string",
          "enum": ["read_only"],
          "description": "Read-only ACP proxy policy shortcut."
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "readFiles":  { "type": "boolean", "description": "Allow proxied ACP file-read requests." },
            "writeFiles": { "const": false, "description": "Must stay false for read-only groups and reviewers." },
            "terminal":   { "const": false, "description": "Must stay false for read-only groups and reviewers." },
            "mcp":        { "type": "boolean", "description": "Forward MCP servers only when every forwarded server is known read-only." },
            "allowUnknownClientRequests": { "const": false, "description": "Must stay false for read-only groups and reviewers." }
          }
        }
      ]
    },

    "workspaceRelativePath": {
      "type": "string",
      "minLength": 1,
      "pattern": "^(?!/)(?![A-Za-z]:[\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$))(?!.*[\\\\/]{2}).+",
      "description": "Workspace-relative path without absolute roots, empty segments, or .. traversal."
    },

    "agentSpec": {
      "type": "object",
      "required": ["name", "command"],
      "additionalProperties": false,
      "properties": {
        "name":           { "type": "string", "minLength": 1, "description": "Display name used in Zed output and writer matching." },
        "command":        { "type": "string", "minLength": 1, "description": "Executable used to start this ACP agent. Values support {env:ENV_VAR}, ${ENV_VAR}, and whole-string $ENV_VAR expansion." },
        "sandboxCommand": { "type": "string", "minLength": 1,
          "description": "Optional wrapper executable used to sandbox this child process. The real command and args are appended after sandboxArgs." },
        "sandboxArgs":    { "type": "array", "items": { "type": "string" }, "description": "Arguments passed to sandboxCommand before the real agent command and args." },
        "rateLimitKey":   { "type": "string", "minLength": 1, "description": "Name of the rateLimits bucket used by this agent. Defaults to command when omitted." },
        "args":           { "type": "array", "items": { "type": "string" }, "description": "Values support {env:ENV_VAR}, ${ENV_VAR}, and whole-string $ENV_VAR expansion." },
        "env":            { "type": "object", "additionalProperties": { "type": "string" }, "description": "Values support {env:ENV_VAR}, ${ENV_VAR}, and whole-string $ENV_VAR expansion." },
        "passEnv":        { "type": "array", "items": { "type": "string" }, "description": "Environment variable names forwarded from the orchestrator process when envIsolation is true." },
        "envIsolation":   { "type": "boolean", "description": "Per-agent override for environment isolation." },
        "credHome":       { "type": "string", "minLength": 1,
          "description": "Workspace-relative, absolute, or ~/... dir used as HOME for this agent. Isolates credential files." },
        "allowRealHome":  { "type": "boolean",
          "description": "When envIsolation is true and credHome is unset, explicitly allow forwarding the real HOME/XDG directories." },
        "agentTimeoutMs": { "type": "integer", "minimum": 1000, "description": "Per-agent wall-clock timeout override in milliseconds." },
        "maxRetries":     { "type": "integer", "minimum": 0, "description": "Per-agent retry-attempt override for transient failures." },
        "retryDelayMs":   { "type": "integer", "minimum": 0, "description": "Per-agent base retry backoff override in milliseconds." },
        "heartbeatMs":    { "type": "integer", "minimum": 0, "description": "Per-agent still-working ping interval override in milliseconds. 0 disables pings." }
      }
    }
  }
}