@claudexor/schema 1.0.0

package/generated/AgentCapabilityCatalog.schema.json

@@ -0,0 +1,389 @@
+{
+  "$ref": "#/definitions/AgentCapabilityCatalog",
+  "definitions": {
+    "AgentCapabilityCatalog": {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean",
+          "const": true,
+          "description": "Envelope marker (matches the CLI JSON convention)."
+        },
+        "version": {
+          "type": "string",
+          "description": "Claudexor version serving this catalog (compare with CLAUDEXOR_PLUGIN_VERSION to detect plugin skew)."
+        },
+        "generatedAt": {
+          "type": "string",
+          "description": "ISO timestamp when the catalog was composed."
+        },
+        "harnesses": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Harness id (codex, claude, cursor, opencode, raw-api, openrouter, ...)."
+              },
+              "enabled": {
+                "type": "boolean",
+                "description": "False when settings disable this harness (harnesses.<id>.enabled=false) — routing excludes it regardless of doctor status."
+              },
+              "displayName": {
+                "type": "string",
+                "description": "Human display name from the manifest."
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "ok",
+                  "degraded",
+                  "unavailable"
+                ],
+                "description": "Doctor verdict: ok | degraded | unavailable (doctor-backed, cached ~90s)."
+              },
+              "providerFamily": {
+                "type": "string",
+                "enum": [
+                  "openai",
+                  "anthropic",
+                  "google",
+                  "cursor",
+                  "opencode",
+                  "xai",
+                  "local",
+                  "unknown"
+                ],
+                "description": "Vendor family the harness routes to."
+              },
+              "enabledIntents": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Intents the gateway will route to this harness right now."
+              },
+              "disabledIntents": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Intents the doctor disabled (with reasons in `reasons`)."
+              },
+              "reasons": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Human-readable doctor/discovery reasons for degraded or unavailable status."
+              },
+              "configuredModel": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The user's configured per-harness default model, if any (null = engine default routing)."
+              },
+              "configuredModelValid": {
+                "type": [
+                  "boolean",
+                  "null"
+                ],
+                "description": "Strict truth-source check of configuredModel (null when no model is configured)."
+              },
+              "models": {
+                "type": "object",
+                "properties": {
+                  "source": {
+                    "type": "string",
+                    "enum": [
+                      "api",
+                      "manifest",
+                      "none"
+                    ],
+                    "description": "Where the model list comes from: a live vendor API enumeration, the adapter manifest's curated hints, or nothing (model overrides are refused for source=none)."
+                  },
+                  "count": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Number of enumerable models (GET /harnesses/:id/models has the full list)."
+                  },
+                  "verifiedAgainst": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "description": "Vendor CLI version the manifest hints were last verified against (null for api/none sources)."
+                  }
+                },
+                "required": [
+                  "source",
+                  "count",
+                  "verifiedAgainst"
+                ],
+                "additionalProperties": false,
+                "description": "Summary of a harness's model truth source (full list via the models endpoint/verb)."
+              },
+              "webPolicy": {
+                "type": "string",
+                "enum": [
+                  "native",
+                  "tools",
+                  "uncontrolled",
+                  "none"
+                ],
+                "description": "How external web/search is controlled for this harness."
+              },
+              "imageInput": {
+                "type": "string",
+                "enum": [
+                  "file_path",
+                  "base64_stream",
+                  "base64_inline",
+                  "none"
+                ],
+                "description": "Attachment/vision delivery mechanism the adapter supports."
+              },
+              "effortLevels": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": [
+                    "low",
+                    "medium",
+                    "high",
+                    "xhigh",
+                    "max"
+                  ],
+                  "description": "Cross-harness reasoning-effort level, weakest to strongest; adapters declare the subset they support and a shared normalizer clamps requests onto the nearest supported level."
+                },
+                "description": "Reasoning-effort ladder the adapter declares (normalized by the engine)."
+              },
+              "accessProfilesSupported": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": [
+                    "readonly",
+                    "workspace_write",
+                    "full",
+                    "external_sandbox_full",
+                    "inherit_native"
+                  ],
+                  "description": "Filesystem/command access profile for a run: readonly (no writes), workspace_write (writes inside the workspace only), full (unrestricted; requires the per-repo trust allow), external_sandbox_full (full access inside an external sandbox), inherit_native (defer to the harness's own native sandbox settings)."
+                },
+                "description": "Access profiles the adapter can enforce."
+              },
+              "readonlyMechanism": {
+                "type": "string",
+                "enum": [
+                  "fs_sandbox",
+                  "permission_deny",
+                  "tool_allowlist",
+                  "none"
+                ],
+                "description": "HOW read-only is enforced (fs_sandbox | permission_deny | tool_allowlist | none) — none means read-only intent is advisory for this harness."
+              }
+            },
+            "required": [
+              "id",
+              "enabled",
+              "displayName",
+              "status",
+              "providerFamily",
+              "enabledIntents",
+              "disabledIntents",
+              "reasons",
+              "configuredModel",
+              "configuredModelValid",
+              "models",
+              "webPolicy",
+              "imageInput",
+              "effortLevels",
+              "accessProfilesSupported",
+              "readonlyMechanism"
+            ],
+            "additionalProperties": false,
+            "description": "Per-harness live capability row (manifest + doctor + model truth)."
+          },
+          "description": "Live per-harness capabilities (doctor-backed)."
+        },
+        "availableHarnesses": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Convenience: ids with doctor status ok."
+        },
+        "modes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "ask",
+              "plan",
+              "audit",
+              "agent",
+              "orchestrate"
+            ],
+            "description": "Canonical run mode: ask, plan, and audit are read-only; agent writes; orchestrate is the autonomous coordinator intent. Engine strategies (race, attempts, swarm, create) are flags on a mode, not modes."
+          },
+          "description": "Canonical run modes (strategies like --n/--until-clean/--swarm are flags, not modes)."
+        },
+        "runControlKeys": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Accepted POST /runs request keys (derived from the ControlRunStartRequest schema; the CLI/MCP/ACP surfaces project subsets of these)."
+        },
+        "mutability": {
+          "type": "object",
+          "properties": {
+            "readOnlyModes": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/AgentCapabilityCatalog/properties/modes/items"
+              },
+              "description": "Canonical modes that never mutate the project tree (ask/plan/audit; orchestrate in suggest autonomy is also read-only)."
+            },
+            "writeModes": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/AgentCapabilityCatalog/properties/modes/items"
+              },
+              "description": "Canonical modes that may mutate a tree (agent always; orchestrate only above suggest autonomy)."
+            },
+            "isolationKinds": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "envelope",
+                  "live"
+                ]
+              },
+              "description": "Run isolation: envelope = isolated worktree under .claudexor/workspaces (default), live = the project tree itself."
+            },
+            "workspaceModes": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "in_place",
+                  "isolated"
+                ],
+                "description": "Per-thread workspace mode: in_place mutates the live project tree directly (the default); isolated keeps a persistent git worktree per thread that apply merges into the project."
+              },
+              "description": "Thread workspace modes (in_place | isolated)."
+            },
+            "accessProfiles": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/AgentCapabilityCatalog/properties/harnesses/items/properties/accessProfilesSupported/items"
+              },
+              "description": "Access vocabulary; `full` additionally requires the per-repo trust allow (claudexor trust --allow-full-access)."
+            },
+            "applyModes": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "apply",
+                  "commit",
+                  "branch",
+                  "pr"
+                ]
+              },
+              "description": "Delivery modes for applying a run's WorkProduct to the project."
+            }
+          },
+          "required": [
+            "readOnlyModes",
+            "writeModes",
+            "isolationKinds",
+            "workspaceModes",
+            "accessProfiles",
+            "applyModes"
+          ],
+          "additionalProperties": false,
+          "description": "The mutability matrix: every way a Claudexor run can (or cannot) touch a tree, from the schema's closed vocabularies."
+        },
+        "cliCommands": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "CLI verb."
+              },
+              "mutability": {
+                "type": "string",
+                "enum": [
+                  "read",
+                  "write",
+                  "delivery",
+                  "ops"
+                ],
+                "description": "read = never mutates the tree; write = produces tree changes (envelope or live); delivery = moves an existing WorkProduct into the tree/VCS; ops = local config/daemon plumbing."
+              },
+              "stability": {
+                "type": "string",
+                "enum": [
+                  "stable",
+                  "experimental"
+                ],
+                "description": "Contract stability of the verb."
+              },
+              "recovery": {
+                "type": "boolean",
+                "description": "True for post-run recovery verbs (inspect/follow/apply/decision)."
+              }
+            },
+            "required": [
+              "id",
+              "mutability",
+              "stability",
+              "recovery"
+            ],
+            "additionalProperties": false,
+            "description": "CLI verb projection from the command registry (same data `claudexor help --json` serves)."
+          },
+          "description": "CLI verbs with mutability/stability (full flag detail via `claudexor help --json`)."
+        },
+        "mcpTools": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "MCP tool names `claudexor mcp serve` exposes."
+        },
+        "runApplyStates": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "RunApplyState vocabulary an agent can encounter on run results (not_applied | applied | applied_review_blocked | reverted) — distinct from the ApplyEligibility verdict object on run details."
+        }
+      },
+      "required": [
+        "ok",
+        "version",
+        "generatedAt",
+        "harnesses",
+        "availableHarnesses",
+        "modes",
+        "runControlKeys",
+        "mutability",
+        "cliCommands",
+        "mcpTools",
+        "runApplyStates"
+      ],
+      "additionalProperties": false,
+      "description": "Machine-readable capability catalog for external agents — derived, never hand-maintained."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/generated/ApplyEligibility.schema.json

