codex-chatgpt-control 0.1.0-alpha.1

package/contracts/v1/schemas/agent.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/agent.schema.json",
+  "type": "object",
+  "required": ["kind", "name", "instructionsMode", "defaults", "tools", "guardrails"],
+  "additionalProperties": false,
+  "properties": {
+    "kind": { "const": "chatgpt_browser_agent" },
+    "name": { "type": "string", "minLength": 1 },
+    "instructions": { "type": "string" },
+    "instructionsMode": {
+      "enum": ["visible_prefix", "visible_setup_message", "metadata_only"]
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "command"],
+        "additionalProperties": true,
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "command": { "type": "string", "minLength": 1 },
+          "risk": { "enum": ["low", "medium", "high"] }
+        }
+      }
+    },
+    "guardrails": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "scope"],
+        "additionalProperties": true,
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "scope": { "enum": ["input", "plan", "step", "output", "report"] }
+        }
+      }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

package/contracts/v1/schemas/backend-event.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/backend-event.schema.json",
+  "type": "object",
+  "required": ["schemaVersion", "type"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "chatgpt.browser_control.backend_event.v1" },
+    "requestId": { "type": "string", "minLength": 1 },
+    "type": {
+      "enum": ["run_item_stream_event", "agent_updated_stream_event", "completed", "error"]
+    },
+    "name": { "type": "string", "minLength": 1 },
+    "item": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "agent": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "result": {},
+    "error": { "$ref": "#/$defs/protocolError" }
+  },
+  "oneOf": [
+    {
+      "required": ["name", "item"],
+      "properties": {
+        "type": { "const": "run_item_stream_event" },
+        "name": { "type": "string", "minLength": 1 },
+        "item": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    {
+      "required": ["agent"],
+      "properties": {
+        "type": { "const": "agent_updated_stream_event" },
+        "agent": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    },
+    {
+      "required": ["result"],
+      "properties": {
+        "type": { "const": "completed" },
+        "result": {}
+      }
+    },
+    {
+      "required": ["error"],
+      "properties": {
+        "type": { "const": "error" },
+        "error": { "$ref": "#/$defs/protocolError" }
+      }
+    }
+  ],
+  "$defs": {
+    "protocolError": {
+      "type": "object",
+      "required": ["code", "message", "recoverable"],
+      "additionalProperties": false,
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "recoverable": { "type": "boolean" }
+      }
+    }
+  }
+}

package/contracts/v1/schemas/backend-request.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/backend-request.schema.json",
+  "type": "object",
+  "required": ["schemaVersion", "command"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "chatgpt.browser_control.backend_request.v1" },
+    "requestId": { "type": "string", "minLength": 1 },
+    "command": {
+      "enum": [
+        "backend.version",
+        "backend.health",
+        "backend.capabilities",
+        "runner.run",
+        "runner.plan",
+        "runner.stream",
+        "responses.create",
+        "ask",
+        "askInThread",
+        "askWithFiles",
+        "askAndDownload",
+        "runMessages",
+        "openThread",
+        "readLatest",
+        "copyLatest",
+        "downloadLatest",
+        "runPlan",
+        "doctor",
+        "createReport",
+        "reports.create",
+        "reports.redact",
+        "reports.summarize",
+        "commands",
+        "describe",
+        "help",
+        "session.bootstrap",
+        "threads.new",
+        "threads.search",
+        "threads.open",
+        "messages.compose",
+        "messages.submit",
+        "messages.ask",
+        "messages.wait",
+        "messages.readLatest",
+        "messages.waitAndRead",
+        "files.attach",
+        "files.downloadLatest",
+        "modes.set",
+        "tools.select",
+        "response.copy"
+      ]
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

package/contracts/v1/schemas/backend-response.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/backend-response.schema.json",
+  "type": "object",
+  "required": ["schemaVersion", "ok"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "chatgpt.browser_control.backend_response.v1" },
+    "requestId": { "type": "string", "minLength": 1 },
+    "ok": { "type": "boolean" },
+    "result": {},
+    "error": { "$ref": "#/$defs/protocolError" }
+  },
+  "oneOf": [
+    {
+      "required": ["result"],
+      "properties": {
+        "ok": { "const": true },
+        "result": {}
+      }
+    },
+    {
+      "required": ["error"],
+      "properties": {
+        "ok": { "const": false },
+        "error": { "$ref": "#/$defs/protocolError" }
+      }
+    }
+  ],
+  "$defs": {
+    "protocolError": {
+      "type": "object",
+      "required": ["code", "message", "recoverable"],
+      "additionalProperties": false,
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "recoverable": { "type": "boolean" }
+      }
+    }
+  }
+}

