approval-md 0.1.0 → 0.2.0

package/package.json

@@ -1,20 +1,29 @@
 {
   "name": "approval-md",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Human approval for agent actions. CLI runtime for the approval.md convention (pre-release).",
   "type": "module",
   "bin": {
     "approval": "./cli.js"
   },
+  "exports": {
+    "./adapters": {
+      "types": "./dist/src/adapters/public.d.ts",
+      "import": "./dist/src/adapters/public.js"
+    }
+  },
   "files": [
     "cli.js",
     "dist/src",
     "schema",
+    "docs/adapter-api.md",
     "docs/cli-reference.md",
     "SPEC.md",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "docs/codex-enforced-session.md",
+    "templates/codex"
   ],
   "repository": "github:approval-md/approval.md",
   "homepage": "https://approval.md",
@@ -25,6 +34,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "codex:mcp": "node .codex/approval-mcp.mjs",
     "typecheck": "tsc --noEmit",
     "test": "tsc -p tsconfig.json && node scripts/run-tests.mjs",
     "lint": "oxlint src tests",

package/schema/codex-instance.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://approval.md/schema/codex-instance.schema.json",
+  "$comment": "CC0 1.0. See schema/LICENSE.",
+  "title": "Constrained Codex instance manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "instance_id", "platform", "codex_version", "node_version", "package_version", "paths", "principals", "invocation", "components"],
+  "properties": {
+    "schema_version": { "const": "approval.codex.instance.v1" },
+    "instance_id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,62}$" },
+    "platform": { "const": "darwin" },
+    "codex_version": { "const": "0.152.1" },
+    "node_version": { "type": "string", "pattern": "^(?:2[0-9]|[3-9][0-9])\\.[0-9]+\\.[0-9]+$" },
+    "package_version": { "type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?$" },
+    "paths": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["install_root", "package_root", "workspace", "primary", "policy", "log", "manifest", "codex_executable", "node_executable", "mcp_executable", "broker_executable", "runner_executable"],
+      "properties": {
+        "install_root": { "$ref": "#/$defs/absolute_path" },
+        "package_root": { "$ref": "#/$defs/absolute_path" },
+        "workspace": { "$ref": "#/$defs/absolute_path" },
+        "primary": { "$ref": "#/$defs/absolute_path" },
+        "policy": { "$ref": "#/$defs/absolute_path" },
+        "log": { "$ref": "#/$defs/absolute_path" },
+        "manifest": { "$ref": "#/$defs/absolute_path" },
+        "codex_executable": { "$ref": "#/$defs/absolute_path" },
+        "node_executable": { "$ref": "#/$defs/absolute_path" },
+        "mcp_executable": { "$ref": "#/$defs/absolute_path" },
+        "broker_executable": { "$ref": "#/$defs/absolute_path" },
+        "runner_executable": { "$ref": "#/$defs/absolute_path" }
+      }
+    },
+    "principals": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["codex", "broker", "runner"],
+      "properties": {
+        "codex": { "const": "_approval_codex" },
+        "broker": { "const": "_approval_broker" },
+        "runner": { "const": "_approval_runner" }
+      }
+    },
+    "invocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "args"],
+      "properties": {
+        "command": { "$ref": "#/$defs/absolute_path" },
+        "args": {
+          "type": "array",
+          "prefixItems": [
+            { "const": "codex" },
+            { "const": "serve" },
+            { "const": "--manifest" },
+            { "$ref": "#/$defs/absolute_path" }
+          ],
+          "items": false,
+          "minItems": 4,
+          "maxItems": 4
+        }
+      }
+    },
+    "components": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["broker", "runner"],
+      "properties": {
+        "broker": { "const": "required-not-shipped" },
+        "runner": { "const": "required-not-shipped" }
+      }
+    }
+  },
+  "$defs": {
+    "absolute_path": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^/"
+    }
+  }
+}

package/schema/event.schema.json

@@ -112,7 +112,8 @@
           "type": "string",
           "enum": [
             "claude-code",
-            "cursor"
+            "cursor",
+            "codex"
           ],
           "description": "SPEC.md §10.1 (amended, APRV-227): which harness hook wrote this record. A closed set, extended only by a task that adds the case, because it is the discriminator a reader scopes `harness_version` by: one log holds the records of every harness that ever wrote to it, and a version with no binary named beside it is a string nobody can compare against anything. OPTIONAL and additive — every record written before the field existed still validates and still verifies, and the two fields travel together or not at all."
         },

package/schema/fixtures/codex-instance/invalid/unpinned-codex-version.json

@@ -0,0 +1,40 @@
+{
+  "schema_version": "approval.codex.instance.v1",
+  "instance_id": "team",
+  "platform": "darwin",
+  "codex_version": "0.153.0",
+  "node_version": "20.19.0",
+  "package_version": "0.1.0",
+  "paths": {
+    "install_root": "/Library/Application Support/approval-codex",
+    "package_root": "/Library/Application Support/approval-codex/package",
+    "workspace": "/Users/_approval_codex/workspace",
+    "primary": "/Users/operator/approval-primary",
+    "policy": "/Users/operator/approval-primary/APPROVAL.md",
+    "log": "/Users/operator/approval-primary/.approval/log/events.jsonl",
+    "manifest": "/Library/Application Support/approval-codex/instances/team.json",
+    "codex_executable": "/Library/Application Support/approval-codex/bin/codex",
+    "node_executable": "/Library/Application Support/approval-codex/bin/node",
+    "mcp_executable": "/Library/Application Support/approval-codex/bin/approval-codex-mcp",
+    "broker_executable": "/Library/Application Support/approval-codex/bin/approval-codex-broker",
+    "runner_executable": "/Library/Application Support/approval-codex/bin/approval-codex-runner"
+  },
+  "principals": {
+    "codex": "_approval_codex",
+    "broker": "_approval_broker",
+    "runner": "_approval_runner"
+  },
+  "invocation": {
+    "command": "/Library/Application Support/approval-codex/bin/approval-codex-mcp",
+    "args": [
+      "codex",
+      "serve",
+      "--manifest",
+      "/Library/Application Support/approval-codex/instances/team.json"
+    ]
+  },
+  "components": {
+    "broker": "required-not-shipped",
+    "runner": "required-not-shipped"
+  }
+}

