@claudexor/schema 1.0.0

package/generated/RunTelemetry.schema.json

@@ -0,0 +1,433 @@
+{
+  "$ref": "#/definitions/RunTelemetry",
+  "definitions": {
+    "RunTelemetry": {
+      "type": "object",
+      "properties": {
+        "schema_version": {
+          "type": "number",
+          "const": 2,
+          "description": "Schema version of the artifact; bumped on breaking ABI changes."
+        },
+        "run_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Run the telemetry belongs to."
+        },
+        "task_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Task the run belongs to."
+        },
+        "mode": {
+          "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."
+        },
+        "requested_access": {
+          "type": "string",
+          "enum": [
+            "readonly",
+            "workspace_write",
+            "full",
+            "external_sandbox_full",
+            "inherit_native"
+          ],
+          "description": "Access profile the caller requested."
+        },
+        "effective_access": {
+          "type": "string",
+          "enum": [
+            "readonly",
+            "workspace_write",
+            "full",
+            "external_sandbox_full",
+            "inherit_native"
+          ],
+          "description": "Access profile actually enforced by the engine."
+        },
+        "external_context_policy": {
+          "type": "string",
+          "enum": [
+            "off",
+            "auto",
+            "cached",
+            "live"
+          ],
+          "description": "Requested web policy for the run."
+        },
+        "effective_web_mode": {
+          "type": "string",
+          "enum": [
+            "off",
+            "auto",
+            "cached",
+            "live"
+          ],
+          "description": "Web policy actually executed by the selected route."
+        },
+        "web_required": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the run required web evidence."
+        },
+        "final_attempt_id": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1,
+              "description": "Non-empty identifier string."
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Attempt whose output became the final answer/patch; null when no attempt succeeded.",
+          "default": null
+        },
+        "web": {
+          "type": "object",
+          "properties": {
+            "required": {
+              "type": "boolean",
+              "default": false,
+              "description": "Whether the run required web evidence."
+            },
+            "policy": {
+              "type": "string",
+              "enum": [
+                "off",
+                "auto",
+                "cached",
+                "live"
+              ],
+              "description": "Requested web policy for the run.",
+              "default": "auto"
+            },
+            "effective_mode": {
+              "$ref": "#/definitions/RunTelemetry/properties/web/properties/policy",
+              "default": "auto",
+              "description": "Policy actually executed by the harness route (disclosed upgrades, e.g. cached to live)."
+            },
+            "attempted": {
+              "type": "boolean",
+              "default": false,
+              "description": "Whether any web activity was attempted."
+            },
+            "satisfied": {
+              "type": "boolean",
+              "default": false,
+              "description": "Whether the web-evidence requirement was satisfied."
+            },
+            "status": {
+              "type": "string",
+              "enum": [
+                "none",
+                "attempted",
+                "satisfied",
+                "failed",
+                "unverified"
+              ],
+              "description": "Web-evidence verdict for an attempt/run: none (no web activity), attempted, satisfied (required evidence produced), failed, or unverified.",
+              "default": "none"
+            },
+            "tool": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "default": null,
+              "description": "Web tool that produced the evidence, when any."
+            },
+            "target": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "default": null,
+              "description": "Redacted target (query/url) of the web activity, when any."
+            },
+            "error_summary": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "default": null,
+              "description": "Redacted error detail when web activity failed."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Run-level web evidence: the final attempt's evidence, else the most severe attempt evidence."
+        },
+        "attempts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "attempt_id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Attempt id."
+              },
+              "harness_id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Harness that ran the attempt."
+              },
+              "observed_model": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "default": null,
+                "description": "Model the harness stream actually reported; null when never disclosed (rendered as unverified, never guessed)."
+              },
+              "web": {
+                "type": "object",
+                "properties": {
+                  "required": {
+                    "$ref": "#/definitions/RunTelemetry/properties/web/properties/required"
+                  },
+                  "policy": {
+                    "$ref": "#/definitions/RunTelemetry/properties/web/properties/policy"
+                  },
+                  "effective_mode": {
+                    "$ref": "#/definitions/RunTelemetry/properties/web/properties/effective_mode"
+                  },
+                  "attempted": {
+                    "$ref": "#/definitions/RunTelemetry/properties/web/properties/attempted"
+                  },
+                  "satisfied": {
+                    "$ref": "#/definitions/RunTelemetry/properties/web/properties/satisfied"
+                  },
+                  "status": {
+                    "$ref": "#/definitions/RunTelemetry/properties/web/properties/status"
+                  },
+                  "tool": {
+                    "$ref": "#/definitions/RunTelemetry/properties/web/properties/tool"
+                  },
+                  "target": {
+                    "$ref": "#/definitions/RunTelemetry/properties/web/properties/target"
+                  },
+                  "error_summary": {
+                    "$ref": "#/definitions/RunTelemetry/properties/web/properties/error_summary"
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Typed web-evidence record computed by the orchestrator; surfaces project it and never re-derive evidence from raw events."
+              },
+              "tool_errors": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "tool": {
+                      "type": "string",
+                      "description": "Native tool name that errored."
+                    },
+                    "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"
+                    },
+                    "target": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "default": null,
+                      "description": "Redacted target of the tool use, when known."
+                    },
+                    "summary": {
+                      "type": "string",
+                      "description": "Redacted error summary."
+                    },
+                    "recovered": {
+                      "type": "boolean",
+                      "default": false,
+                      "description": "True when a later successful result of the same tool exists in the same attempt."
+                    },
+                    "tool_use_id": {
+                      "type": [
+                        "string",
+                        "null"
+                      ],
+                      "default": null,
+                      "description": "Tool use id correlating the error to its call, when known."
+                    }
+                  },
+                  "required": [
+                    "tool",
+                    "summary"
+                  ],
+                  "additionalProperties": false,
+                  "description": "One tool error observed during an attempt."
+                },
+                "default": [],
+                "description": "Tool errors, bounded by the writer (most recent first when truncated; tool_errors_total keeps the true count)."
+              },
+              "tool_errors_total": {
+                "type": "integer",
+                "minimum": 0,
+                "default": 0,
+                "description": "True total count of tool errors."
+              },
+              "unrecovered_tool_errors": {
+                "type": "integer",
+                "minimum": 0,
+                "default": 0,
+                "description": "Tool errors with no later successful recovery."
+              },
+              "statusless_tool_results": {
+                "type": "integer",
+                "minimum": 0,
+                "default": 0,
+                "description": "tool_result events that arrived without a status field (never treated as ok)."
+              },
+              "dropped_events": {
+                "type": "integer",
+                "minimum": 0,
+                "default": 0,
+                "description": "Native lines/events the adapter could not parse or did not recognize (never silently zero)."
+              },
+              "transient_failures": {
+                "type": "array",
+                "items": {
+                  "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": "An adapter-declared transient failure that informed bounded retry policy."
+                },
+                "default": [],
+                "description": "Adapter-declared transient failures that informed bounded retry policy."
+              },
+              "outcome": {
+                "type": "object",
+                "properties": {
+                  "deliverable_present": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the attempt produced the deliverable the intent asked for."
+                  },
+                  "gates_passed": {
+                    "type": [
+                      "boolean",
+                      "null"
+                    ],
+                    "default": null,
+                    "description": "Whether deterministic gates passed; null when no gates ran."
+                  },
+                  "harness_errored": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Whether the harness itself errored."
+                  },
+                  "web_required_unsatisfied": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "True when required web evidence was not satisfied."
+                  },
+                  "tool_warnings_count": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "default": 0,
+                    "description": "Count of tool warnings in the attempt."
+                  },
+                  "status": {
+                    "type": "string",
+                    "enum": [
+                      "success",
+                      "success_with_warnings",
+                      "blocked",
+                      "failed"
+                    ],
+                    "description": "Outcome of one attempt: success, success_with_warnings, blocked, or failed.",
+                    "default": "success"
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Contract/outcome truth for one attempt; tool errors are tracked separately from deliverable production.",
+                "default": {}
+              }
+            },
+            "required": [
+              "attempt_id",
+              "harness_id",
+              "web"
+            ],
+            "additionalProperties": false,
+            "description": "Telemetry for one attempt: route evidence, web evidence, tool errors, dropped events, and outcome."
+          },
+          "default": [],
+          "description": "Per-attempt telemetry records."
+        },
+        "tool_warnings_total": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0,
+          "description": "Sum of attempt tool warnings; rendered separately from terminal state."
+        },
+        "generated_at": {
+          "type": "string",
+          "minLength": 1,
+          "description": "When the telemetry artifact was generated."
+        }
+      },
+      "required": [
+        "schema_version",
+        "run_id",
+        "task_id",
+        "mode",
+        "requested_access",
+        "effective_access",
+        "external_context_policy",
+        "effective_web_mode",
+        "web",
+        "generated_at"
+      ],
+      "additionalProperties": false,
+      "description": "Run telemetry artifact (final/telemetry.yaml), the single computed source of web/tool evidence; surfaces project it and never re-derive evidence from raw events."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/generated/SecretMetadata.schema.json

