@claudexor/schema 1.0.0

package/generated/ThreadTurn.schema.json

@@ -0,0 +1,172 @@
+{
+  "$ref": "#/definitions/ThreadTurn",
+  "definitions": {
+    "ThreadTurn": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Turn id."
+        },
+        "thread_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Thread the turn belongs to."
+        },
+        "run_id": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1,
+              "description": "Non-empty identifier string."
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Run backing this turn; null while unbound.",
+          "default": null
+        },
+        "parent_run_id": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ThreadTurn/properties/run_id/anyOf/0"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Run this turn follows up on, when any.",
+          "default": null
+        },
+        "plan_run_id": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/ThreadTurn/properties/run_id/anyOf/0"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Set when this turn implements an approved plan from an earlier plan run.",
+          "default": null
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "initial",
+            "followup",
+            "decision"
+          ],
+          "description": "Kind of thread turn: the initial message, a followup, or an operator decision turn.",
+          "default": "followup"
+        },
+        "prompt": {
+          "type": "string",
+          "default": "",
+          "description": "The user's message for this turn."
+        },
+        "attachments": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Attachment id."
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "image",
+                  "file"
+                ],
+                "description": "Kind of attachment: image (vision input) or file (generic bytes).",
+                "default": "file"
+              },
+              "mime": {
+                "type": "string",
+                "default": "application/octet-stream",
+                "description": "MIME type of the attachment content."
+              },
+              "name": {
+                "type": "string",
+                "default": "",
+                "description": "Original file name as provided by the user or agent."
+              },
+              "path": {
+                "type": "string",
+                "description": "Resolved local path in the scoped attachment store (kept outside any worktree)."
+              }
+            },
+            "required": [
+              "id",
+              "path"
+            ],
+            "additionalProperties": false,
+            "description": "A user- or agent-provided file/image attached to a turn, stored in the scoped attachment store and forwarded to harnesses in their native shape."
+          },
+          "default": [],
+          "description": "Files/images the user attached to this turn (resolved scoped paths)."
+        },
+        "enqueue_error": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "message": {
+                  "type": "string",
+                  "description": "Human-readable refusal message."
+                },
+                "code": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "default": null,
+                  "description": "Machine-readable refusal code carried from the throwing gate; null when the failure had no typed code."
+                },
+                "retryable": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "True when retry can replay this turn (a job was recorded before the failure); false when no job exists to replay."
+                },
+                "failed_at": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "When the enqueue failed."
+                }
+              },
+              "required": [
+                "message",
+                "failed_at"
+              ],
+              "additionalProperties": false,
+              "description": "Typed record of a turn whose run could not be enqueued/started, persisted on the turn so every surface renders the refusal inline; cleared when a retry binds a run."
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Why this turn has no run (enqueue/preflight refusal); null once a run binds.",
+          "default": null
+        },
+        "created_at": {
+          "type": "string",
+          "minLength": 1,
+          "description": "When the turn was created."
+        }
+      },
+      "required": [
+        "id",
+        "thread_id",
+        "created_at"
+      ],
+      "additionalProperties": false,
+      "description": "One follow-up unit within a thread; a run is its backing execution."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/generated/TrustConfig.schema.json

