codex-chatgpt-control 0.5.1-alpha.2 → 0.5.1-alpha.4

package/contracts/v1/schemas/operation-artifact-receipt.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/schemas/operation-artifact-receipt.schema.json",
+  "title": "Transactional browser operation artifact receipt",
+  "description": "A redacted receipt for one operation-owned artifact and assistant turn. Output keys are opaque generated names, never caller-supplied paths.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "operationId", "artifactKey", "assistantTurnId", "sourceIdentityDigest", "kind", "ordinal", "status"],
+  "properties": {
+    "schemaVersion": { "const": "chatgpt.browser_control.operation_artifact_receipt.v1" },
+    "operationId": { "$ref": "#/$defs/uuid" },
+    "artifactKey": { "$ref": "#/$defs/opaqueKey" },
+    "assistantTurnId": { "$ref": "#/$defs/opaqueId" },
+    "sourceIdentityDigest": { "$ref": "#/$defs/digest" },
+    "kind": { "enum": ["file", "image", "other"] },
+    "ordinal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+    "outputKey": { "$ref": "#/$defs/outputKey" },
+    "mimeType": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 127,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9!#$&^_.+/-]{0,126}$"
+    },
+    "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+    "sha256": { "$ref": "#/$defs/sha256" },
+    "status": { "enum": ["available", "transferred", "partial", "blocked"] },
+    "blockerCode": { "$ref": "#/$defs/code" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "transferred" } }, "required": ["status"] },
+      "then": {
+        "required": ["outputKey", "bytes", "sha256"],
+        "properties": {
+          "outputKey": { "$ref": "#/$defs/outputKey" },
+          "bytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+          "sha256": { "$ref": "#/$defs/sha256" }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "status": { "enum": ["partial", "blocked"] } }, "required": ["status"] },
+      "then": {
+        "required": ["blockerCode"],
+        "properties": { "blockerCode": { "$ref": "#/$defs/code" } }
+      }
+    },
+    {
+      "if": { "properties": { "status": { "enum": ["available", "transferred"] } }, "required": ["status"] },
+      "then": { "not": { "required": ["blockerCode"] } }
+    }
+  ],
+  "$defs": {
+    "opaqueId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]{1,512}$"
+    },
+    "uuid": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^hmac-sha256:[0-9a-f]{64}$"
+    },
+    "opaqueKey": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+    },
+    "outputKey": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+    },
+    "sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "code": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]{0,63}$"
+    }
+  }
+}

package/contracts/v1/schemas/operation-blocker.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/schemas/operation-blocker.schema.json",
+  "title": "Transactional browser operation blocker",
+  "description": "A structured public blocker taxonomy. The message is a transient caller-facing explanation and must be redacted before durable journal persistence.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "code", "recoverable", "operationId", "requestDigest", "phase", "mutationBoundary", "message"],
+  "properties": {
+    "schemaVersion": { "const": "chatgpt.browser_control.operation_blocker.v1" },
+    "code": {
+      "enum": [
+        "operation_not_found",
+        "operation_request_mismatch",
+        "operation_state_corrupt",
+        "operation_receipt_expired",
+        "operation_quota_exceeded",
+        "operation_cancelled",
+        "operation_timeout",
+        "ambiguous_file_handoff",
+        "ambiguous_submit",
+        "attachment_manifest_mismatch",
+        "input_file_changed",
+        "target_binding_mismatch",
+        "target_evidence_unavailable",
+        "turn_ownership_ambiguous",
+        "concurrent_user_turn",
+        "configuration_drift",
+        "tab_ownership_conflict",
+        "provider_concurrency_unsupported",
+        "runtime_incompatible",
+        "backend_unavailable",
+        "browser_bridge_unavailable",
+        "login_required",
+        "captcha",
+        "rate_limited",
+        "permission_required",
+        "needs_confirmation",
+        "selector_drift",
+        "send_control_unavailable",
+        "capture_ownership_lost",
+        "artifact_unavailable",
+        "artifact_transfer_partial",
+        "output_collision",
+        "output_commit_indeterminate",
+        "clipboard_restore_failed"
+      ]
+    },
+    "recoverable": { "type": "boolean" },
+    "operationId": { "$ref": "#/$defs/uuid" },
+    "requestDigest": { "$ref": "#/$defs/digest" },
+    "phase": {
+      "enum": ["prepared", "handoff_pending", "ready", "send_pending", "submitted", "generating", "capturing", "completed", "uncertain"]
+    },
+    "mutationBoundary": {
+      "enum": ["none", "handoff_may_have_occurred", "send_may_have_occurred", "control_may_have_occurred"]
+    },
+    "message": { "type": "string", "minLength": 1, "maxLength": 4096 }
+  },
+  "$defs": {
+    "uuid": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^hmac-sha256:[0-9a-f]{64}$"
+    }
+  }
+}

