{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://livesport.github.io/homer/schemas/latest/homer-agent.schema.json",
  "title": "Homer Agent",
  "description": "Definition of a single Homer agent (JSON or YAML). YAML files may use kaml tags (!<cmd>, !<script>, !<claude>, !<codex>, !<langgraph>, !<runnerCmd>, !<agent>, !<pass>, !<jsonPath>, !<regex>, !<prompt>, !<langfuse>) instead of an explicit type property.",
  "type": "object",
  "additionalProperties": false,
  "required": ["name", "commands"],
  "not": {
    "allOf": [
      { "required": ["runner"] },
      { "required": ["runnerTags"], "properties": { "runnerTags": { "minItems": 1 } } }
    ]
  },
  "properties": {
    "name": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" },
    "description": { "type": "string" },
    "group": {
      "type": ["string", "null"],
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F-\\u009F]+$",
      "description": "Optional operator-facing label for this agent. The console's Agents page renders an \"All\" tab plus one tab per distinct group, so related agents can be browsed together. Omitted or null = ungrouped; ungrouped agents appear under \"All\" only. Must be non-blank, at most 64 characters, and free of control characters."
    },
    "workspace": { "$ref": "#/$defs/Workspace" },
    "commands": {
      "type": "array",
      "minItems": 1,
      "items": { "$ref": "#/$defs/Command" }
    },
    "onStop": {
      "type": "array",
      "maxItems": 10,
      "items": { "$ref": "#/$defs/Command" },
      "description": "Steps run once, in order, after the run is stopped gracefully — by a step's own `timeout` with `onTimeout: stop`, or by the runner's soft run deadline. Each receives the HMR_STOP_* environment and runs under the run's remaining deadline. The first stop step that fails or times out ends the rest. At most 10 steps. See AGENT.md → Graceful stop."
    },
    "env": {
      "type": "object",
      "description": "Per-agent environment. Values support @SYSENV:VAR_NAME references.",
      "additionalProperties": { "type": "string" }
    },
    "inputs": {
      "type": ["array", "null"],
      "items": { "$ref": "#/$defs/Param" }
    },
    "queryParams": {
      "type": ["array", "null"],
      "items": { "$ref": "#/$defs/Param" },
      "deprecated": true,
      "description": "Deprecated alias for `inputs`. New configs should use `inputs`."
    },
    "lockStrategy": { "$ref": "#/$defs/LockStrategy" },
    "cron": { "$ref": "#/$defs/CronConfig" },
    "maxParallelRuns": { "type": "integer", "minimum": 1, "default": 10 },
    "onMaxParallelRuns": {
      "type": "string",
      "enum": ["WAIT", "REJECT"],
      "default": "WAIT"
    },
    "maxQueuedRuns": {
      "type": ["integer", "null"],
      "minimum": 0,
      "default": null,
      "description": "Under onMaxParallelRuns: WAIT, the maximum number of runs that may be queued waiting for a parallel-run slot. Null (default) = unbounded; a non-null value fails the surplus run once the queue is full. No effect under REJECT."
    },
    "runner": {
      "type": "string",
      "minLength": 1,
      "description": "Alias of the execution backend to use. Omitted = 'local' (built-in, Homer's host). Other aliases must match a key in AppConfig.runners. Mutually exclusive with runnerTags. See ADR-0066."
    },
    "runnerTags": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$" },
      "maxItems": 32,
      "uniqueItems": true,
      "description": "Select a runner by tags: any configured runner whose tags contain every listed tag may take the run. Mutually exclusive with runner. See ADR-0066."
    },
    "runnerClaimTimeoutSec": {
      "type": ["integer", "null"],
      "minimum": 1,
      "description": "Seconds a run waits for a runner to claim it before failing; null = server.runnerClaimTimeoutSec (default 300)."
    },
    "runnerAffinity": {
      "type": ["object", "null"],
      "additionalProperties": false,
      "required": ["group", "waitSec"],
      "description": "Opt-in preference for the runner instance that already holds this flow's host-local caches. Soft: it only orders runners that already match the agent's runner/runnerTags filter, and never widens it. See ADR-0099.",
      "properties": {
        "group": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$",
          "description": "Free label naming one cache set. The preference key is the run's flow root plus this group, so the same group in another flow is a different key."
        },
        "waitSec": {
          "type": "integer",
          "minimum": 1,
          "maximum": 86400,
          "description": "Seconds a run waits for its preferred instance before any matching runner may take it. The run's claim TTL bounds the whole wait."
        }
      }
    },
    "inputSchema": {
      "type": ["object", "null"],
      "description": "JSON Schema (Draft 2020-12) validating the JSON request body of POST /api/v1/agent/{name}. A violation is rejected with HTTP 422 before the process is spawned."
    },
    "mcp": { "$ref": "#/$defs/AgentMcpConfig" },
    "dispatch": { "$ref": "#/$defs/AgentDispatchConfig" },
    "continuation": { "$ref": "#/$defs/AgentContinuationConfig" },
    "cooldown": { "$ref": "#/$defs/Cooldown" },
    "telemetry": { "$ref": "#/$defs/AgentTelemetry" },
    "tags": { "$ref": "#/$defs/Tags" },
    "hooks": {
      "type": "array",
      "maxItems": 16,
      "default": [],
      "description": "Status hooks: each entry is a one-key object mapping a run status of THIS agent to the agent Homer starts when a run of this agent reaches it, from every start path (cron, HTTP, MCP, console retry, sub-run). The hook run belongs to the triggering run's owner and is bounded by server.hooks. A status may be listed more than once to fan out. The target must be a loaded agent, must not be this agent, and must not form a hook cycle. See ADR-0107.",
      "items": {
        "type": "object",
        "minProperties": 1,
        "maxProperties": 1,
        "propertyNames": { "enum": ["CREATED", "WORKING", "FINISHED", "KILLED", "FAILED", "UNKNOWN"] },
        "additionalProperties": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" }
      }
    },
    "artifactNameTemplate": {
      "type": "string",
      "minLength": 1,
      "default": "cmd_{{HMR_CMD_INDEX}}",
      "description": "Template for the stem of the autogenerated per-command stdout/stderr artifact files (Homer appends .out/.err). Rendered per command and per attempt via {{VAR}} substitution against the workspace env plus two synthetic, template-only variables that are never exported to the process env: HMR_CMD_INDEX (zero-based command index) and HMR_CMD_ATTEMPT (zero-based retry attempt within the command; always 0 outside a Claude retry). The default renders the same path for every attempt, preserving the pre-existing cmd_N.out/.err behavior."
    }
  },
  "$defs": {
    "AgentTelemetry": {
      "type": "object",
      "additionalProperties": false,
      "description": "Everything this agent decides about its own telemetry. Server-wide openTelemetryExport still gates all of it.",
      "properties": {
        "export": {
          "type": "string",
          "enum": ["ALL", "OFF"],
          "default": "ALL",
          "description": "Whether this agent's runs reach the collector. OFF mutes the whole trace, including every descendant span."
        },
        "traceTags": {
          "type": "array",
          "items": { "type": "string" },
          "default": [],
          "deprecated": true,
          "description": "DEPRECATED: use tags.fromInputs instead. Kept one release as an alias meaning tags.fromInputs; agent load logs a warning. paramNames of declared inputs whose resolved values become 'paramName:value' tags on the run trace."
        }
      }
    },
    "Tags": {
      "type": "object",
      "additionalProperties": false,
      "description": "A run's subject tags — what it ran over — so it is findable by GET /api/v1/status/all?tag=key:value. Also exported as Langfuse trace tags.",
      "properties": {
        "fromInputs": {
          "type": "array",
          "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$" },
          "default": [],
          "description": "paramNames of declared inputs whose resolved values become 'paramName:value' tags at run start. Each name must match a declared, non-secret input whose paramName matches ^[A-Za-z0-9._-]{1,64}$ (it becomes the tag key), checked at agent load. Values must match ^[A-Za-z0-9._-]{1,128}$; an out-of-charset or oversized value is dropped (never truncated). Prefer inputs with a bounded value set."
        },
        "runtime": {
          "type": "array",
          "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$" },
          "default": [],
          "description": "Tag keys a running command may fill later via the homer-tag helper (POST /api/v1/callback/tags), for facts not known until the run starts. Each key must match ^[A-Za-z0-9._-]{1,64}$ and must be disjoint from every fromInputs name; overlap is a load error."
        }
      }
    },
    "Cooldown": {
      "type": "object",
      "additionalProperties": false,
      "description": "Minimum spacing between runs of this agent. At least one of minInterval and afterFailure must be set. Durations use the purgeAfter grammar (m/h/d/w). By default both windows are counted per agent; key narrows them to one subject.",
      "minProperties": 1,
      "properties": {
        "minInterval": {
          "type": "string",
          "pattern": "^[0-9]+[mhdw]$",
          "description": "Minimum time since the previous run of this agent started."
        },
        "afterFailure": {
          "type": "string",
          "pattern": "^[0-9]+[mhdw]$",
          "description": "Minimum time since the previous run ended, applied only when that run FAILED."
        },
        "key": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256,
          "description": "Optional {{VAR}} template naming the subject both windows are counted per (a merge request, a branch, a ticket), rendered at start from the run's env and resolved inputs. A placeholder that does not resolve fails the run before it starts, never as a shared literal. The rendered value must be at most 128 characters of [A-Za-z0-9._:/-] and must not reference a secret input."
        }
      }
    },
    "AgentMcpConfig": {
      "type": "object",
      "additionalProperties": false,
      "description": "Opt-in exposure of this agent as an MCP tool on the /mcp endpoint (requires server.mcp.enabled).",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": false,
          "description": "Expose this agent as an MCP tool."
        }
      }
    },
    "AgentDispatchConfig": {
      "type": "object",
      "additionalProperties": false,
      "description": "Opt-in: allow this agent to be the target of an ask-and-dispatch dispatch.",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": false,
          "description": "Allow this agent to be started by ask-and-dispatch."
        }
      }
    },
    "AgentContinuationConfig": {
      "type": "object",
      "additionalProperties": false,
      "description": "Opt-in: a continuation fired to this agent from a run of the same agent inherits that run's resolved inputs.",
      "properties": {
        "inheritInputs": {
          "type": "boolean",
          "default": false,
          "description": "Merge the origin run's stored inputs under the continuation's own params and resume payload, so a resumed segment keeps a real lock key and its tags.fromInputs tags. The continuation's own params and the resume/answer param win on conflict; a continuation to a different agent inherits nothing."
        }
      }
    },
    "Workspace": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "path": { "type": "string" },
        "cleanAfterFinish": { "type": "boolean", "default": true },
        "purgeAfter": {
          "type": "string",
          "pattern": "^[0-9]+[mhdw]$",
          "description": "Deletes the workspace directory this long after the run ends. The record dies with it unless `retain` extends it."
        },
        "retain": {
          "type": "object",
          "description": "What outlives purgeAfter: the run's record for recordFor, plus artifact files matching the artifacts globs, kept in place for the same window. Omitted = record and directory die together.",
          "properties": {
            "recordFor": {
              "type": "string",
              "pattern": "^[0-9]+[mhdw]$",
              "description": "How long the run's record (status, steps, exit codes, cost) survives the workspace purge. Must be >= purgeAfter."
            },
            "artifacts": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Globs relative to the artifacts dir naming files that survive until the record dies, served by the same artifact routes. Bounded per run by server.maxRetainedArtifactBytes. Requires workspace.path to contain {{HMR_PROCESS_ID}} (per-run directory)."
            }
          },
          "required": ["recordFor"],
          "additionalProperties": false
        }
      }
    },
    "LockStrategy": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "key": { "type": "string", "description": "Lock key; supports template vars." },
        "onCollision": {
          "type": "string",
          "enum": ["KILL_OLD_RUN_CURRENT", "SKIP_CURRENT", "WAIT"],
          "default": "WAIT"
        },
        "acceptParentLock": {
          "type": "boolean",
          "default": false,
          "description": "When true and this run's resolved lock key is already held by an ancestor in its invocation chain, skip lock acquisition (pass-through) so a flow cannot self-collide on a shared key. Parallel-run limits still apply."
        }
      }
    },
    "CronConfig": {
      "type": "object",
      "additionalProperties": false,
      "required": ["expression"],
      "properties": {
        "expression": {
          "type": "string",
          "description": "Standard 5-field UNIX cron expression."
        },
        "timezone": { "type": "string", "default": "UTC" }
      }
    },
    "Command": {
      "description": "A single command in the agent pipeline. JSON form uses a `type` discriminator; YAML form uses kaml tags.",
      "oneOf": [
        { "$ref": "#/$defs/Cmd" },
        { "$ref": "#/$defs/Script" },
        { "$ref": "#/$defs/Claude" },
        { "$ref": "#/$defs/Codex" },
        { "$ref": "#/$defs/Opencode" },
        { "$ref": "#/$defs/RunAgent" },
        { "$ref": "#/$defs/LangGraph" },
        { "$ref": "#/$defs/RunnerCmd" }
      ]
    },
    "OnTimeout": {
      "description": "What a step's own `timeout` does when it expires. `fail` (the default) fails the run at once; `stop` stops the run gracefully, running the agent's `onStop:` steps first. `stop` requires `onStop:` to be declared.",
      "type": "string",
      "enum": ["fail", "stop"],
      "default": "fail"
    },
    "CommandCommonProps": {
      "type": "object",
      "properties": {
        "label": { "type": "string" },
        "timeout": { "type": "integer", "minimum": 0, "default": 60 },
        "onTimeout": { "$ref": "#/$defs/OnTimeout" },
        "interruptGraceSeconds": { "type": "integer", "minimum": 0, "maximum": 600, "default": 30 },
        "continueIfFail": { "type": "boolean", "default": false },
        "finishExitCode": { "type": ["integer", "null"] },
        "resultEnvParam": {
          "type": "array",
          "items": { "$ref": "#/$defs/ResultEnvParam" }
        },
        "when": { "$ref": "#/$defs/When" }
      }
    },
    "When": {
      "description": "Conditional execution predicate. Each expression is run as `bash -c <expr>`; exit 0 = true, 1 = false, ≥2 = eval error (fails the agent). Per-expression timeout is 5 s. A scalar string is shorthand for `{all: [<string>]}`.",
      "oneOf": [
        { "type": "string", "minLength": 1 },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["all"],
          "properties": {
            "all": {
              "type": "array",
              "minItems": 1,
              "items": { "type": "string", "minLength": 1 }
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["any"],
          "properties": {
            "any": {
              "type": "array",
              "minItems": 1,
              "items": { "type": "string", "minLength": 1 }
            }
          }
        }
      ]
    },
    "Cmd": {
      "type": "object",
      "required": ["cmd"],
      "not": { "required": ["prompt"] },
      "allOf": [{ "$ref": "#/$defs/CommandCommonProps" }],
      "properties": {
        "type": { "const": "cmd" },
        "cmd": {
          "description": "Either a scalar string (POSIX-tokenized) or an explicit array of argv strings.",
          "oneOf": [
            { "type": "string", "minLength": 1 },
            {
              "type": "array",
              "minItems": 1,
              "items": { "type": "string" }
            }
          ]
        },
        "label": { "type": "string" },
        "timeout": { "type": "integer", "minimum": 0 },
        "continueIfFail": { "type": "boolean" },
        "onTimeout": { "$ref": "#/$defs/OnTimeout" },
        "interruptGraceSeconds": { "type": "integer", "minimum": 0, "maximum": 600, "default": 30 },
        "finishExitCode": { "type": ["integer", "null"] },
        "resultEnvParam": {
          "type": "array",
          "items": { "$ref": "#/$defs/ResultEnvParam" }
        },
        "when": { "$ref": "#/$defs/When" }
      },
      "additionalProperties": false
    },
    "Script": {
      "type": "object",
      "required": ["content"],
      "properties": {
        "type": { "const": "script" },
        "content": { "type": "string" },
        "shell": { "type": "string", "default": "sh" },
        "label": { "type": "string" },
        "timeout": { "type": "integer", "minimum": 0 },
        "continueIfFail": { "type": "boolean" },
        "onTimeout": { "$ref": "#/$defs/OnTimeout" },
        "interruptGraceSeconds": { "type": "integer", "minimum": 0, "maximum": 600, "default": 30 },
        "finishExitCode": { "type": ["integer", "null"] },
        "resultEnvParam": {
          "type": "array",
          "items": { "$ref": "#/$defs/ResultEnvParam" }
        },
        "when": { "$ref": "#/$defs/When" }
      },
      "additionalProperties": false
    },
    "Claude": {
      "type": "object",
      "required": ["prompt", "options"],
      "properties": {
        "type": { "const": "claude" },
        "cmd": { "type": "string", "default": "claude", "description": "CLI binary (argv[0]). {{VAR}} is substituted; referencing an input envName fails the agent at load." },
        "prompt": { "$ref": "#/$defs/LlmPrompt" },
        "options": { "$ref": "#/$defs/ClaudeCmdOptions" },
        "retry": { "$ref": "#/$defs/LlmRetry" },
        "label": { "type": "string" },
        "timeout": { "type": "integer", "minimum": 0 },
        "continueIfFail": { "type": "boolean" },
        "onTimeout": { "$ref": "#/$defs/OnTimeout" },
        "interruptGraceSeconds": { "type": "integer", "minimum": 0, "maximum": 600, "default": 30 },
        "finishExitCode": { "type": ["integer", "null"] },
        "resultEnvParam": {
          "type": "array",
          "items": { "$ref": "#/$defs/ResultEnvParam" }
        },
        "when": { "$ref": "#/$defs/When" },
        "escalate": { "type": "array", "maxItems": 3, "items": { "$ref": "#/$defs/LlmEscalation" }, "description": "Stronger models to rerun the step on when a tier's when predicate judges the previous outcome bad. Empty or absent: the step runs once. See ADR-0079." }
      },
      "additionalProperties": false
    },
    "LlmRetry": {
      "type": "object",
      "additionalProperties": false,
      "description": "Retry policy for an LLM command (claude, codex or opencode). Retries fire on non-zero exit OR on output validation failure (MalformedLlmOutputException); a terminal cap stop the command opted into (Claude's maxTurnsExitCode) is never retried. Other exceptions propagate immediately.",
      "properties": {
        "attempts": {
          "type": "integer",
          "minimum": 1,
          "default": 1,
          "description": "Total attempts including the first; 1 = no retry."
        },
        "baseDelayMs": {
          "type": "integer",
          "minimum": 0,
          "default": 1000,
          "description": "Base delay in ms; subsequent attempts back off as min(maxDelayMs, baseDelayMs * 2^(attempt-1))."
        },
        "maxDelayMs": {
          "type": "integer",
          "minimum": 0,
          "default": 30000,
          "description": "Hard cap on the per-attempt backoff delay."
        }
      }
    },
    "LlmEscalation": {
      "type": "object",
      "additionalProperties": false,
      "required": ["model", "when"],
      "description": "One escalation tier of an LLM command (claude, codex or opencode): rerun the same prompt on model when the when predicate, evaluated after the previous tier with HMR_LLM_OUTCOME and HMR_LLM_EXIT_CODE set, is true. See ADR-0079.",
      "properties": {
        "model": { "type": "string", "minLength": 1, "description": "Model for this tier. {{VAR}} is substituted." },
        "options": { "type": "array", "items": { "type": "string" }, "description": "Replaces the step's raw CLI options list for this tier (e.g. [] to drop --continue). Absent: the step's list is kept." },
        "when": { "$ref": "#/$defs/When" }
      }
    },
    "Codex": {
      "type": "object",
      "required": ["prompt"],
      "properties": {
        "type": { "const": "codex" },
        "cmd": { "type": "string", "default": "codex", "description": "CLI binary (argv[0]). {{VAR}} is substituted; referencing an input envName fails the agent at load." },
        "prompt": { "$ref": "#/$defs/LlmPrompt" },
        "options": { "$ref": "#/$defs/CodexCmdOptions" },
        "retry": { "$ref": "#/$defs/LlmRetry" },
        "label": { "type": "string" },
        "timeout": { "type": "integer", "minimum": 0 },
        "continueIfFail": { "type": "boolean" },
        "onTimeout": { "$ref": "#/$defs/OnTimeout" },
        "interruptGraceSeconds": { "type": "integer", "minimum": 0, "maximum": 600, "default": 30 },
        "finishExitCode": { "type": ["integer", "null"] },
        "resultEnvParam": {
          "type": "array",
          "items": { "$ref": "#/$defs/ResultEnvParam" }
        },
        "when": { "$ref": "#/$defs/When" },
        "escalate": { "type": "array", "maxItems": 3, "items": { "$ref": "#/$defs/LlmEscalation" }, "description": "Stronger models to rerun the step on when a tier's when predicate judges the previous outcome bad. Empty or absent: the step runs once. See ADR-0079." }
      },
      "additionalProperties": false
    },
    "CodexCmdOptions": {
      "type": "object",
      "additionalProperties": false,
      "description": "Options for the codex command, mapped 1:1 to `codex exec` CLI flags. The executor always appends `--json --color never` and passes the prompt via stdin.",
      "properties": {
        "model": { "type": ["string", "null"] },
        "profile": { "type": ["string", "null"] },
        "sandbox": {
          "type": ["string", "null"],
          "enum": ["read-only", "workspace-write", "danger-full-access", null],
          "description": "Sandbox policy for model-generated shell commands. Takes precedence over dangerouslyBypassApprovalsAndSandbox when both are set."
        },
        "cd": {
          "type": ["string", "null"],
          "description": "Working root for the agent (--cd)."
        },
        "addDir": { "type": ["string", "null"] },
        "skipGitRepoCheck": { "type": "boolean", "default": false },
        "ephemeral": {
          "type": "boolean",
          "default": false,
          "description": "Run without persisting Codex session files to disk."
        },
        "ignoreUserConfig": { "type": "boolean", "default": false },
        "ignoreRules": { "type": "boolean", "default": false },
        "outputSchema": {
          "type": ["string", "null"],
          "description": "Path to a JSON Schema file describing the model's final response shape."
        },
        "outputLastMessage": {
          "type": ["string", "null"],
          "description": "File where the last agent message is written (--output-last-message)."
        },
        "dangerouslyBypassApprovalsAndSandbox": {
          "type": "boolean",
          "default": false,
          "description": "Security: opt-in. Skips all confirmation prompts and sandboxing; only safe in isolated/sandboxed environments."
        },
        "config": {
          "type": ["array", "null"],
          "items": { "type": "string" },
          "description": "Repeated `--config key=value` overrides (TOML values)."
        },
        "options": {
          "type": ["array", "null"],
          "items": { "type": "string" },
          "description": "Raw CLI arguments appended before the hardcoded tail."
        }
      }
    },
    "Opencode": {
      "type": "object",
      "required": ["prompt"],
      "properties": {
        "type": { "const": "opencode" },
        "cmd": { "type": "string", "default": "opencode", "description": "CLI binary (argv[0]). {{VAR}} is substituted; referencing an input envName fails the agent at load." },
        "prompt": { "$ref": "#/$defs/LlmPrompt" },
        "options": { "$ref": "#/$defs/OpencodeCmdOptions" },
        "retry": { "$ref": "#/$defs/LlmRetry" },
        "label": { "type": "string" },
        "timeout": { "type": "integer", "minimum": 0 },
        "continueIfFail": { "type": "boolean" },
        "onTimeout": { "$ref": "#/$defs/OnTimeout" },
        "interruptGraceSeconds": { "type": "integer", "minimum": 0, "maximum": 600, "default": 30 },
        "finishExitCode": { "type": ["integer", "null"] },
        "resultEnvParam": {
          "type": "array",
          "items": { "$ref": "#/$defs/ResultEnvParam" }
        },
        "when": { "$ref": "#/$defs/When" },
        "escalate": { "type": "array", "maxItems": 3, "items": { "$ref": "#/$defs/LlmEscalation" }, "description": "Stronger models to rerun the step on when a tier's when predicate judges the previous outcome bad. Empty or absent: the step runs once. See ADR-0079." }
      },
      "additionalProperties": false
    },
    "OpencodeCmdOptions": {
      "type": "object",
      "additionalProperties": false,
      "description": "Options for the opencode command, mapped 1:1 to `opencode run` CLI flags. The executor always appends `--format json` and passes the prompt via stdin.",
      "properties": {
        "model": { "type": ["string", "null"], "description": "Model in opencode's provider/model form (--model)." },
        "agent": { "type": ["string", "null"], "description": "Agent to run (--agent)." },
        "dir": { "type": ["string", "null"], "description": "Directory to start opencode in (--dir)." },
        "file": {
          "type": ["array", "null"],
          "items": { "type": "string" },
          "description": "Repeated `--file` attachments."
        },
        "auto": {
          "type": "boolean",
          "default": false,
          "description": "Security: opt-in. Auto-approves every permission the opencode configuration does not explicitly deny; only safe in isolated/sandboxed environments."
        },
        "options": {
          "type": ["array", "null"],
          "items": { "type": "string" },
          "description": "Raw CLI arguments appended before the hardcoded tail."
        }
      }
    },
    "RunAgent": {
      "type": "object",
      "required": ["agentName"],
      "properties": {
        "type": { "const": "agent" },
        "agentName": { "type": "string", "minLength": 1 },
        "queryParams": {
          "type": "array",
          "items": { "$ref": "#/$defs/AgentCommandParam" }
        },
        "label": { "type": "string" },
        "timeout": { "type": "integer", "minimum": 0 },
        "continueIfFail": { "type": "boolean" },
        "onTimeout": { "$ref": "#/$defs/OnTimeout" },
        "interruptGraceSeconds": { "type": "integer", "minimum": 0, "maximum": 600, "default": 30 },
        "finishExitCode": { "type": ["integer", "null"] },
        "resultEnvParam": {
          "type": "array",
          "items": { "$ref": "#/$defs/ResultEnvParam" }
        },
        "when": { "$ref": "#/$defs/When" }
      },
      "additionalProperties": false
    },
    "LangGraph": {
      "type": "object",
      "required": ["module"],
      "description": "Thin launcher for the Python homer_langgraph runtime. The agent must set dispatch.enabled: true (enforced at load time). See ADR-0024.",
      "properties": {
        "type": { "const": "langgraph" },
        "module": { "type": "string", "minLength": 1 },
        "python": { "type": "string", "default": "python3" },
        "inputEnv": { "type": "string", "default": "HMR_LG_INPUT" },
        "label": { "type": "string" },
        "timeout": { "type": "integer", "minimum": 0 },
        "continueIfFail": { "type": "boolean" },
        "onTimeout": { "$ref": "#/$defs/OnTimeout" },
        "interruptGraceSeconds": { "type": "integer", "minimum": 0, "maximum": 600, "default": 30 },
        "finishExitCode": { "type": ["integer", "null"] },
        "resultEnvParam": {
          "type": "array",
          "items": { "$ref": "#/$defs/ResultEnvParam" }
        },
        "when": { "$ref": "#/$defs/When" }
      },
      "additionalProperties": false
    },
    "RunnerCmd": {
      "type": "object",
      "required": ["runner", "execute"],
      "description": "Runs one command on any configured runner alias with check -> syncToRemote -> execute -> syncFromRemote phases. Agents containing this command must run on runner: local. See ADR-0034.",
      "properties": {
        "type": { "const": "runnerCmd" },
        "runner": { "type": "string", "minLength": 1, "description": "Runner alias from server config, or \"local\"" },
        "execute": { "type": "string", "minLength": 1, "description": "Script piped to `<shell> -s -` on the target" },
        "shell": { "type": "string", "default": "sh" },
        "check": {
          "type": "array",
          "items": { "type": "string", "minLength": 1 },
          "description": "Pre-flight expressions run on the target via `<shell> -c`; each must exit 0"
        },
        "syncToRemote": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Workdir-relative paths uploaded to the target before execute"
        },
        "syncFromRemote": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Target-workdir-relative paths downloaded back after successful execute"
        },
        "label": { "type": "string" },
        "timeout": { "type": "integer", "minimum": 0 },
        "continueIfFail": { "type": "boolean" },
        "onTimeout": { "$ref": "#/$defs/OnTimeout" },
        "interruptGraceSeconds": { "type": "integer", "minimum": 0, "maximum": 600, "default": 30 },
        "finishExitCode": { "type": ["integer", "null"] },
        "resultEnvParam": {
          "type": "array",
          "items": { "$ref": "#/$defs/ResultEnvParam" }
        },
        "when": { "$ref": "#/$defs/When" }
      },
      "additionalProperties": false
    },
    "LlmPrompt": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["prompt"],
          "properties": {
            "type": { "const": "prompt" },
            "prompt": { "type": "string" }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["promptName"],
          "properties": {
            "type": { "const": "langfuse" },
            "promptName": { "type": "string" },
            "version": { "type": ["integer", "null"] },
            "label": { "type": ["string", "null"] }
          }
        }
      ]
    },
    "ClaudeCmdOptions": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "agent": { "type": ["string", "null"] },
        "agents": {
          "type": ["object", "null"],
          "description": "Map of subagent name to subagent definition. Serialized to the --agents flag as a JSON object.",
          "additionalProperties": { "$ref": "#/$defs/ClaudeSubagent" }
        },
        "maxTurns": { "type": "integer", "minimum": 1, "default": 40 },
        "maxTurnsExitCode": { "type": ["integer", "null"], "minimum": 1, "maximum": 255, "default": null, "description": "Opt-in: return this exit code when Claude stops at maxTurns (result subtype error_max_turns) instead of failing the run; combine with continueIfFail and a RESULT_CODE resultEnvParam so a later step can decide." },
        "maxMcpOutputTokens": { "type": ["integer", "null"] },
        "model": { "type": ["string", "null"] },
        "fallbackModel": { "type": ["string", "null"] },
        "systemPrompt": { "type": ["string", "null"] },
        "systemPromptFile": { "type": ["string", "null"] },
        "appendSystemPrompt": { "type": ["string", "null"] },
        "appendSystemPromptFile": { "type": ["string", "null"] },
        "permissionMode": {
          "type": ["string", "null"],
          "enum": ["default", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions", null]
        },
        "permissionPromptTool": { "type": ["string", "null"] },
        "maxBudgetUsd": { "type": ["number", "null"] },
        "sessionId": { "type": ["string", "null"] },
        "addDir": { "type": ["string", "array", "null"], "items": { "type": "string" } },
        "allowedTools": {
          "type": ["array", "null"],
          "items": { "type": "string" }
        },
        "disallowedTools": {
          "type": ["array", "null"],
          "items": { "type": "string" }
        },
        "mcpConfig": { "type": ["string", "array", "null"], "items": { "type": "string" } },
        "strictMcpConfig": { "type": "boolean", "default": false },
        "includeHookEvents": { "type": "boolean", "default": false },
        "includePartialMessages": { "type": "boolean", "default": false },
        "inputFormat": { "type": ["string", "null"], "enum": ["text", "stream-json", null] },
        "pluginDir": { "type": ["string", "array", "null"], "items": { "type": "string" } },
        "pluginUrl": { "type": ["string", "array", "null"], "items": { "type": "string" } },
        "file": { "type": ["string", "array", "null"], "items": { "type": "string" } },
        "settings": { "type": ["string", "null"] },
        "settingSources": {
          "type": ["array", "null"],
          "items": {
            "type": "string",
            "enum": ["user", "project", "local"]
          }
        },
        "tools": {
          "type": ["array", "null"],
          "items": { "type": "string" }
        },
        "disableSlashCommands": { "type": "boolean", "default": false },
        "effort": {
          "type": ["string", "null"],
          "enum": ["low", "medium", "high", "xhigh", "max", null]
        },
        "excludeDynamicSystemPromptSections": { "type": "boolean", "default": false },
        "noSessionPersistence": { "type": "boolean", "default": false },
        "bare": { "type": "boolean", "default": false },
        "jsonSchema": { "type": ["string", "null"] },
        "betas": { "type": ["string", "null"] },
        "debugFile": { "type": ["string", "null"] },
        "dangerouslySkipPermissions": { "type": "boolean", "default": false },
        "options": {
          "type": ["array", "null"],
          "items": { "type": "string" }
        }
      }
    },
    "ClaudeSubagent": {
      "type": "object",
      "additionalProperties": false,
      "required": ["prompt"],
      "properties": {
        "prompt": { "type": "string" },
        "description": { "type": ["string", "null"] },
        "tools": {
          "type": ["array", "null"],
          "items": { "type": "string" }
        },
        "model": { "type": ["string", "null"] }
      }
    },
    "ResultEnvParam": {
      "type": "object",
      "additionalProperties": false,
      "required": ["src", "envName"],
      "properties": {
        "src": {
          "type": "string",
          "enum": ["STD_OUT", "STD_ERR", "RESULT_CODE"]
        },
        "envName": { "type": "string", "minLength": 1 },
        "transformer": { "$ref": "#/$defs/ResultTransformer" }
      }
    },
    "ResultTransformer": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "properties": { "type": { "const": "pass" } }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["path"],
          "properties": {
            "type": { "const": "jsonPath" },
            "path": { "type": "string", "minLength": 1 }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["regex"],
          "properties": {
            "type": { "const": "regex" },
            "regex": { "type": "string", "minLength": 1 },
            "group": { "type": ["integer", "null"], "minimum": 0 }
          }
        }
      ]
    },
    "AgentCommandParam": {
      "type": "object",
      "additionalProperties": false,
      "required": ["envName", "paramName"],
      "properties": {
        "envName": { "type": "string" },
        "paramName": { "type": "string" },
        "transformer": { "$ref": "#/$defs/ResultTransformer" }
      }
    },
    "Param": {
      "type": "object",
      "additionalProperties": false,
      "required": ["paramName"],
      "properties": {
        "paramName": { "type": "string", "minLength": 1 },
        "envName": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
        "src": {
          "type": "string",
          "enum": ["query", "body", "header"],
          "default": "query"
        },
        "type": {
          "type": "string",
          "enum": ["STRING", "NUMBER", "ANY", "string", "integer", "number", "boolean"],
          "default": "STRING",
          "description": "Lowercase values are the typed generation (constraints below apply). Uppercase STRING/NUMBER/ANY are the deprecated legacy generation: STRING rejects spaces, NUMBER is Int-only."
        },
        "required": { "type": "boolean", "default": true },
        "transformer": { "$ref": "#/$defs/ParamTransformer" },
        "secret": {
          "type": "boolean",
          "default": false,
          "description": "Redact this input's value in API responses and telemetry, and drop its default and values from the agents summary and MCP tool schema. The value still reaches the run environment and the server database."
        },
        "values": {
          "type": "array",
          "items": { "type": ["string", "number"] },
          "description": "Typed generation only (string/integer/number): the value must equal one of these. Numeric comparison for integer/number. The Kotlin field is a list of strings — JSON agent files must quote each entry; YAML may use bare scalars. On a secret input the list is still enforced, but it is dropped from the agents summary and MCP tool schema, and a value outside it gets a generic denial that never lists the set."
        },
        "pattern": {
          "type": "string",
          "description": "Typed generation, string only: regex the whole value must match."
        },
        "min": { "type": "number", "description": "Typed generation, integer/number only: inclusive lower bound. Must be integral for integer." },
        "max": { "type": "number", "description": "Typed generation, integer/number only: inclusive upper bound. Must be integral for integer." },
        "minLength": { "type": "integer", "minimum": 0, "description": "Typed generation, string only." },
        "maxLength": { "type": "integer", "minimum": 0, "description": "Typed generation, string only." },
        "default": {
          "type": ["string", "number", "boolean"],
          "description": "Typed generation: value used when this optional param is absent; requires 'required: false'. The Kotlin field is a string — JSON agent files must quote it; YAML may use a bare scalar. On a secret input it is dropped from the agents summary and MCP tool schema."
        }
      }
    },
    "ParamTransformer": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "properties": { "type": { "const": "pass" } }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["path"],
          "properties": {
            "type": { "const": "jsonPath" },
            "path": { "type": "string", "minLength": 1 }
          }
        }
      ]
    }
  }
}