@@ -0,0 +1,44 @@
+{
+  "$ref": "#/definitions/TrustConfig",
+  "definitions": {
+    "TrustConfig": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "number",
+          "const": 1,
+          "default": 1,
+          "description": "Config format version."
+        },
+        "access_default": {
+          "type": "string",
+          "enum": [
+            "readonly",
+            "workspace_write",
+            "full",
+            "external_sandbox_full",
+            "inherit_native"
+          ],
+          "description": "Default access profile for runs in this repo.",
+          "default": "workspace_write"
+        },
+        "allow_full_access": {
+          "type": "boolean",
+          "default": false,
+          "description": "Per-repo allow required before any run may use the full access profile."
+        },
+        "repo_root": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "Provenance only: repo root this trust file was written for; never gates anything. Null on legacy files written before this field."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Sensitive per-repo trust settings — only valid in global/user-local trust files, never in the versioned repo config."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/generated/WorkProduct.schema.json

@@ -0,0 +1,60 @@
+{
+  "$ref": "#/definitions/WorkProduct",
+  "definitions": {
+    "WorkProduct": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Work product id."
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "patch",
+            "new_repo",
+            "report"
+          ],
+          "description": "Kind of work product a run produces: a patch against the base tree, a newly created repository, or a report document."
+        },
+        "source_task_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Task the work product came from."
+        },
+        "producer_attempt_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Attempt that produced it, when known."
+        },
+        "evidence_dir": {
+          "type": "string",
+          "description": "Directory holding run evidence artifacts."
+        },
+        "files": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "default": {},
+          "description": "Kind-specific file payload, e.g. artifact name to path (validated loosely here; specialized per kind by callers)."
+        },
+        "meta": {
+          "type": "object",
+          "additionalProperties": {},
+          "default": {},
+          "description": "Kind-specific metadata."
+        }
+      },
+      "required": [
+        "id",
+        "kind",
+        "source_task_id"
+      ],
+      "additionalProperties": false,
+      "description": "The deliverable a run produced (patch, new repo, or report), referenced by apply/delivery verbs."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/generated/WorkspaceEnvelope.schema.json

@@ -0,0 +1,94 @@
+{
+  "$ref": "#/definitions/WorkspaceEnvelope",
+  "definitions": {
+    "WorkspaceEnvelope": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Envelope id."
+        },
+        "task_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Task the envelope belongs to."
+        },
+        "attempt_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Attempt the envelope belongs to."
+        },
+        "repo_root": {
+          "type": "string",
+          "description": "Absolute path of the source repository root."
+        },
+        "base_ref": {
+          "type": "string",
+          "description": "Git ref the worktree was created from."
+        },
+        "base_sha": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "Resolved base commit SHA; null when not recorded."
+        },
+        "worktree_path": {
+          "type": "string",
+          "description": "Absolute path of the isolated git worktree."
+        },
+        "branch_name": {
+          "type": "string",
+          "description": "Branch created for the worktree."
+        },
+        "home_dir": {
+          "type": "string",
+          "description": "Scoped HOME directory for the harness process (kept outside the worktree)."
+        },
+        "harness_config_dirs": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "default": {},
+          "description": "Scoped per-harness config directories keyed by harness id (kept outside the worktree)."
+        },
+        "policy_profile": {
+          "type": "string",
+          "default": "workspace_write",
+          "description": "Access profile the envelope enforces."
+        },
+        "dirty_policy": {
+          "type": "string",
+          "enum": [
+            "refuse",
+            "snapshot"
+          ],
+          "description": "How a dirty working tree is handled when creating an envelope: snapshot captures the dirty state as the base SHA without touching the live tree; refuse fails loudly.",
+          "default": "refuse"
+        },
+        "created_at": {
+          "type": "string",
+          "minLength": 1,
+          "description": "When the envelope was created."
+        }
+      },
+      "required": [
+        "id",
+        "task_id",
+        "attempt_id",
+        "repo_root",
+        "base_ref",
+        "worktree_path",
+        "branch_name",
+        "home_dir",
+        "created_at"
+      ],
+      "additionalProperties": false,
+      "description": "An isolated execution envelope: a git worktree for files plus scoped env/HOME/harness-config isolation."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@claudexor/schema",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Single source of truth for all Claudexor data shapes (Zod + generated JSON Schema).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./generated/*.schema.json": "./generated/*.schema.json"
+  },
+  "files": [
+    "dist",
+    "generated"
+  ],
+  "dependencies": {
+    "zod": "^3.24.1",
+    "zod-to-json-schema": "^3.24.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/razzant/claudexor.git",
+    "directory": "packages/schema"
+  },
+  "homepage": "https://github.com/razzant/claudexor#readme",
+  "bugs": {
+    "url": "https://github.com/razzant/claudexor/issues"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}