package/contracts/v1/schemas/operation-collect-request.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/schemas/operation-collect-request.schema.json",
+  "title": "Transactional browser operation collect request",
+  "description": "A browser-touching collect request. It can observe and capture only the exact operation-owned turn; it cannot compose, attach, or submit.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "handle"],
+  "properties": {
+    "schemaVersion": { "const": "chatgpt.browser_control.operation_collect_request.v1" },
+    "handle": { "$ref": "#/$defs/handle" },
+    "wait": { "type": "boolean" },
+    "timeoutMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+    "pollIntervalMs": { "type": "integer", "minimum": 0, "maximum": 60000 },
+    "responseContent": { "enum": ["include", "metadata"] }
+  },
+  "$defs": {
+    "uuid": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^hmac-sha256:[0-9a-f]{64}$"
+    },
+    "handle": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "operationId", "requestDigest", "surface", "revision", "phase", "mutationBoundary"],
+      "properties": {
+        "schemaVersion": { "const": "chatgpt.browser_control.operation_handle.v1" },
+        "operationId": { "$ref": "#/$defs/uuid" },
+        "requestDigest": { "$ref": "#/$defs/digest" },
+        "surface": { "enum": ["chat", "work"] },
+        "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+        "phase": {
+          "enum": ["prepared", "handoff_pending", "ready", "send_pending", "submitted", "generating", "capturing", "completed", "uncertain"]
+        },
+        "mutationBoundary": {
+          "enum": ["none", "handoff_may_have_occurred", "send_may_have_occurred", "control_may_have_occurred"]
+        },
+        "targetBindingDigest": { "$ref": "#/$defs/digest" }
+      }
+    }
+  }
+}