@@ -0,0 +1,44 @@
+{
+  "$ref": "#/definitions/ApplyEligibility",
+  "definitions": {
+    "ApplyEligibility": {
+      "type": "object",
+      "properties": {
+        "eligible": {
+          "type": "boolean",
+          "description": "True when the apply gate would accept this run's patch right now."
+        },
+        "state": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The gate's state classification (e.g. blocked | ungated | review_not_run | no_op | ok) when known."
+        },
+        "reason": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The gate's refusal text when not eligible (null when eligible)."
+        },
+        "requiredAction": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Honest guidance for what actually unblocks apply (typed operator decision, add gates, re-run, or nothing to apply)."
+        }
+      },
+      "required": [
+        "eligible",
+        "state",
+        "reason",
+        "requiredAction"
+      ],
+      "additionalProperties": false,
+      "description": "Derived apply-gate verdict for a run's WorkProduct (single producer in the delivery gate)."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/generated/BudgetLease.schema.json

@@ -0,0 +1,95 @@
+{
+  "$ref": "#/definitions/BudgetLease",
+  "definitions": {
+    "BudgetLease": {
+      "type": "object",
+      "properties": {
+        "lease_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Lease id."
+        },
+        "task_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Task the lease belongs to."
+        },
+        "attempt_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Attempt the lease covers, when scoped to one."
+        },
+        "intent": {
+          "type": "string",
+          "enum": [
+            "plan",
+            "spec",
+            "implement",
+            "create_from_scratch",
+            "repair",
+            "review",
+            "verify",
+            "synthesize",
+            "explain",
+            "audit",
+            "orchestrate"
+          ],
+          "description": "Canonical intent a harness can be assigned for a session (roles are intents, never fixed classes)."
+        },
+        "harness_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Harness the reservation is for."
+        },
+        "model_hint": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "Requested model for the reserved call; null = harness default."
+        },
+        "max_usd": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "default": null,
+          "description": "USD cap reserved for the call; null = no cap."
+        },
+        "reason": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Human-readable reasons the lease was created."
+        },
+        "created_at": {
+          "type": "string",
+          "description": "When the lease was created."
+        },
+        "state": {
+          "type": "string",
+          "enum": [
+            "reserved",
+            "settled",
+            "cancelled"
+          ],
+          "default": "reserved",
+          "description": "Lifecycle state: reserved before work, settled after, or cancelled."
+        }
+      },
+      "required": [
+        "lease_id",
+        "task_id",
+        "intent",
+        "harness_id",
+        "created_at"
+      ],
+      "additionalProperties": false,
+      "description": "A pre-call budget reservation, created before work and settled after; never post-hoc only."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/generated/BudgetObservation.schema.json

