codex-chatgpt-control 0.1.0-alpha.1 → 0.2.0-alpha.1

package/contracts/v1/parity-suite.json

@@ -182,8 +182,14 @@
       "id": "workflows-primitives-diagnostics",
       "summary": "High-level workflows, browser primitives, named macros, and doctor diagnostics.",
       "fixtures": [
+        "blocker-explanation-profiles.json",
         "doctor-bridge-upload.json",
+        "doctor-scenario-preflight.json",
+        "existing-tab-diagnostics-blocker.json",
+        "files-preflight-success.json",
+        "project-sources-plan-add.json",
         "primitive-bootstrap-blocker.json",
+        "read-latest-clipped.json",
         "workflow-ask-success.json"
       ],
       "sourceFiles": [
@@ -192,7 +198,10 @@
         "src/commands/session.ts",
         "src/commands/threads.ts",
         "src/commands/messages.ts",
+        "src/commands/artifacts.ts",
+        "src/dom/artifacts.ts",
         "src/commands/files.ts",
+        "src/commands/project-sources.ts",
         "src/commands/modes.ts",
         "src/commands/response-actions.ts",
         "src/commands/doctor.ts"
@@ -201,7 +210,9 @@
         "tests/unit/client.test.ts",
         "tests/unit/sequence.test.ts",
         "tests/unit/messages.test.ts",
+        "tests/unit/artifacts.test.ts",
         "tests/unit/files.test.ts",
+        "tests/unit/project-sources.test.ts",
         "tests/unit/modes.test.ts",
         "tests/unit/backend-conformance.test.ts"
       ],
@@ -374,9 +385,9 @@
     },
     "doctor": {
       "surface": "workflows-primitives-diagnostics",
-      "fixtures": ["doctor-bridge-upload.json", "command-descriptors.json"],
+      "fixtures": ["doctor-bridge-upload.json", "doctor-scenario-preflight.json", "command-descriptors.json"],
       "nodeTests": ["tests/unit/client.test.ts", "tests/unit/backend-dispatch.test.ts", "tests/unit/backend-conformance.test.ts"],
-      "pythonTests": ["tests/test_workflows.py", "tests/test_cross_language_conformance.py"],
+      "pythonTests": ["tests/test_workflows.py", "tests/test_cross_language_conformance.py", "tests/test_models_complete.py"],
       "docs": ["references/troubleshooting.md", "references/backend-protocol.md", "references/python-parity.md"]
     },
     "createReport": {
@@ -486,10 +497,10 @@
     },
     "messages.readLatest": {
       "surface": "workflows-primitives-diagnostics",
-      "fixtures": ["command-descriptors.json", "run-basic-success.json"],
+      "fixtures": ["command-descriptors.json", "run-basic-success.json", "read-latest-clipped.json"],
       "nodeTests": ["tests/unit/messages.test.ts", "tests/unit/client.test.ts"],
-      "pythonTests": ["tests/test_primitives.py"],
-      "docs": ["references/backend-protocol.md", "references/python-parity.md"]
+      "pythonTests": ["tests/test_primitives.py", "tests/test_models_complete.py"],
+      "docs": ["references/backend-protocol.md", "references/troubleshooting.md", "references/python-parity.md"]
     },
     "messages.waitAndRead": {
       "surface": "workflows-primitives-diagnostics",
@@ -498,6 +509,34 @@
       "pythonTests": ["tests/test_primitives.py"],
       "docs": ["references/backend-protocol.md", "references/python-parity.md"]
     },