package/contracts/v1/schemas/operation-collect-result.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/schemas/operation-collect-result.schema.json",
+  "title": "Transactional browser operation collect result",
+  "description": "A strict versioned collect envelope. Durable receipts contain metadata only; optional liveResponse is explicitly ephemeral and non-durable.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "status", "operationId", "requestDigest", "handle"],
+  "properties": {
+    "schemaVersion": { "const": "chatgpt.browser_control.operation_collect_result.v1" },
+    "status": { "enum": ["completed", "pending", "blocked", "uncertain"] },
+    "operationId": { "$ref": "#/$defs/uuid" }, "requestDigest": { "$ref": "#/$defs/digest" }, "handle": { "$ref": "#/$defs/handle" },
+    "receipt": { "$ref": "#/$defs/receipt" }, "liveResponse": { "$ref": "#/$defs/liveResponse" }, "blocker": { "$ref": "#/$defs/blocker" }
+  },
+  "allOf": [
+    { "if": { "properties": { "status": { "const": "completed" } }, "required": ["status"] }, "then": { "required": ["receipt"], "properties": { "receipt": { "$ref": "#/$defs/receipt" }, "blocker": false } } },
+    { "if": { "properties": { "status": { "const": "pending" } }, "required": ["status"] }, "then": { "properties": { "receipt": false, "blocker": false, "liveResponse": false } } },
+    { "if": { "properties": { "status": { "enum": ["blocked", "uncertain"] } }, "required": ["status"] }, "then": { "required": ["blocker"], "properties": { "blocker": { "$ref": "#/$defs/blocker" }, "receipt": false, "liveResponse": false } } }
+  ],
+  "$defs": {
+    "uuid": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+    "digest": { "type": "string", "pattern": "^hmac-sha256:[0-9a-f]{64}$" },
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "instant": { "type": "string", "pattern": "^(?!\\d{4}-02-(?:30|31)T)(?!\\d{4}-(?:04|06|09|11)-31T)\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}Z$" },
+    "opaqueId": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]{1,512}$" },
+    "phase": { "enum": ["prepared", "handoff_pending", "ready", "send_pending", "submitted", "generating", "capturing", "completed", "uncertain"] },
+    "boundary": { "enum": ["none", "handoff_may_have_occurred", "send_may_have_occurred", "control_may_have_occurred"] },
+    "handle": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schemaVersion", "operationId", "requestDigest", "surface", "revision", "phase", "mutationBoundary"],
+      "properties": {
+        "schemaVersion": { "const": "chatgpt.browser_control.operation_handle.v1" }, "operationId": { "$ref": "#/$defs/uuid" }, "requestDigest": { "$ref": "#/$defs/digest" },
+        "surface": { "enum": ["chat", "work"] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "phase": { "$ref": "#/$defs/phase" }, "mutationBoundary": { "$ref": "#/$defs/boundary" }, "targetBindingDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "artifact": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schemaVersion", "operationId", "artifactKey", "assistantTurnId", "sourceIdentityDigest", "kind", "ordinal", "status"],
+      "properties": {
+        "schemaVersion": { "const": "chatgpt.browser_control.operation_artifact_receipt.v1" }, "operationId": { "$ref": "#/$defs/uuid" }, "artifactKey": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "assistantTurnId": { "$ref": "#/$defs/opaqueId" }, "sourceIdentityDigest": { "$ref": "#/$defs/digest" }, "kind": { "enum": ["file", "image", "other"] }, "ordinal": { "type": "integer", "minimum": 0, "maximum": 31 }, "outputKey": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "mimeType": { "type": "string", "minLength": 1, "maxLength": 127, "pattern": "^[A-Za-z0-9][A-Za-z0-9!#$&^_.+/-]{0,126}$" }, "bytes": { "type": "integer", "minimum": 0, "maximum": 8388608 }, "sha256": { "$ref": "#/$defs/sha256" }, "status": { "enum": ["available", "transferred", "partial", "blocked"] }, "blockerCode": { "$ref": "#/$defs/code" }
+      },
+      "allOf": [
+        { "if": { "properties": { "status": { "const": "transferred" } }, "required": ["status"] }, "then": { "required": ["outputKey", "bytes", "sha256"], "properties": { "outputKey": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "$ref": "#/$defs/sha256" } } } },
+        { "if": { "properties": { "status": { "enum": ["partial", "blocked"] } }, "required": ["status"] }, "then": { "required": ["blockerCode"], "properties": { "blockerCode": { "$ref": "#/$defs/code" } } } },
+        { "if": { "properties": { "status": { "enum": ["available", "transferred"] } }, "required": ["status"] }, "then": { "properties": { "blockerCode": false } } }
+      ]
+    },
+    "receipt": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schemaVersion", "operationId", "requestDigest", "targetBindingDigest", "userTurnId", "userTurnEvidenceDigest", "assistantTurnId", "ownershipEvidenceDigest", "finishReason", "contentAvailable", "artifacts", "completedAt"],
+      "properties": {
+        "schemaVersion": { "const": "chatgpt.browser_control.operation_receipt.v1" }, "operationId": { "$ref": "#/$defs/uuid" }, "requestDigest": { "$ref": "#/$defs/digest" }, "targetBindingDigest": { "$ref": "#/$defs/digest" }, "userTurnId": { "$ref": "#/$defs/opaqueId" }, "userTurnEvidenceDigest": { "$ref": "#/$defs/digest" }, "assistantTurnId": { "$ref": "#/$defs/opaqueId" }, "ownershipEvidenceDigest": { "$ref": "#/$defs/digest" }, "responseDigest": { "$ref": "#/$defs/digest" }, "responseBytes": { "type": "integer", "minimum": 0, "maximum": 8388608 }, "responseFormat": { "enum": ["markdown", "text"] }, "finishReason": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" }, "contentAvailable": { "type": "boolean" }, "artifacts": { "type": "array", "maxItems": 32, "items": { "$ref": "#/$defs/artifact" } }, "completedAt": { "$ref": "#/$defs/instant" }
+      },
+      "dependentRequired": { "responseDigest": ["responseBytes"], "responseBytes": ["responseDigest"] },
+      "allOf": [{ "if": { "properties": { "contentAvailable": { "const": true } }, "required": ["contentAvailable"] }, "then": { "required": ["responseDigest", "responseBytes"], "properties": { "responseDigest": { "$ref": "#/$defs/digest" }, "responseBytes": { "type": "integer", "minimum": 0, "maximum": 8388608 } } } }]
+    },
+    "liveResponse": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schemaVersion", "durability", "durable", "content", "bytes", "chars"],
+      "properties": {
+        "schemaVersion": { "const": "chatgpt.browser_control.operation_live_response.v1" }, "durability": { "const": "ephemeral" }, "durable": { "const": false },
+        "content": { "type": "string", "maxLength": 8388608 }, "responseFormat": { "enum": ["markdown", "text"] }, "bytes": { "type": "integer", "minimum": 0, "maximum": 8388608 }, "chars": { "type": "integer", "minimum": 0, "maximum": 8388608 }
+      }
+    },
+    "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" },
+    "blocker": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schemaVersion", "code", "recoverable", "operationId", "requestDigest", "phase", "mutationBoundary", "message"],
+      "properties": {
+        "schemaVersion": { "const": "chatgpt.browser_control.operation_blocker.v1" }, "code": { "$ref": "#/$defs/code" }, "recoverable": { "type": "boolean" }, "operationId": { "$ref": "#/$defs/uuid" }, "requestDigest": { "$ref": "#/$defs/digest" }, "phase": { "$ref": "#/$defs/phase" }, "mutationBoundary": { "$ref": "#/$defs/boundary" }, "message": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9][A-Za-z0-9 .,:;'()\\-]{0,511}$" }
+      }
+    }
+  }
+}