package/contracts/v1/schemas/capabilities.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/capabilities.schema.json",
+  "type": "object",
+  "required": ["protocolVersion", "commands", "transports", "streaming"],
+  "additionalProperties": false,
+  "properties": {
+    "protocolVersion": { "const": "chatgpt.browser_control.backend_request.v1" },
+    "commands": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "transports": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "enum": ["stdio", "http"] }
+    },
+    "streaming": {
+      "type": "object",
+      "required": ["modes", "tokenDeltas"],
+      "additionalProperties": false,
+      "properties": {
+        "modes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "enum": ["ndjson", "sse"] }
+        },
+        "tokenDeltas": { "const": false }
+      }
+    }
+  }
+}

package/contracts/v1/schemas/command-descriptor.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/command-descriptor.schema.json",
+  "type": "object",
+  "required": ["name", "layer", "summary", "risk", "args", "defaults", "retryPolicy", "blockers", "examples"],
+  "additionalProperties": true,
+  "properties": {
+    "name": { "type": "string", "minLength": 1 },
+    "layer": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string", "minLength": 1 },
+    "risk": { "enum": ["low", "medium", "high"] },
+    "defaultTimeoutMs": { "type": "integer", "minimum": 0 },
+    "args": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "retryPolicy": { "type": "string", "minLength": 1 },
+    "blockers": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "examples": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/contracts/v1/schemas/command-result.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/command-result.schema.json",
+  "type": "object",
+  "required": ["ok", "status", "warnings", "context"],
+  "additionalProperties": true,
+  "properties": {
+    "ok": { "type": "boolean" },
+    "status": { "$ref": "#/$defs/commandStatus" },
+    "data": {},
+    "output_text": { "type": "string" },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "reportPath": { "type": "string" },
+    "error": {
+      "type": "object",
+      "required": ["name", "message", "recoverable"],
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "recoverable": { "type": "boolean" }
+      }
+    },
+    "blocker": {
+      "type": "object",
+      "required": ["kind", "message"],
+      "additionalProperties": true,
+      "properties": {
+        "kind": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "visibleText": { "type": "string" },
+        "code": { "type": "string" },
+        "fieldPath": { "type": "string" },
+        "remediation": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["label", "instruction", "userActionRequired"],
+            "additionalProperties": true,
+            "properties": {
+              "label": { "type": "string", "minLength": 1 },
+              "instruction": { "type": "string", "minLength": 1 },
+              "userActionRequired": { "type": "boolean" }
+            }
+          }
+        },
+        "candidates": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["label"],
+            "additionalProperties": true,
+            "properties": {
+              "label": { "type": "string", "minLength": 1 },
+              "role": { "type": "string" }
+            }
+          }
+        },
+        "resumable": { "type": "boolean" }
+      }
+    },
+    "context": {
+      "type": "object",
+      "required": ["timestamp"],
+      "additionalProperties": true,
+      "properties": {
+        "timestamp": { "type": "string", "minLength": 1 }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "command", "status", "ok", "startedAt", "endedAt", "warnings"],
+        "additionalProperties": true,
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "command": { "type": "string", "minLength": 1 },
+          "status": { "$ref": "#/$defs/commandStatus" },
+          "ok": { "type": "boolean" },
+          "startedAt": { "type": "string", "minLength": 1 },
+          "endedAt": { "type": "string", "minLength": 1 },
+          "warnings": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "commandStatus": {
+      "enum": ["ok", "partial", "timeout", "blocked", "needs_confirmation", "not_found", "unsupported", "error"]
+    }
+  }
+}

