@claudexor/schema 1.0.0

package/generated/GlobalConfig.schema.json

@@ -0,0 +1,313 @@
+{
+  "$ref": "#/definitions/GlobalConfig",
+  "definitions": {
+    "GlobalConfig": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "number",
+          "const": 1,
+          "default": 1,
+          "description": "Config format version."
+        },
+        "default_portfolio": {
+          "type": "string",
+          "enum": [
+            "daily-rich",
+            "balanced",
+            "cheapest",
+            "strongest",
+            "burn",
+            "subscription-first",
+            "api-overflow",
+            "conserve-claude",
+            "conserve-codex"
+          ],
+          "description": "Budget portfolio used when a run does not specify one.",
+          "default": "subscription-first"
+        },
+        "interaction_timeout_ms": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "default": 900000,
+          "description": "How long an interactive run waits for the user's answer to a harness question before delivering a benign decline and letting the model continue."
+        },
+        "routing": {
+          "type": "object",
+          "properties": {
+            "default_policy": {
+              "type": "string",
+              "enum": [
+                "auto",
+                "primary"
+              ],
+              "description": "Default routing policy: auto (engine picks) or primary (prefer the configured primary harness).",
+              "default": "auto"
+            },
+            "primary_harness": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "default": null,
+              "description": "Global default primary harness; null = engine decides."
+            },
+            "eligible_harnesses": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": [],
+              "description": "Harness pool eligible for routing/races; empty = all available."
+            },
+            "env_inheritance": {
+              "type": "string",
+              "enum": [
+                "mirror_native",
+                "clean"
+              ],
+              "default": "mirror_native",
+              "description": "How the child harness env is built: mirror_native inherits the user's shell env; clean spawns from a minimal allowlist."
+            },
+            "auth_preference": {
+              "type": "string",
+              "enum": [
+                "subscription",
+                "api_key",
+                "auto"
+              ],
+              "description": "Preferred auth route: subscription (native/OAuth session), api_key (a stored API key), or auto (engine picks subscription-first with policy fallback). A preference, not a secret.",
+              "default": "auto"
+            },
+            "quality_priors": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "propertyNames": {
+                "enum": [
+                  "openai",
+                  "anthropic",
+                  "google",
+                  "cursor",
+                  "opencode",
+                  "xai",
+                  "local",
+                  "unknown"
+                ]
+              },
+              "default": {},
+              "description": "Operator-tunable per-provider-family quality priors (0..1) feeding the router; unset families ride the neutral 0.5."
+            }
+          },
+          "additionalProperties": false,
+          "default": {},
+          "description": "Global routing defaults."
+        },
+        "budget": {
+          "type": "object",
+          "properties": {
+            "max_usd_per_run": {
+              "anyOf": [
+                {
+                  "type": "number",
+                  "minimum": 0
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null,
+              "description": "Global USD cap per run; null = no cap."
+            },
+            "estimate_usd_floor": {
+              "type": "number",
+              "minimum": 0,
+              "default": 0.05,
+              "description": "Per-candidate USD reservation floor held against the run cap for every race-wave slot after the first, so a parallel wave cannot blow past the cap between settlements."
+            }
+          },
+          "additionalProperties": false,
+          "default": {},
+          "description": "Global budget limits."
+        },
+        "runtime": {
+          "type": "object",
+          "properties": {
+            "transient_retry": {
+              "type": "object",
+              "properties": {
+                "max_retries": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 5,
+                  "default": 2,
+                  "description": "Maximum retries for a transient failure."
+                },
+                "initial_delay_ms": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "default": 1000,
+                  "description": "Initial retry delay in milliseconds."
+                },
+                "max_delay_ms": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "default": 10000,
+                  "description": "Maximum retry delay in milliseconds."
+                }
+              },
+              "additionalProperties": false,
+              "default": {},
+              "description": "Bounded retry policy for adapter-declared transient failures; user-global only."
+            },
+            "reviewer_timeout_ms": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "default": 600000,
+              "description": "Wall-clock timeout for a reviewer run, in milliseconds."
+            },
+            "harness_inactivity_timeout_ms": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "default": 1200000,
+              "description": "Inactivity watchdog for harness streams: no events for this window aborts the stream and fails the attempt with a typed timeout."
+            }
+          },
+          "additionalProperties": false,
+          "default": {},
+          "description": "Global runtime timeouts and retry policy."
+        },
+        "harnesses": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": true,
+                "description": "Whether the harness participates in routing."
+              },
+              "default_model": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "default": null,
+                "description": "Per-harness default model; null = the harness's own default."
+              },
+              "effort": {
+                "anyOf": [
+                  {
+                    "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."
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Default reasoning effort for the harness; null = harness default.",
+                "default": null
+              },
+              "max_turns": {
+                "anyOf": [
+                  {
+                    "type": "integer",
+                    "exclusiveMinimum": 0
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "Default max agent turns; null = no limit."
+              },
+              "max_rounds": {
+                "anyOf": [
+                  {
+                    "type": "integer",
+                    "exclusiveMinimum": 0
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "Default max convergence rounds; null = engine default."
+              },
+              "max_usd": {
+                "anyOf": [
+                  {
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "Per-harness USD cap; null = no cap."
+              },
+              "tools_allow": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "default": [],
+                "description": "Tool names allowed for this harness."
+              },
+              "tools_deny": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "default": [],
+                "description": "Tool names denied for this harness."
+              },
+              "fallback_model": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "default": null,
+                "description": "Model to fall back to on typed fallback signals; null = none."
+              },
+              "web": {
+                "type": "string",
+                "enum": [
+                  "off",
+                  "auto",
+                  "cached",
+                  "live"
+                ],
+                "description": "Default web policy for this harness.",
+                "default": "auto"
+              },
+              "auth_preference": {
+                "$ref": "#/definitions/GlobalConfig/properties/routing/properties/auth_preference",
+                "default": "auto",
+                "description": "Preferred auth route: subscription (native/OAuth session), api_key (a stored API key), or auto (engine picks subscription-first with policy fallback). A preference, not a secret."
+              }
+            },
+            "additionalProperties": false,
+            "description": "Per-harness settings."
+          },
+          "default": {},
+          "description": "Per-harness settings keyed by harness id."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Global user config (~/.claudexor/config.yaml): portfolio, routing, budget, runtime, and per-harness settings."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/generated/HarnessEvent.schema.json

@@ -0,0 +1,360 @@
+{
+  "$ref": "#/definitions/HarnessEvent",
+  "definitions": {
+    "HarnessEvent": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "started",
+            "thinking",
+            "message",
+            "tool_call",
+            "tool_result",
+            "interaction_requested",
+            "file_change",
+            "usage",
+            "error",
+            "completed"
+          ],
+          "description": "Normalized event type covering session lifecycle, output, tool use, interaction, file changes, usage, and errors."
+        },
+        "session_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Session the event belongs to."
+        },
+        "ts": {
+          "type": "string",
+          "description": "Event timestamp."
+        },
+        "text": {
+          "type": "string",
+          "description": "Text content for thinking/message/error events."
+        },
+        "tool": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Native tool name as the harness reports it."
+            },
+            "kind": {
+              "type": "string",
+              "enum": [
+                "web",
+                "file",
+                "command",
+                "mcp",
+                "search",
+                "other"
+              ],
+              "description": "Coarse tool classification used for typed governance; adapters map native tool names to a kind.",
+              "default": "other"
+            },
+            "use_id": {
+              "type": "string",
+              "description": "Correlates a tool_result with its tool_call."
+            },
+            "target": {
+              "type": "string",
+              "description": "Redacted, bounded human-readable target (query/url/path/command)."
+            },
+            "status": {
+              "type": "string",
+              "enum": [
+                "ok",
+                "error",
+                "cancelled",
+                "denied"
+              ],
+              "description": "Outcome of the tool use; required on tool_result events (a missing status is never treated as ok)."
+            },
+            "error_summary": {
+              "type": "string",
+              "description": "Redacted, bounded error detail for status=error results."
+            },
+            "content_summary": {
+              "type": "string",
+              "description": "Redacted, bounded content detail for results (success or failure)."
+            },
+            "exit_code": {
+              "type": "integer",
+              "description": "Process exit code for command tools, when known."
+            }
+          },
+          "required": [
+            "name"
+          ],
+          "additionalProperties": false,
+          "description": "Typed tool info; set on tool_call and tool_result events."
+        },
+        "interaction": {
+          "type": "object",
+          "properties": {
+            "interaction_id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Interaction id used to correlate the answer set."
+            },
+            "questions": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Question id."
+                  },
+                  "question": {
+                    "type": "string",
+                    "description": "The question text."
+                  },
+                  "header": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "default": null,
+                    "description": "Short chip/header text some harnesses attach to a question."
+                  },
+                  "options": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "label": {
+                          "type": "string",
+                          "description": "Option label shown to the user."
+                        },
+                        "description": {
+                          "type": [
+                            "string",
+                            "null"
+                          ],
+                          "default": null,
+                          "description": "Optional longer explanation of the option."
+                        }
+                      },
+                      "required": [
+                        "label"
+                      ],
+                      "additionalProperties": false,
+                      "description": "One multiple-choice option of an interactive question."
+                    },
+                    "default": [],
+                    "description": "Selectable options; empty for free-text-only questions."
+                  },
+                  "multi_select": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether multiple options may be selected."
+                  }
+                },
+                "required": [
+                  "id",
+                  "question"
+                ],
+                "additionalProperties": false,
+                "description": "One question of an interactive user-input request."
+              },
+              "default": [],
+              "description": "Questions the harness wants answered."
+            },
+            "source_tool": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "default": null,
+              "description": "Native tool that raised the request (e.g. \"AskUserQuestion\")."
+            }
+          },
+          "required": [
+            "interaction_id"
+          ],
+          "additionalProperties": false,
+          "description": "Set on interaction_requested events."
+        },
+        "usage": {
+          "type": "object",
+          "properties": {
+            "input_tokens": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Input tokens consumed."
+            },
+            "output_tokens": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Output tokens produced."
+            },
+            "cached_input_tokens": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Input tokens served from cache."
+            },
+            "cost_usd": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Cost in USD."
+            },
+            "estimated": {
+              "type": "boolean",
+              "description": "True when cost_usd is derived from token pricing (not natively reported)."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Token/cost usage reported by the harness."
+        },
+        "observed_model": {
+          "type": "string",
+          "description": "Model the harness actually reported using."
+        },
+        "quota": {
+          "type": "object",
+          "properties": {
+            "used_percent": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 100,
+              "description": "Consumed share of the binding rate window, 0-100."
+            },
+            "resets_at": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "default": null,
+              "description": "Native reset moment for the window, when the CLI reports one."
+            }
+          },
+          "required": [
+            "used_percent"
+          ],
+          "additionalProperties": false,
+          "description": "Typed quota/usage-window signal from the harness CLI's own native machine-readable surface, never scraped from prose."
+        },
+        "plan_progress": {
+          "type": "object",
+          "properties": {
+            "items": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "Plan item id."
+                  },
+                  "title": {
+                    "type": "string",
+                    "description": "Plan item title."
+                  },
+                  "status": {
+                    "type": "string",
+                    "enum": [
+                      "pending",
+                      "in_progress",
+                      "completed"
+                    ],
+                    "description": "Progress state of the item."
+                  }
+                },
+                "required": [
+                  "id",
+                  "title",
+                  "status"
+                ],
+                "additionalProperties": false
+              },
+              "default": [],
+              "description": "Last-wins list of plan/todo items."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Typed live plan/todo progress mapped from the harness's native plan tools, never parsed from prose."
+        },
+        "rate_limit": {
+          "type": "object",
+          "properties": {
+            "resets_at": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "default": null,
+              "description": "When the rate window resets, when reported."
+            },
+            "retry_delay_ms": {
+              "anyOf": [
+                {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null,
+              "description": "Suggested retry delay in milliseconds, when reported."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Typed rate-limit/quota signal set by the adapter when the native CLI reports a 429/quota/overload."
+        },
+        "transient": {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "network",
+                "stream_disconnect",
+                "service_unavailable",
+                "timeout",
+                "unknown"
+              ],
+              "default": "unknown",
+              "description": "Kind of transient failure."
+            },
+            "retry_delay_ms": {
+              "anyOf": [
+                {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "default": null,
+              "description": "Suggested retry delay in milliseconds, when reported."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Typed transient-failure signal set by the adapter from native CLI/API error shapes, consumed for bounded retry policy."
+        },
+        "error": {
+          "type": "string",
+          "description": "Error text for error events."
+        },
+        "payload": {
+          "type": "object",
+          "additionalProperties": {},
+          "description": "Raw adapter-specific payload for diagnostics."
+        }
+      },
+      "required": [
+        "type",
+        "session_id",
+        "ts"
+      ],
+      "additionalProperties": false,
+      "description": "Normalized event emitted by every adapter (the SSOT of adapter output)."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}