package/contracts/v1/schemas/operation-control-receipt.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/schemas/operation-control-receipt.schema.json",
+  "title": "Transactional browser operation control receipt",
+  "description": "A redacted receipt for one operation-bound stop or steer action. It never contains the steer text or response content.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "controlActionId",
+    "parentOperationId",
+    "parentRequestDigest",
+    "parentTargetBindingDigest",
+    "expectedAssistantTurnId",
+    "requestDigest",
+    "action",
+    "outcome",
+    "observedAt"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "chatgpt.browser_control.operation_control_receipt.v1" },
+    "controlActionId": { "$ref": "#/$defs/uuid" },
+    "parentOperationId": { "$ref": "#/$defs/uuid" },
+    "parentRequestDigest": { "$ref": "#/$defs/digest" },
+    "parentTargetBindingDigest": { "$ref": "#/$defs/digest" },
+    "expectedAssistantTurnId": { "$ref": "#/$defs/opaqueId" },
+    "requestDigest": { "$ref": "#/$defs/digest" },
+    "action": { "enum": ["stop", "steer"] },
+    "outcome": { "enum": ["satisfied", "not_satisfied", "uncertain"] },
+    "evidenceDigest": { "$ref": "#/$defs/digest" },
+    "blockerCode": { "$ref": "#/$defs/blockerCode" },
+    "observedAt": { "$ref": "#/$defs/instant" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "outcome": { "const": "satisfied" } }, "required": ["outcome"] },
+      "then": {
+        "required": ["evidenceDigest"],
+        "properties": {
+          "evidenceDigest": { "$ref": "#/$defs/digest" },
+          "blockerCode": false
+        }
+      }
+    },
+    {
+      "if": { "properties": { "outcome": { "enum": ["not_satisfied", "uncertain"] } }, "required": ["outcome"] },
+      "then": { "required": ["blockerCode"] }
+    }
+  ],
+  "$defs": {
+    "uuid": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^hmac-sha256:[0-9a-f]{64}$"
+    },
+    "opaqueId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]{1,512}$"
+    },
+    "instant": {
+      "type": "string",
+      "pattern": "^(?!\\d{4}-02-(?:30|31)T)(?!\\d{4}-(?:04|06|09|11)-31T)\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}Z$"
+    },
+    "blockerCode": {
+      "enum": [
+        "operation_not_found",
+        "operation_request_mismatch",
+        "operation_state_corrupt",
+        "operation_receipt_expired",
+        "operation_quota_exceeded",
+        "operation_cancelled",
+        "operation_timeout",
+        "ambiguous_file_handoff",
+        "ambiguous_submit",
+        "attachment_manifest_mismatch",
+        "input_file_changed",
+        "target_binding_mismatch",
+        "target_evidence_unavailable",
+        "turn_ownership_ambiguous",
+        "concurrent_user_turn",
+        "configuration_drift",
+        "tab_ownership_conflict",
+        "provider_concurrency_unsupported",
+        "runtime_incompatible",
+        "backend_unavailable",
+        "browser_bridge_unavailable",
+        "login_required",
+        "captcha",
+        "rate_limited",
+        "permission_required",
+        "needs_confirmation",
+        "selector_drift",
+        "send_control_unavailable",
+        "capture_ownership_lost",
+        "artifact_unavailable",
+        "artifact_transfer_partial",
+        "output_collision",
+        "output_commit_indeterminate",
+        "clipboard_restore_failed"
+      ]
+    }
+  }
+}