package/schema/fixtures/codex-instance/valid/canonical.json

@@ -0,0 +1,40 @@
+{
+  "schema_version": "approval.codex.instance.v1",
+  "instance_id": "team",
+  "platform": "darwin",
+  "codex_version": "0.152.1",
+  "node_version": "20.19.0",
+  "package_version": "0.1.0",
+  "paths": {
+    "install_root": "/Library/Application Support/approval-codex",
+    "package_root": "/Library/Application Support/approval-codex/package",
+    "workspace": "/Users/_approval_codex/workspace",
+    "primary": "/Users/operator/approval-primary",
+    "policy": "/Users/operator/approval-primary/APPROVAL.md",
+    "log": "/Users/operator/approval-primary/.approval/log/events.jsonl",
+    "manifest": "/Library/Application Support/approval-codex/instances/team.json",
+    "codex_executable": "/Library/Application Support/approval-codex/bin/codex",
+    "node_executable": "/Library/Application Support/approval-codex/bin/node",
+    "mcp_executable": "/Library/Application Support/approval-codex/bin/approval-codex-mcp",
+    "broker_executable": "/Library/Application Support/approval-codex/bin/approval-codex-broker",
+    "runner_executable": "/Library/Application Support/approval-codex/bin/approval-codex-runner"
+  },
+  "principals": {
+    "codex": "_approval_codex",
+    "broker": "_approval_broker",
+    "runner": "_approval_runner"
+  },
+  "invocation": {
+    "command": "/Library/Application Support/approval-codex/bin/approval-codex-mcp",
+    "args": [
+      "codex",
+      "serve",
+      "--manifest",
+      "/Library/Application Support/approval-codex/instances/team.json"
+    ]
+  },
+  "components": {
+    "broker": "required-not-shipped",
+    "runner": "required-not-shipped"
+  }
+}

package/schema/policy.schema.json

@@ -369,7 +369,7 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["autonomy"],
-      "description": "SPEC.md §5.1: a class rule. The shorthand form is `{ autonomy }` alone; the full form adds `approvers` and `limits`. Both are this one shape — `autonomy` is always REQUIRED, since a rule without it cannot decide anything, and unknown keys are rejected so a typo'd constraint is never silently ignored.",
+      "description": "SPEC.md §5.1: a class rule. The shorthand form is `{ autonomy }` alone; the full form may add rates, `allow_irreversible`, `approvers` and `limits`. Both are this one shape — `autonomy` is always REQUIRED, since a rule without it cannot decide anything, and unknown keys are rejected so a typo'd constraint is never silently ignored.",
       "allOf": [
         {
           "$comment": "SPEC.md §5.2 (amended, APRV-127): `live_rate` belongs to `supervised-live` and to nothing else. Required there, because a live mode with no fraction declares a control without saying how much of it runs, and the runtime would have to invent the number an author did not write. Forbidden everywhere else, because a rate sitting on a `manual`, `supervised-retro` or `autonomous` rule is a fraction its author believes is in force that nothing reads — the same silent no-op this schema's closed shape exists to prevent. APRV-185 adds `human-only` to that everywhere-else, and the `else` branch below already carries it with no new clause: a level whose actions no agent may take has no fraction of them to gate, so a `live_rate` written there is a control its author believes is running over a population of size zero.",
@@ -405,6 +405,22 @@
             "type": "object",
             "properties": { "retro_rate": false }
           }
+        },
+        {
+          "$comment": "SPEC.md §5.2/§7 (amended, APRV-317): `allow_irreversible: true` is an explicit operator-authored capability for a nonmanual class rule. It is valid only where there is agent execution to retain: autonomous and the three supervised spellings. False is admitted on every level as the explicit spelling of the backward-compatible default. Manual needs no exception and human-only must never acquire one.",
+          "if": {
+            "type": "object",
+            "properties": { "allow_irreversible": { "const": true } },
+            "required": ["allow_irreversible"]
+          },
+          "then": {
+            "type": "object",
+            "properties": {
+              "autonomy": {
+                "enum": ["supervised-live", "supervised", "supervised-retro", "autonomous"]
+              }
+            }
+          }
         }
       ],
       "properties": {
@@ -414,6 +430,10 @@
         },
         "live_rate": { "$ref": "#/$defs/liveRate" },
         "retro_rate": { "$ref": "#/$defs/retroRate" },
+        "allow_irreversible": {
+          "type": "boolean",
+          "description": "SPEC.md §5.2/§7 (amended, APRV-317): explicit permission for truthful `reversible: false` actions matching this rule to retain its nonmanual autonomy. Omission or false preserves the manual floor. Every equally most-specific matching rule must say true; defaults and action metadata cannot supply it."
+        },
         "approvers": {
           "type": "array",
           "minItems": 1,

package/templates/codex/README.md

@@ -0,0 +1,9 @@
+# Constrained Codex host templates
+
+These files are documentation inputs for approval codex prepare. The command
+renders an instance-specific bundle with absolute paths and hashes.
+
+Generated output is inert. Do not copy it into /etc/codex, load its launchd
+units, create service accounts, or start its launchers until the policy-bound
+broker and confined runner are installed and strict doctor reports ready.
+APRV-325.1 always reports them as not ready.