package/contracts/v1/schemas/manifest.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/manifest.schema.json",
+  "type": "object",
+  "required": ["schemaVersion", "contractVersion", "wireCase", "schemas", "fixtures"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "chatgpt.browser_control.contract_manifest.v1" },
+    "contractVersion": { "type": "string", "minLength": 1 },
+    "wireCase": { "const": "camelCaseWithDocumentedAliases" },
+    "schemas": {
+      "type": "object",
+      "required": [
+        "runResult",
+        "response",
+        "streamEvent",
+        "commandDescriptor",
+        "commandResult",
+        "sequencePlan",
+        "agent",
+        "backendRequest",
+        "backendResponse",
+        "backendEvent",
+        "capabilities"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "runResult": { "type": "string", "minLength": 1 },
+        "response": { "type": "string", "minLength": 1 },
+        "streamEvent": { "type": "string", "minLength": 1 },
+        "commandDescriptor": { "type": "string", "minLength": 1 },
+        "commandResult": { "type": "string", "minLength": 1 },
+        "sequencePlan": { "type": "string", "minLength": 1 },
+        "agent": { "type": "string", "minLength": 1 },
+        "backendRequest": { "type": "string", "minLength": 1 },
+        "backendResponse": { "type": "string", "minLength": 1 },
+        "backendEvent": { "type": "string", "minLength": 1 },
+        "capabilities": { "type": "string", "minLength": 1 }
+      }
+    },
+    "fixtures": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "schema", "case"],
+        "additionalProperties": false,
+        "properties": {
+          "file": { "type": "string", "minLength": 1 },
+          "schema": {
+            "enum": [
+              "runResult",
+              "response",
+              "streamEvent",
+              "commandDescriptor",
+              "commandResult",
+              "sequencePlan",
+              "agent",
+              "backendRequest",
+              "backendResponse",
+              "backendEvent",
+              "capabilities"
+            ]
+          },
+          "case": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/contracts/v1/schemas/response.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/response.schema.json",
+  "type": "object",
+  "required": ["id", "object", "created_at", "status", "output_text", "output", "browser_control"],
+  "additionalProperties": true,
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "object": { "const": "chatgpt.browser.response" },
+    "created_at": { "type": "integer", "minimum": 0 },
+    "status": { "$ref": "#/$defs/commandStatus" },
+    "output_text": { "type": "string" },
+    "output": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "browser_control": {
+      "type": "object",
+      "required": ["visibleUi", "resultStatus"],
+      "additionalProperties": true,
+      "properties": {
+        "visibleUi": { "type": "boolean" },
+        "resultStatus": { "$ref": "#/$defs/commandStatus" },
+        "thread": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "reportPath": { "type": "string" },
+        "unsupported": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/unsupportedField" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "commandStatus": {
+      "enum": ["ok", "partial", "timeout", "blocked", "needs_confirmation", "not_found", "unsupported", "error"]
+    },
+    "unsupportedField": {
+      "type": "object",
+      "required": ["path", "reason"],
+      "additionalProperties": true,
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 },
+        "alternative": { "type": "string" }
+      }
+    }
+  }
+}

package/contracts/v1/schemas/run-result.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://local.codex-chatgpt-control/contracts/v1/run-result.schema.json",
+  "type": "object",
+  "required": [
+    "ok",
+    "status",
+    "output_text",
+    "output",
+    "newItems",
+    "interruptions",
+    "state",
+    "warnings",
+    "context"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "ok": { "type": "boolean" },
+    "status": { "$ref": "#/$defs/commandStatus" },
+    "output_text": { "type": "string" },
+    "finalOutput": {},
+    "output": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/runItem" }
+    },
+    "newItems": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/runItem" }
+    },
+    "interruptions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/interruption" }
+    },
+    "state": { "$ref": "#/$defs/runState" },
+    "activeAgentName": { "type": "string" },
+    "lastAgentName": { "type": "string" },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "context": {
+      "type": "object",
+      "required": ["timestamp"],
+      "additionalProperties": true,
+      "properties": {
+        "timestamp": { "type": "string", "minLength": 1 }
+      }
+    },
+    "blocker": { "$ref": "#/$defs/blocker" },
+    "reportPath": { "type": "string" }
+  },
+  "$defs": {
+    "commandStatus": {
+      "enum": ["ok", "partial", "timeout", "blocked", "needs_confirmation", "not_found", "unsupported", "error"]
+    },
+    "runState": {
+      "type": "object",
+      "required": ["id", "resumable"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "resumable": { "type": "boolean" },
+        "thread": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "nextStepId": { "type": "string" }
+      }
+    },
+    "blocker": {
+      "type": "object",
+      "required": ["kind", "message"],
+      "additionalProperties": true,
+      "properties": {
+        "kind": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "visibleText": { "type": "string" },
+        "code": { "type": "string" },
+        "fieldPath": { "type": "string" },
+        "remediation": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["label", "instruction", "userActionRequired"],
+            "additionalProperties": true,
+            "properties": {
+              "label": { "type": "string", "minLength": 1 },
+              "instruction": { "type": "string", "minLength": 1 },
+              "userActionRequired": { "type": "boolean" }
+            }
+          }
+        },
+        "candidates": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["label"],
+            "additionalProperties": true,
+            "properties": {
+              "label": { "type": "string", "minLength": 1 },
+              "role": { "type": "string" }
+            }
+          }
+        },
+        "resumable": { "type": "boolean" }
+      }
+    },
+    "interruption": {
+      "type": "object",
+      "required": ["id", "type", "status", "message", "resume"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "type": { "type": "string", "minLength": 1 },
+        "status": { "$ref": "#/$defs/commandStatus" },
+        "message": { "type": "string", "minLength": 1 },
+        "resume": {
+          "type": "object",
+          "required": ["supported"],
+          "additionalProperties": true,
+          "properties": {
+            "supported": { "type": "boolean" },
+            "stateId": { "type": "string" },
+            "reason": { "type": "string" }
+          }
+        }
+      }
+    },
+    "runItem": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": true,
+      "properties": {
+        "type": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}