package/contracts/v1/schemas/operation-control-request.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/schemas/operation-control-request.schema.json",
+  "title": "Transactional browser operation control request",
+  "description": "A request-only, caller-owned stop or steer action bound to an immutable parent handle and expected assistant turn. steerPrompt is transient and must not enter durable state.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "controlActionId",
+    "parent",
+    "action",
+    "expectedAssistantTurnId"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "chatgpt.browser_control.operation_control_request.v1" },
+    "controlActionId": { "$ref": "#/$defs/uuid" },
+    "parent": { "$ref": "#/$defs/handle" },
+    "action": { "enum": ["stop", "steer"] },
+    "expectedAssistantTurnId": { "$ref": "#/$defs/opaqueId" },
+    "steerPrompt": { "type": "string", "minLength": 1, "maxLength": 8388608 },
+    "timeoutMs": { "$ref": "#/$defs/timeoutMs" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "action": { "const": "steer" } }, "required": ["action"] },
+      "then": {
+        "required": ["steerPrompt"],
+        "properties": { "steerPrompt": { "type": "string", "minLength": 1, "maxLength": 8388608 } }
+      }
+    },
+    {
+      "if": { "properties": { "action": { "const": "stop" } }, "required": ["action"] },
+      "then": { "properties": { "steerPrompt": false } }
+    },
+    {
+      "properties": {
+        "parent": {
+          "type": "object",
+          "required": ["targetBindingDigest"],
+          "properties": {
+            "phase": { "const": "generating" },
+            "targetBindingDigest": { "$ref": "#/$defs/digest" }
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "uuid": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^hmac-sha256:[0-9a-f]{64}$"
+    },
+    "opaqueId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]{1,512}$"
+    },
+    "timeoutMs": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "handle": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "operationId",
+        "requestDigest",
+        "surface",
+        "revision",
+        "phase",
+        "mutationBoundary"
+      ],
+      "properties": {
+        "schemaVersion": { "const": "chatgpt.browser_control.operation_handle.v1" },
+        "operationId": { "$ref": "#/$defs/uuid" },
+        "requestDigest": { "$ref": "#/$defs/digest" },
+        "surface": { "enum": ["chat", "work"] },
+        "revision": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
+        "phase": {
+          "enum": [
+            "prepared",
+            "handoff_pending",
+            "ready",
+            "send_pending",
+            "submitted",
+            "generating",
+            "capturing",
+            "completed",
+            "uncertain"
+          ]
+        },
+        "mutationBoundary": {
+          "enum": ["none", "handoff_may_have_occurred", "send_may_have_occurred", "control_may_have_occurred"]
+        },
+        "targetBindingDigest": { "$ref": "#/$defs/digest" }
+      }
+    }
+  }
+}