@@ -0,0 +1,34 @@
+{
+  "$ref": "#/definitions/SecretMetadata",
+  "definitions": {
+    "SecretMetadata": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Secret name/label."
+        },
+        "backend": {
+          "type": "string",
+          "enum": [
+            "keychain",
+            "file"
+          ],
+          "description": "Where the secret is stored: the OS keychain or a file store."
+        },
+        "present": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether a value is actually stored."
+        }
+      },
+      "required": [
+        "name",
+        "backend"
+      ],
+      "additionalProperties": false,
+      "description": "Secret list row: name, storage backend, and presence — never the value."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/generated/Session.schema.json

@@ -0,0 +1,80 @@
+{
+  "$ref": "#/definitions/Session",
+  "definitions": {
+    "Session": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Session id."
+        },
+        "thread_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Thread the session belongs to."
+        },
+        "harness_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Harness the session is bound to."
+        },
+        "native_session_id": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "The vendor CLI session id (codex thread id / claude session uuid / ...); null when none exists."
+        },
+        "resume_kind": {
+          "type": "string",
+          "enum": [
+            "resume_by_id",
+            "none"
+          ],
+          "description": "How the session can be continued on its native CLI: resume_by_id when a native session id exists, none otherwise.",
+          "default": "none"
+        },
+        "last_observed_model": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "Model last observed on the session's stream."
+        },
+        "state": {
+          "type": "string",
+          "enum": [
+            "live",
+            "stale",
+            "rebound"
+          ],
+          "description": "Vendor session cache state: live (resumable), stale, or rebound (re-hosted elsewhere).",
+          "default": "live"
+        },
+        "created_at": {
+          "type": "string",
+          "minLength": 1,
+          "description": "When the session was created."
+        },
+        "updated_at": {
+          "type": "string",
+          "minLength": 1,
+          "description": "When the session was last updated."
+        }
+      },
+      "required": [
+        "id",
+        "thread_id",
+        "harness_id",
+        "created_at",
+        "updated_at"
+      ],
+      "additionalProperties": false,
+      "description": "A re-hostable pointer to one harness's native CLI session for a thread — a cache, not the source of truth."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/generated/SessionReboundLineage.schema.json