@@ -0,0 +1,76 @@
+{
+  "$ref": "#/definitions/BudgetObservation",
+  "definitions": {
+    "BudgetObservation": {
+      "type": "object",
+      "properties": {
+        "harness_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Harness the observation is about."
+        },
+        "ts": {
+          "type": "string",
+          "description": "When the signal was observed."
+        },
+        "quality": {
+          "type": "string",
+          "enum": [
+            "exact",
+            "native",
+            "observed",
+            "manual",
+            "unknown"
+          ],
+          "description": "Quality of a usage/quota signal a harness can emit, from exact vendor accounting through native CLI reporting, engine observation, manual entry, to unknown."
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "spend",
+            "rate_limited",
+            "used_percent",
+            "cooldown",
+            "manual"
+          ],
+          "description": "What was observed: spend, a rate-limit hit, a used-percent reading, a cooldown, or a manual entry."
+        },
+        "usd": {
+          "type": "number",
+          "description": "Observed spend in USD, for spend observations."
+        },
+        "used_percent": {
+          "type": "number",
+          "description": "Consumed share of the rate window (0-100), for used_percent observations."
+        },
+        "resets_at": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "When the rate window resets, when reported."
+        },
+        "cooldown_until": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Until when the harness is in cooldown, when set."
+        },
+        "detail": {
+          "type": "string",
+          "description": "Redacted human-readable detail."
+        }
+      },
+      "required": [
+        "harness_id",
+        "ts",
+        "quality",
+        "kind"
+      ],
+      "additionalProperties": false,
+      "description": "An observed quota/usage signal (rate-limit error, used-percent, reset hint) recorded in the budget ledger."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}