+    "artifacts.listLatest": {
+      "surface": "workflows-primitives-diagnostics",
+      "fixtures": ["command-descriptors.json"],
+      "nodeTests": ["tests/unit/artifacts.test.ts", "tests/unit/client.test.ts"],
+      "pythonTests": ["tests/test_primitives.py", "tests/test_async_client.py"],
+      "docs": ["references/backend-protocol.md", "references/python-parity.md"]
+    },
+    "artifacts.wait": {
+      "surface": "workflows-primitives-diagnostics",
+      "fixtures": ["command-descriptors.json"],
+      "nodeTests": ["tests/unit/artifacts.test.ts", "tests/unit/sequence.test.ts"],
+      "pythonTests": ["tests/test_primitives.py", "tests/test_async_client.py"],
+      "docs": ["references/backend-protocol.md", "references/python-parity.md"]
+    },
+    "artifacts.downloadLatest": {
+      "surface": "workflows-primitives-diagnostics",
+      "fixtures": ["command-descriptors.json"],
+      "nodeTests": ["tests/unit/artifacts.test.ts", "tests/unit/files.test.ts"],
+      "pythonTests": ["tests/test_primitives.py", "tests/test_async_client.py"],
+      "docs": ["references/backend-protocol.md", "references/python-parity.md"]
+    },
+    "files.preflight": {
+      "surface": "workflows-primitives-diagnostics",
+      "fixtures": ["files-preflight-success.json", "doctor-scenario-preflight.json", "command-descriptors.json"],
+      "nodeTests": ["tests/unit/files.test.ts", "tests/unit/client.test.ts", "tests/unit/backend-dispatch.test.ts"],
+      "pythonTests": ["tests/test_primitives.py", "tests/test_models_complete.py"],
+      "docs": ["references/backend-protocol.md", "references/troubleshooting.md", "references/python-parity.md"]
+    },
     "files.attach": {
       "surface": "workflows-primitives-diagnostics",
       "fixtures": ["run-file-attach-success.json", "command-descriptors.json"],
@@ -512,6 +551,27 @@
       "pythonTests": ["tests/test_primitives.py"],
       "docs": ["references/backend-protocol.md", "references/troubleshooting.md", "references/python-parity.md"]
     },
+    "projects.sources.list": {
+      "surface": "workflows-primitives-diagnostics",
+      "fixtures": ["command-descriptors.json"],
+      "nodeTests": ["tests/unit/project-sources.test.ts", "tests/unit/backend-dispatch.test.ts"],
+      "pythonTests": ["tests/test_primitives.py", "tests/test_async_client.py"],
+      "docs": ["references/backend-protocol.md", "references/localization.md", "references/python-parity.md"]
+    },
+    "projects.sources.planAdd": {
+      "surface": "workflows-primitives-diagnostics",
+      "fixtures": ["project-sources-plan-add.json", "command-descriptors.json"],
+      "nodeTests": ["tests/unit/project-sources.test.ts", "tests/unit/backend-dispatch.test.ts"],
+      "pythonTests": ["tests/test_primitives.py", "tests/test_async_client.py"],
+      "docs": ["references/backend-protocol.md", "references/python-parity.md"]
+    },
+    "projects.sources.add": {
+      "surface": "workflows-primitives-diagnostics",
+      "fixtures": ["project-sources-plan-add.json", "command-descriptors.json"],
+      "nodeTests": ["tests/unit/project-sources.test.ts", "tests/unit/backend-dispatch.test.ts"],
+      "pythonTests": ["tests/test_primitives.py", "tests/test_async_client.py"],
+      "docs": ["references/backend-protocol.md", "references/localization.md", "references/python-parity.md"]
+    },
     "modes.set": {
       "surface": "workflows-primitives-diagnostics",
       "fixtures": ["command-descriptors.json"],
@@ -571,6 +631,12 @@
       "command": "npm run contract:validate",
       "ciRequired": true
     },
+    {
+      "id": "node.docs-drift",
+      "cwd": "packages/node",
+      "command": "npm run docs:drift",
+      "ciRequired": true
+    },
     {
       "id": "node.parity-fixtures",
       "cwd": "packages/node",
@@ -616,7 +682,7 @@
     {
       "id": "python.pyright",
       "cwd": "packages/python",
-      "command": "python -m pyright --pythonpath \"$(which python)\" src tests",
+      "command": "python -m pyright src tests",
       "ciRequired": true
     },
     {

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

@@ -44,6 +44,9 @@
         "messages.wait",
         "messages.readLatest",
         "messages.waitAndRead",
+        "artifacts.listLatest",
+        "artifacts.wait",
+        "artifacts.downloadLatest",
         "files.attach",
         "files.downloadLatest",
         "modes.set",

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

@@ -59,6 +59,13 @@
             }
           }
         },
+        "diagnostics": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "existingTab": { "$ref": "#/$defs/existingTabDiagnostics" }
+          }
+        },
         "resumable": { "type": "boolean" }
       }
     },