@@ -0,0 +1,73 @@
+{
+  "$ref": "#/definitions/SessionReboundLineage",
+  "definitions": {
+    "SessionReboundLineage": {
+      "type": "object",
+      "properties": {
+        "thread_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Thread whose session was re-hosted."
+        },
+        "harness_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Harness the new session runs on."
+        },
+        "from_native_session_id": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "The vendor native session id being left behind (not a Claudexor id); null when none existed."
+        },
+        "to_session_id": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1,
+              "description": "Non-empty identifier string."
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "New Claudexor session id; null when no new session was created.",
+          "default": null
+        },
+        "summary": {
+          "type": "string",
+          "default": "",
+          "description": "Carried-over conversation summary injected into the new session."
+        },
+        "reason": {
+          "type": "string",
+          "enum": [
+            "quota_exhausted",
+            "money_exhausted",
+            "subscription_exhausted",
+            "rate_limited",
+            "harness_error",
+            "stall",
+            "web_evidence_unsatisfied",
+            "fallback_model",
+            "not_portable",
+            "auth_unavailable",
+            "readiness_preferred",
+            "manual"
+          ],
+          "description": "Typed reason an auto-fallback (route/auth switch) or session re-host happened, driven by typed budget/quota signals and events, never by regex over prose.",
+          "default": "not_portable"
+        }
+      },
+      "required": [
+        "thread_id",
+        "harness_id"
+      ],
+      "additionalProperties": false,
+      "description": "The lossy payload serialized when a turn cannot resume the native session in place (isolated candidates or re-hosting onto a different harness); carried by the session.rebound event."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}