package/contracts/v1/schemas/operation-control-result.schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/schemas/operation-control-result.schema.json",
+  "title": "Transactional browser operation control result",
+  "description": "A strict versioned stop or steer envelope. The handle is the freshly reloaded parent handle; steer text is never present.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "status", "operationId", "requestDigest", "handle", "parentRequestDigest", "parentTargetBindingDigest", "controlActionId", "action", "expectedAssistantTurnId"],
+  "properties": {
+    "schemaVersion": { "const": "chatgpt.browser_control.operation_control_result.v1" },
+    "status": { "enum": ["completed", "blocked", "uncertain"] },
+    "operationId": { "$ref": "#/$defs/uuid" },
+    "requestDigest": {
+      "$ref": "#/$defs/digest",
+      "description": "Digest of the child stop or steer request; it is intentionally distinct from the parent handle digest."
+    },
+    "handle": {
+      "$ref": "#/$defs/handle",
+      "description": "Freshly reloaded parent operation handle, bound to parentRequestDigest."
+    },
+    "parentRequestDigest": {
+      "$ref": "#/$defs/digest",
+      "description": "Immutable parent operation request digest used by the handle and blocker."
+    },
+    "parentTargetBindingDigest": { "$ref": "#/$defs/digest" }, "controlActionId": { "$ref": "#/$defs/uuid" },
+    "action": { "enum": ["stop", "steer"] }, "expectedAssistantTurnId": { "$ref": "#/$defs/opaqueId" },
+    "receipt": { "$ref": "#/$defs/receipt" }, "blocker": { "$ref": "#/$defs/blocker" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "completed" } }, "required": ["status"] },
+      "then": {
+        "required": ["receipt"],
+        "properties": {
+          "receipt": { "allOf": [{ "$ref": "#/$defs/receipt" }, { "type": "object", "required": ["outcome"], "properties": { "outcome": { "const": "satisfied" } } }] },
+          "blocker": false
+        }
+      }
+    },
+    {
+      "if": { "properties": { "status": { "const": "blocked" } }, "required": ["status"] },
+      "then": {
+        "required": ["blocker"],
+        "properties": {
+          "blocker": { "$ref": "#/$defs/blocker" },
+          "receipt": { "allOf": [{ "$ref": "#/$defs/receipt" }, { "type": "object", "required": ["outcome"], "properties": { "outcome": { "const": "not_satisfied" } } }] }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "status": { "const": "uncertain" } }, "required": ["status"] },
+      "then": {
+        "required": ["blocker"],
+        "properties": {
+          "blocker": { "$ref": "#/$defs/blocker" },
+          "receipt": { "allOf": [{ "$ref": "#/$defs/receipt" }, { "type": "object", "required": ["outcome"], "properties": { "outcome": { "const": "uncertain" } } }] }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "uuid": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+    "digest": { "type": "string", "pattern": "^hmac-sha256:[0-9a-f]{64}$" },
+    "opaqueId": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]{1,512}$" },
+    "instant": { "type": "string", "pattern": "^(?!\\d{4}-02-(?:30|31)T)(?!\\d{4}-(?:04|06|09|11)-31T)\\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\\d|3[01])T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}Z$" },
+    "phase": { "enum": ["prepared", "handoff_pending", "ready", "send_pending", "submitted", "generating", "capturing", "completed", "uncertain"] },
+    "boundary": { "enum": ["none", "handoff_may_have_occurred", "send_may_have_occurred", "control_may_have_occurred"] },
+    "handle": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schemaVersion", "operationId", "requestDigest", "surface", "revision", "phase", "mutationBoundary", "targetBindingDigest"],
+      "properties": { "schemaVersion": { "const": "chatgpt.browser_control.operation_handle.v1" }, "operationId": { "$ref": "#/$defs/uuid" }, "requestDigest": { "$ref": "#/$defs/digest" }, "surface": { "enum": ["chat", "work"] }, "revision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "phase": { "$ref": "#/$defs/phase" }, "mutationBoundary": { "$ref": "#/$defs/boundary" }, "targetBindingDigest": { "$ref": "#/$defs/digest" } }
+    },
+    "receipt": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schemaVersion", "controlActionId", "parentOperationId", "parentRequestDigest", "parentTargetBindingDigest", "expectedAssistantTurnId", "requestDigest", "action", "outcome", "observedAt"],
+      "properties": {
+        "schemaVersion": { "const": "chatgpt.browser_control.operation_control_receipt.v1" }, "controlActionId": { "$ref": "#/$defs/uuid" }, "parentOperationId": { "$ref": "#/$defs/uuid" }, "parentRequestDigest": { "$ref": "#/$defs/digest" }, "parentTargetBindingDigest": { "$ref": "#/$defs/digest" }, "expectedAssistantTurnId": { "$ref": "#/$defs/opaqueId" }, "requestDigest": { "$ref": "#/$defs/digest" }, "action": { "enum": ["stop", "steer"] }, "outcome": { "enum": ["satisfied", "not_satisfied", "uncertain"] }, "evidenceDigest": { "$ref": "#/$defs/digest" }, "blockerCode": { "$ref": "#/$defs/code" }, "observedAt": { "$ref": "#/$defs/instant" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "outcome": { "const": "satisfied" } }, "required": ["outcome"] },
+          "then": {
+            "required": ["evidenceDigest"],
+            "properties": { "evidenceDigest": { "$ref": "#/$defs/digest" }, "blockerCode": false }
+          }
+        },
+        {
+          "if": { "properties": { "outcome": { "enum": ["not_satisfied", "uncertain"] } }, "required": ["outcome"] },
+          "then": { "required": ["blockerCode"] }
+        }
+      ]
+    },
+    "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" },
+    "blocker": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schemaVersion", "code", "recoverable", "operationId", "requestDigest", "phase", "mutationBoundary", "message"],
+      "properties": {
+        "schemaVersion": { "const": "chatgpt.browser_control.operation_blocker.v1" },
+        "code": { "$ref": "#/$defs/code" },
+        "recoverable": { "type": "boolean" },
+        "operationId": { "$ref": "#/$defs/uuid" },
+        "requestDigest": {
+          "$ref": "#/$defs/digest",
+          "description": "Parent operation request digest; a control blocker never identifies the child request here."
+        },
+        "phase": { "$ref": "#/$defs/phase" },
+        "mutationBoundary": { "$ref": "#/$defs/boundary" },
+        "message": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9][A-Za-z0-9 .,:;'()\\-]{0,511}$" }
+      }
+    }
+  }
+}