@@ -94,6 +101,47 @@
   "$defs": {
     "commandStatus": {
       "enum": ["ok", "partial", "timeout", "blocked", "needs_confirmation", "not_found", "unsupported", "error"]
+    },
+    "existingTabDiagnostics": {
+      "type": "object",
+      "required": ["requestedTarget", "userOpenTabsAvailable", "chatgptTabCount", "mismatchReason", "candidateTabs"],
+      "additionalProperties": true,
+      "properties": {
+        "requestedTarget": {
+          "type": "object",
+          "required": ["type"],
+          "additionalProperties": true,
+          "properties": {
+            "type": { "type": "string", "minLength": 1 },
+            "host": { "type": "string" },
+            "tabId": { "type": "string" },
+            "conversationId": { "type": "string" },
+            "url": { "type": "string" },
+            "title": { "type": "string" },
+            "exact": { "type": "boolean" }
+          }
+        },
+        "userOpenTabsAvailable": { "type": "boolean" },
+        "chatgptTabCount": { "type": "integer", "minimum": 0 },
+        "mismatchReason": { "type": "string", "minLength": 1 },
+        "omittedCandidateCount": { "type": "integer", "minimum": 0 },
+        "candidateTabs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id"],
+            "additionalProperties": true,
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "url": { "type": "string" },
+              "title": { "type": "string" },
+              "conversationId": { "type": "string" },
+              "lastOpened": { "type": "string" },
+              "tabGroup": { "type": "string" }
+            }
+          }
+        }
+      }
     }
   }
 }

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

@@ -26,6 +26,7 @@
           "additionalProperties": true
         },
         "reportPath": { "type": "string" },
+        "untrustedOutput": { "$ref": "#/$defs/untrustedOutputReturnEnvelope" },
         "unsupported": {
           "type": "array",
           "items": { "$ref": "#/$defs/unsupportedField" }
@@ -46,6 +47,33 @@
         "reason": { "type": "string", "minLength": 1 },
         "alternative": { "type": "string" }
       }
+    },
+    "untrustedOutputReturnEnvelope": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "trusted",
+        "source",
+        "capturedAt",
+        "contentSha256",
+        "contentBytes",
+        "inline",
+        "maxInlineBytes",
+        "rendered"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "schemaVersion": { "const": "chatgpt.browser_control.untrusted_output_return.v1" },
+        "trusted": { "const": false },
+        "source": { "type": "string", "minLength": 1 },
+        "capturedAt": { "type": "string", "minLength": 1 },
+        "contentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "contentBytes": { "type": "integer", "minimum": 0 },
+        "inline": { "type": "boolean" },
+        "maxInlineBytes": { "type": "integer", "minimum": 1 },
+        "outputPath": { "type": "string" },
+        "rendered": { "type": "string", "minLength": 1 }
+      }
     }
   }
 }

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

@@ -19,6 +19,15 @@
     "status": { "$ref": "#/$defs/commandStatus" },
     "output_text": { "type": "string" },
     "finalOutput": {},
+    "data": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "outputText": { "type": "string" },
+        "untrustedOutput": { "$ref": "#/$defs/untrustedOutputReturnEnvelope" },
+        "reportPath": { "type": "string" }
+      }
+    },
     "output": {
       "type": "array",
       "items": { "$ref": "#/$defs/runItem" }
@@ -102,9 +111,57 @@
             }
           }
         },
+        "diagnostics": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "existingTab": { "$ref": "#/$defs/existingTabDiagnostics" }
+          }
+        },
         "resumable": { "type": "boolean" }
       }
     },
+    "existingTabDiagnostics": {
+      "type": "object",
+      "required": ["requestedTarget", "userOpenTabsAvailable", "chatgptTabCount", "mismatchReason", "candidateTabs"],
+      "additionalProperties": true,
+      "properties": {
+        "requestedTarget": {
+          "type": "object",
+          "required": ["type"],
+          "additionalProperties": true,
+          "properties": {
+            "type": { "type": "string", "minLength": 1 },
+            "host": { "type": "string" },
+            "tabId": { "type": "string" },
+            "conversationId": { "type": "string" },
+            "url": { "type": "string" },
+            "title": { "type": "string" },
+            "exact": { "type": "boolean" }
+          }
+        },
+        "userOpenTabsAvailable": { "type": "boolean" },
+        "chatgptTabCount": { "type": "integer", "minimum": 0 },
+        "mismatchReason": { "type": "string", "minLength": 1 },
+        "omittedCandidateCount": { "type": "integer", "minimum": 0 },
+        "candidateTabs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id"],
+            "additionalProperties": true,
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "url": { "type": "string" },
+              "title": { "type": "string" },
+              "conversationId": { "type": "string" },
+              "lastOpened": { "type": "string" },
+              "tabGroup": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
     "interruption": {
       "type": "object",
       "required": ["id", "type", "status", "message", "resume"],
@@ -133,6 +190,33 @@
       "properties": {
         "type": { "type": "string", "minLength": 1 }
       }
+    },
+    "untrustedOutputReturnEnvelope": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "trusted",
+        "source",
+        "capturedAt",
+        "contentSha256",
+        "contentBytes",
+        "inline",
+        "maxInlineBytes",
+        "rendered"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "schemaVersion": { "const": "chatgpt.browser_control.untrusted_output_return.v1" },
+        "trusted": { "const": false },
+        "source": { "type": "string", "minLength": 1 },
+        "capturedAt": { "type": "string", "minLength": 1 },
+        "contentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "contentBytes": { "type": "integer", "minimum": 0 },
+        "inline": { "type": "boolean" },
+        "maxInlineBytes": { "type": "integer", "minimum": 1 },
+        "outputPath": { "type": "string" },
+        "rendered": { "type": "string", "minLength": 1 }
+      }
     }
   }
 }

package/contracts/v1/surface-drift-policy.json

@@ -0,0 +1,210 @@
+{
+  "schemaVersion": "chatgpt.browser_control.surface_drift_policy.v1",
+  "backendCommandDescriptorExemptions": [
+    {
+      "command": "backend.version",
+      "date": "2026-06-10",
+      "reason": "Backend metadata command used by protocol clients, not a user-facing SDK command descriptor."
+    },
+    {
+      "command": "backend.health",
+      "date": "2026-06-10",
+      "reason": "Backend metadata command used by protocol clients, not a user-facing SDK command descriptor."
+    },
+    {
+      "command": "backend.capabilities",
+      "date": "2026-06-10",
+      "reason": "Backend metadata command used by protocol clients, not a user-facing SDK command descriptor."
+    },
+    {
+      "command": "runner.plan",
+      "date": "2026-06-10",
+      "reason": "Lower-level planning command covered by the runner facade and parity suite rather than a separate public descriptor."
+    },
+    {
+      "command": "runner.stream",
+      "date": "2026-06-10",
+      "reason": "Milestone streaming transport command covered by runner docs and tests rather than a separate descriptor."
+    },
+    {
+      "command": "openThread",
+      "date": "2026-06-10",
+      "reason": "Legacy workflow alias documented through threads.open and top-level workflow facade coverage."
+    },
+    {
+      "command": "readLatest",
+      "date": "2026-06-10",
+      "reason": "Legacy workflow alias documented through messages.readLatest and response capture coverage."
+    },
+    {
+      "command": "downloadLatest",
+      "date": "2026-06-10",
+      "reason": "Legacy workflow alias documented through files.downloadLatest and download coverage."
+    },
+    {
+      "command": "reports.create",
+      "date": "2026-06-10",
+      "reason": "Report helper command is represented by createReport/redacted report descriptor and report docs."
+    },
+    {
+      "command": "reports.redact",
+      "date": "2026-06-10",
+      "reason": "Report helper command is represented by createReport/redacted report descriptor and report docs."
+    },
+    {
+      "command": "reports.summarize",
+      "date": "2026-06-10",
+      "reason": "Report helper command is represented by createReport/redacted report descriptor and report docs."
+    },
+    {
+      "command": "commands",
+      "date": "2026-06-10",
+      "reason": "Command-discovery metadata command that returns descriptors; it is not itself a public descriptor."
+    },
+    {
+      "command": "describe",
+      "date": "2026-06-10",
+      "reason": "Command-discovery metadata command that returns descriptors; it is not itself a public descriptor."
+    },
+    {
+      "command": "help",
+      "date": "2026-06-10",
+      "reason": "Command-discovery metadata command that returns help text; it is not itself a public descriptor."
+    }
+  ],
+  "descriptorBackendCommandExemptions": [
+    {
+      "descriptor": "new-ask-read",
+      "date": "2026-06-10",
+      "reason": "Named sequence macro executed through runPlan, not a backend command."
+    },
+    {
+      "descriptor": "find-open-ask-read",
+      "date": "2026-06-10",
+      "reason": "Named sequence macro executed through runPlan, not a backend command."
+    },
+    {
+      "descriptor": "find-open-copy-latest",
+      "date": "2026-06-10",
+      "reason": "Named sequence macro executed through runPlan, not a backend command."
+    },
+    {
+      "descriptor": "attach-ask-read",
+      "date": "2026-06-10",
+      "reason": "Named sequence macro executed through runPlan, not a backend command."
+    },
+    {
+      "descriptor": "ask-and-download",
+      "date": "2026-06-10",
+      "reason": "Named sequence macro executed through runPlan, not a backend command."
+    },
+    {
+      "descriptor": "two-turn",
+      "date": "2026-06-10",
+      "reason": "Named sequence macro executed through runPlan, not a backend command."
+    },
+    {
+      "descriptor": "doctor-upload",
+      "date": "2026-06-10",
+      "reason": "Named sequence macro executed through runPlan, not a backend command."
+    },
+    {
+      "descriptor": "redacted-run-report",
+      "date": "2026-06-10",
+      "reason": "Named sequence macro executed through runPlan, not a backend command."
+    }
+  ],
+  "backendDispatchExemptions": [
+    {
+      "command": "runner.stream",
+      "date": "2026-06-10",
+      "reason": "Handled by BackendSession.stream instead of dispatchBackendCommand."
+    }
+  ],
+  "pythonFacadeExemptions": [
+    {
+      "command": "backend.version",
+      "date": "2026-06-10",
+      "reason": "Python exposes the generic BackendClient.request path for backend.version; health and capabilities have dedicated facades."
+    }
+  ],
+  "generatedBlockerDocs": [
+    "references/troubleshooting.md",
+    "../../tools/public-export/root/docs/troubleshooting.md",
+    "../../docs/troubleshooting.md"
+  ],
+  "docAnchors": [
+    {
+      "id": "backend-protocol-file-preflight",
+      "paths": ["references/backend-protocol.md"],
+      "terms": ["files.preflight", "does not open ChatGPT"]
+    },
+    {
+      "id": "backend-protocol-project-sources",
+      "paths": ["references/backend-protocol.md"],
+      "terms": ["projects.sources.planAdd", "confirmMutation"]
+    },
+    {
+      "id": "python-parity-file-preflight",
+      "paths": ["references/python-parity.md"],
+      "terms": ["chatgpt.files.preflight", "FilePreflightData"]
+    },
+    {
+      "id": "python-parity-project-sources",
+      "paths": ["references/python-parity.md"],
+      "terms": ["chatgpt.projects.sources", "plan_add"]
+    },
+    {
+      "id": "node-readme-blocker-explainability",
+      "paths": ["../../tools/public-export/root/packages/node/README.md", "README.md"],
+      "terms": ["explainBlocker", "structured blockers"]
+    },
+    {
+      "id": "node-readme-file-preflight",
+      "paths": ["../../tools/public-export/root/packages/node/README.md", "README.md"],
+      "terms": ["chatgpt.files.preflight", "opening ChatGPT"]
+    },
+    {
+      "id": "node-readme-project-sources",
+      "paths": ["../../tools/public-export/root/packages/node/README.md", "README.md"],
+      "terms": ["chatgpt.projects.sources.planAdd", "confirmMutation"]
+    },
+    {
+      "id": "python-readme-blocker-explainability",
+      "paths": [
+        "$pythonRoot/README.md",
+        "../../tools/public-export/root/packages/python/README.md",
+        "../python/README.md"
+      ],
+      "terms": ["explain_blocker", "structured fields"]
+    },
+    {
+      "id": "python-readme-file-preflight",
+      "paths": [
+        "$pythonRoot/README.md",
+        "../../tools/public-export/root/packages/python/README.md",
+        "../python/README.md"
+      ],
+      "terms": ["chatgpt.files.preflight", "preflight"]
+    },
+    {
+      "id": "python-readme-project-sources",
+      "paths": [
+        "$pythonRoot/README.md",
+        "../../tools/public-export/root/packages/python/README.md",
+        "../python/README.md"
+      ],
+      "terms": ["chatgpt.projects.sources.plan_add", "confirm_mutation"]
+    },
+    {
+      "id": "skill-file-preflight",
+      "paths": ["../../tools/public-export/root/skills/codex-chatgpt-control/SKILL.md", "../../skills/codex-chatgpt-control/SKILL.md"],
+      "terms": ["chatgpt.files.preflight", "does not open ChatGPT"]
+    },
+    {
+      "id": "skill-project-sources",
+      "paths": ["../../tools/public-export/root/skills/codex-chatgpt-control/SKILL.md", "../../skills/codex-chatgpt-control/SKILL.md"],
+      "terms": ["chatgpt.projects.sources.planAdd", "confirmMutation"]
+    }
+  ]
+}