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

package/references/backend-protocol.md

@@ -108,6 +108,43 @@ The final event contains a normal runner result:
 
 Streaming is milestone streaming only. It does not promise token deltas or OpenAI API stream-event parity. Partial assistant text is emitted as `message_in_progress`; only completion-confirmed output is emitted as `message_completed`.
 
+Persistent clients perform one single-flight `backend.hello` negotiation before
+admitting multiplexed work. When the backend advertises request-ID-scoped unary
+and stream multiplexing, one lifecycle-owned reader routes every response and
+event to its exact `requestId`; compatible older backends remain single-flight.
+Cancellation and timeout retain a bounded late-output tombstone. A record for a
+known tombstone is drained, while an unknown request ID quarantines and recycles
+the connection rather than being guessed into an active route.
+
+The transport retains a bounded, redacted `backend_compatibility.v1` snapshot for
+the current backend generation. Protocol or capability incompatibility rejects
+the hello before any browser command is admitted. Compatible package, runtime,
+and build differences are warnings rather than an exact package-version gate;
+the report includes a `build_digest_mismatch` warning even when package versions
+match. Missing provenance is reported as `unknown`, never inferred, and the
+snapshot contains no command list, prompts, paths, secrets, or provider output.
+
+Backpressure is bounded by both event count and encoded UTF-8 bytes. Overflow
+fails only the affected stream route and leaves unrelated correlated routes
+usable. The Node and Python clients bound aggregate queued stdin frames by
+count and bytes, and both clients bound aggregate caller/control route
+admissions with `maxInFlight`/`max_in_flight` (default `256`, minimum `2`) across
+handshake probes, waiting legacy slots, pending unary routes, async
+pre-reservations, and streams. During negotiation gaps where the handshake is
+unknown/in progress and no control route is currently charged, caller
+reservations use at most `maxInFlight - 1` slots so the transport can always
+admit the next hello/legacy control probe. Once a control route is charged, it
+counts as one ordinary live route and callers can use the full configured
+bound; the virtual headroom returns between sequential legacy probes. Saturation
+is rejected before request-ID
+reservation and every terminal, cancellation, timeout, queued-never-started
+release, and recycle path releases its live slot. The client rechecks route
+ownership immediately before writing, so a request canceled while queued is never written later. If a started stdin write
+does not settle, the child is recycled; at most one unresolved generation may
+be detached, and a second unresolved generation fails closed until teardown
+settles. These are transport liveness guards, not proof that a browser mutation
+did or did not occur.
+
 ## Required Backend Commands
 
 The backend must support:
@@ -129,6 +166,68 @@ timeout Work result is recovered through status/wait/read on the same task, not
 by resubmitting the original prompt.
 
 `doctor` returns a normal `CommandResult` whose `data.checks` map is extensible. Scenario checks such as `existing_tab`, `artifacts`, `file_preflight`, `localization`, and `reports` may add optional `code`, `blockerKind`, `nextCommand`, and JSON `details` fields to individual check entries while preserving the existing `status`, `message`, and `remediation` fields.
+The additive `compatibility` check is browser-free and exposes the retained
+report in `details`; warning and unknown provenance map to an `unknown` check,
+while a rejected negotiation maps to `blocked` and makes the report not ready.
+
+## Transactional operations (v1)
+
+The additive operation surface uses four strict backend commands:
+`operations.submit`, `operations.collect`, `operations.inspect`, and
+`operations.control`. Their request and result schemas, caller-owned
+`operationId` rules, fresh-handle recovery, and privacy boundary are defined in
+[the transactional operations reference](2026-08-16-transactional-operations.md).
+
+These commands are not aliases for `messages.submit`, `messages.wait`, or the
+legacy workflow runner. `operations.submit` creates/reconciles one journal
+record and returns an accepted/completed/blocked/uncertain envelope;
+`operations.collect` observes only that operation's owned turn;
+`operations.inspect` is browser-free durable inspection; and `operations.control`
+binds one Stop or Work steer to a generating parent handle. `operations.run`
+is an SDK composition, not a fifth wire command.
+
+`operations.inspect` is browser-free and may include the same additive
+`compatibility` report projected from the lifecycle-owned transport. It does not
+reopen a tab or perform a browser read.
+
+Transactional wire validation rejects unsupported fields before browser use.
+The backend redacts adapter/journal failures at the protocol boundary so raw
+prompts, local paths, URLs, and provider-private diagnostics do not cross the
+NDJSON response. With no custom adapter seam, the default client constructs a
+lazy request-local ChatGPT adapter after journal admission and fails closed if
+the bridge, authenticated target evidence, or required provider primitive is
+unavailable. A custom adapter configuration must supply the complete adapter
+factory set; neither path falls back to a legacy sequence.
+
+The default local journal requires real process identity, platform-appropriate
+file ownership, and process-liveness authority. It validates those host
+capabilities before creating journal directories or touching the browser. When
+they are unavailable and no explicit journal service is configured, an
+operation-aware high-level `ask` returns the normal command
+result shape with `status: "blocked"`, `blocker.kind: "unknown"`,
+`blocker.code: "journal_runtime_unavailable"`, `blocker.resumable: false`, and
+`error.recoverable: false`. The bounded remediation uses the established
+`label`, `instruction`, and `userActionRequired` fields. This is an unavailable
+runtime result, not evidence of composer drift or a successful submission.
+The shared `journal-runtime-unavailable.json` fixture is generated through the
+public facade and preserves that result across Python decoding.
+
+As verified on 2026-09-06, the restricted Codex JavaScript host used for issue
+41 exposes its browser bridge but does not expose the required process APIs.
+It can run compatibility workflows, but its default local journal is
+unavailable. An explicitly started normal Node journal service supplies durable
+storage and signing through the authenticated private-file connection while
+browser actions remain in the active bridge host. Configure
+`operations.journalService.descriptorPath` as described in the
+[journal service runbook](2026-09-06-journal-service.md). A plain Node subprocess
+still cannot inherit the browser bridge. Do not substitute PID or owner values,
+install a fake `process`, disable ownership checks, or infer that an unknown
+lock owner is dead. An automatic retry or a new operation ID cannot repair a
+missing host capability.
+
+`operations.collect` optionally accepts `pollIntervalMs`, an integer from `0`
+through `60000`. It controls only the interval between bounded observation
+attempts. Poll sleeps occur outside browser/tab transactions.
 
 ## Host-Local Attachment Paths
 
@@ -185,6 +284,29 @@ reported as structured blockers such as
 `artifact_unavailable`, `artifact_selector_drift`, or
 `artifact_download_unavailable`, not protocol errors.
 
+After a visible download activation, the runtime requires the browser bridge's
+native completion receipt within the operation deadline. An unverified
+completion returns `download_receipt_timeout` with kind `download_unavailable`,
+status `blocked`, and nonresumable/nonrecoverable flags. It does not retry the
+activation or switch download strategies, and preserves existing browser
+downloads. A bridge that cannot expose a native receipt remains unsupported
+for verified download completion.
+
+A structurally identified Chrome error page with the exact
+`ERR_BLOCKED_BY_CLIENT` code returns `download_blocked_by_browser` with the same
+`download_unavailable` kind, blocked status, and nonresumable/nonrecoverable
+flags. Text mentioning that code in a normal conversation is not browser-error
+evidence. The runtime does not retry the activation or bypass browser
+restrictions; the caller receives no successful download receipt and completion
+remains unverified. This browser-error observation is distinct from a native
+receipt timeout.
+
+Other native event or activation failures return `download_receipt_failed`
+with the same blocked and nonretryable semantics. A fixed message replaces
+native error details, which may include sensitive download URLs. The runtime
+supplies no successful receipt and does not switch to another strategy after
+an uncertain activation.
+
 `session.bootstrap` accepts `existingTab` for explicit reuse of a user-open Chrome tab before any read or prompt step. The wire shape is shared by TypeScript and Python:
 
 ```json
@@ -261,6 +383,56 @@ python scripts/live_smoke.py --mode ordinary-shell
 
 In an ordinary shell without Codex browser bridge access, browser-required commands must return a structured `browser_bridge_unavailable` blocker. This is a successful smoke result when the backend process stays alive and protocol calls such as `backend.health` and `commands` succeed.
 
+## Transactional Live Qualification
+
+Compatibility live smokes and release canaries do not qualify submit-once
+behavior. The additive Node live scenario `transactional-submit-once` is
+explicitly enabled with `CHATGPT_E2E_TRANSACTIONAL=1`; select that scenario
+alone when using `CHATGPT_E2E_SCENARIOS` or the live-smoke module's scenario
+filter. In a supported host with an already initialized browser bridge:
+
+```javascript
+const selected = smoke.filterScenarios(smoke.optionalScenarios, "transactional-submit-once");
+const run = await smoke.runLiveSmoke({
+  agent,
+  browser,
+  reportDir: "/absolute/path/to/local/reports/live-smoke",
+  env: {
+    CHATGPT_E2E_TRANSACTIONAL: "1",
+    // Optional when the browser host requires the separate journal service.
+    CHATGPT_E2E_JOURNAL_DESCRIPTOR: "/absolute/private/session/connection.json"
+  }
+}, selected);
+const qualified = run.results.length === 1 && run.results[0].status === "pass";
+```
+
+Here `smoke` is the imported `codex-chatgpt-control-live-smoke.bundle.mjs`.
+The scenario creates one synthetic Chat conversation using the public `ask`
+facade and the default production runtime, with a fresh UUID, zero files, and a
+multiline prompt. It performs submit-only, bounded collect, owned-receipt
+verification, and a same-ID replay only after a completed receipt. It verifies
+one satisfied Send action, the same operation/request/target handle, and exactly
+one user/assistant exchange in the same established conversation before and
+after replay. For `ambiguous_submit` only, it may make one observation-only
+same-ID recovery after inspection proves the matching target and a durable
+`observe_only_after_intent` Send action at the `send_may_have_occurred` boundary.
+It then verifies the same action and intent survived recovery. Other blockers
+stop qualification; there is no blind resubmission or replacement operation ID.
+Reports contain only structural evidence, response length/hash, and fixed
+status codes.
+
+This scenario is optional, so inspect its own `status`; an empty
+`requiredFailures` list does not establish a pass. A missing host capability,
+pending collect, absent receipt, or changed turn count fails qualification.
+Without the explicit service, the restricted Codex host described above fails
+with `journal_runtime_unavailable`. Configuring the service makes that host
+eligible for this qualification; the scenario must still pass submit, collect,
+receipt and replay checks. A successful journal connection alone does not
+qualify browser behavior. Python fixture and facade checks validate result
+preservation; Python operation-aware relay qualification remains a separate
+gate requiring a live bridge-hosted Node backend and a permitted transport to
+that backend.
+
 ## Browser-Bridge Smoke
 
 Run only when intentionally operating a backend with live browser access:
@@ -355,3 +527,7 @@ npm run test:backend-conformance
 ```
 
 Python must also load and round-trip the same fixtures through Pydantic models. Any future backend implementation should pass these fixtures before claiming compatibility.
+
+## Restricted-host journal authority
+
+The Node backend can use an explicit asynchronous journal service while keeping browser control in its active host. See [the journal service runbook](2026-09-06-journal-service.md) for startup, recovery, transport boundaries, and the intentional TypeScript host API asymmetry. Operation wire shapes and Python facades are unchanged. The private-file transport rejects Windows with `journal_rpc_unsupported_platform` before filesystem access; the existing local Node journal path is unchanged.

package/references/python-parity.md

@@ -30,6 +30,98 @@ Wire fields stay TypeScript-compatible. Python exposes idiomatic aliases:
 | `newTask` | `new_task` |
 | `includeArtifacts` | `include_artifacts` |
 
+Negotiated compatibility is also shared contract behavior. The Node and Python
+transports retain a bounded `BackendCompatibilityReport` for the current
+backend generation and expose it through `compatibility_report()` (or the
+TypeScript equivalent). Protocol/capability rejection blocks before browser
+commands; package, runtime, and build differences are precise warnings, not an
+exact package-version requirement. A matching package version with a different
+build digest remains a `build_digest_mismatch` warning. Unknown provenance stays
+unknown. The report is redacted and contains no command list, prompt, path,
+secret, or provider output.
+
+## Transactional operations parity
+
+The direct v1 operation surface is shared by TypeScript and Python through the
+same strict wire schemas and backend commands:
+
+- `operations.submit`
+- `operations.collect`
+- `operations.inspect`
+- `operations.control`
+
+Python exposes sync `OperationsClient` and async `AsyncOperationsClient` on the
+`ChatGPT`/`AsyncChatGPT` facades. Their keyword aliases are idiomatic
+snake_case (`operation_id`, `response_content`, `timeout_ms`,
+`control_action_id`), but `to_wire()` always emits the TypeScript-compatible
+camelCase fields. Every envelope validates operation ID, request digest, fresh
+handle, target binding, receipt/blocker identity, and mutation-boundary
+monotonicity before returning to the caller. `run()` is local composition of
+one submit and at most one collect; it is not a fifth backend command.
+`operations.inspect` projects the transport compatibility snapshot into its
+additive `compatibility` field without browser access. `doctor` exposes the same
+report in its browser-free `compatibility` check; a warning or unknown
+provenance is diagnostic and does not block readiness, while rejected
+negotiation is blocked.
+
+The immutable submit capture contract is exposed as
+`OperationDurableCapturePolicy` (with the `OperationCapturePolicyState` alias)
+and is serialized as the path-free `capturePolicy` object on created/state
+records. It contains only `responseContent`, `responseFormat` (defaulting to
+`markdown`), and `artifacts`; request-local `outputDirectory` is never accepted
+on a durable model. A recovered `transfer` policy remains a transfer
+obligation until a new request-local destination is explicitly authorized.
+
+This direct parity does not make Python a second browser runtime. The current
+backend remains Node-backed and, with no custom seam, creates the same lazy
+request-local ChatGPT adapter as the TypeScript client. Browser-touching calls
+still require a bridge-enabled runtime, authenticated target evidence, and the
+required provider primitives. `inspect` is browser-free; an ordinary
+Python-spawned Node process cannot inherit Codex's in-process bridge, so
+ordinary-shell checks can exercise request/result validation and structured
+blockers without claiming live ChatGPT control. Raw
+`liveResponse` content is explicitly ephemeral and is never accepted into a
+durable receipt or operation state.
+
+Operation-aware Python `ask` preserves the Node host blocker
+`journal_runtime_unavailable` as a `CommandResult` with `status == "blocked"`,
+`blocker["kind"] == "unknown"`, `blocker["resumable"] == False`, and
+`error["recoverable"] == False`, including the existing remediation fields.
+Sync and async facades return it after one backend request; they do not replace
+it with transport uncertainty, retry, or open another operation. The shared
+`journal-runtime-unavailable.json` fixture covers exact wire round-tripping.
+No Python model or browser implementation change is needed because the
+TypeScript journal remains authoritative.
+
+The default local journal requires real process identity, platform-appropriate
+ownership, and process-liveness APIs before filesystem or browser mutation.
+The restricted Codex JavaScript host observed on 2026-09-06 lacks those APIs
+even though its browser bridge works. Configure the explicit journal service
+on its bridge-hosted Node `BackendSession` to provide storage and signing from
+a normal Node process. The Python facade and operation protocol stay unchanged.
+A Python-to-Node relay alone cannot supply journal authority, and a plain Node
+subprocess cannot inherit the browser bridge. Do not spoof process identity,
+weaken ownership/lock checks, or retry with a new UUID.
+
+The TypeScript and Python high-level Runner and Responses adapters now have an
+explicit caller-owned operation-ID opt-in. Python accepts the idiomatic
+`operation_id` keyword (or the `operation_id`/`operationId` member of the
+runner input), validates it and all supported combinations before backend
+traffic, then routes exactly one submit followed by at most one collect through
+the shared operation facade. Legacy calls with no operation ID retain their
+existing `runner.run`/`responses.create` transport path. Returned run/response
+data carries the validated operation ID and fresh handle; pending, blocked, and
+uncertain operation envelopes remain partial/blocked results with their
+contract blocker, while identity mismatches fail closed. The full request,
+recovery, coordinator, privacy, and compatibility boundary is documented in
+[Transactional browser operations](2026-08-16-transactional-operations.md).
+
+Direct Python `collect`/`run` expose `poll_interval_ms`; transactional Runner
+wait objects additionally accept `pollMs`, `poll_ms`, `pollIntervalMs`, or
+`poll_interval_ms` when aliases agree. The wire field is `pollIntervalMs`, its
+range is the inclusive integer interval `0..60000`, and sleeping never holds a
+browser/tab coordinator transaction.
+
 Incomplete response capture is also shared contract behavior. Python must preserve `status == "partial"`, `output_text`, warnings, and any nested `data.captureLimit` dictionaries exactly as the TypeScript backend returns them. `partial` is not a protocol error: callers should inspect `data.complete` and run another wait/read on the same thread when they need final output.
 
 For long-answer polling, Python forwards `response_content="metadata"` to the shared wire field `responseContent: "metadata"` on `messages.wait`. The TypeScript backend then omits assistant text from wait results and returns compact metadata such as `data.responseChars` and `data.responseSha256`; Python must preserve those fields without trying to reconstruct omitted content.
@@ -43,6 +135,23 @@ the same backend commands through `chatgpt.artifacts.list_latest(...)`,
 `chatgpt.artifacts.wait(...)`, and `chatgpt.artifacts.download_latest(...)`.
 Those methods forward to `artifacts.listLatest`, `artifacts.wait`, and
 `artifacts.downloadLatest`; they do not duplicate DOM or selector logic.
+
+Python preserves the backend's `download_receipt_timeout` blocker when native
+browser download completion cannot be verified within the deadline. The result
+is blocked, nonresumable and nonrecoverable; the facade does not retry the
+activation or select an alternate download path. Existing browser downloads
+remain in place. Python also preserves `download_blocked_by_browser` when the
+TypeScript runtime identifies Chrome's `ERR_BLOCKED_BY_CLIENT` error page. It
+is a blocked, nonresumable, nonrecoverable command result with no download
+receipt; Python does not retry or duplicate the browser-error detection. The
+shared `download-blocked-by-browser.json` fixture and Python snapshot test lock
+this behavior without adding wire fields or Python-specific browser logic.
+The `download-receipt-failed.json` fixture also preserves the sanitized
+`download_receipt_failed` result from native event or activation failures:
+blocked status, no receipt, and false resumable/recoverable flags. Python keeps
+the fixed backend message and never reconstructs native error details or
+retries an uncertain activation.
+
 If the TypeScript runtime recovers a generated image by reopening a stalled
 claimed conversation in a temporary bridge-owned tab and exporting through
 `pageAssets`, Python observes the same command result through the backend
@@ -183,6 +292,30 @@ Python is a native SDK facade over the local backend protocol. The initial brows
 - Ordinary-shell smoke passes when browser-required calls return structured `browser_bridge_unavailable`.
 - Browser-bridge runtime smoke remains explicitly gated because it can operate a real ChatGPT session.
 
+## Transactional Qualification Is Separate
+
+The opt-in Node scenario `transactional-submit-once` uses the default public
+runtime with `CHATGPT_E2E_TRANSACTIONAL=1`. It verifies a fresh-ID multiline,
+zero-file ask, owned collection, a completed receipt, and same-ID replay with
+one Send and one user/assistant exchange. One `ambiguous_submit` recovery is
+permitted only after proving the existing observation-only Send intent and
+matching target; other blockers stop qualification. See [Transactional Live Qualification](backend-protocol.md#transactional-live-qualification)
+for selection and report checks. A host blocker is a failed qualification,
+even when ordinary-shell blocker handling or compatibility browser smokes
+pass.
+
+Python's existing `scripts/live_smoke.py --mode browser-bridge` matrix omits
+operation IDs and therefore covers compatibility workflows. Its success does
+not establish transactional parity. This patch adds shared-fixture and
+sync/async `ask` preservation coverage; full Python operation-aware relay
+qualification remains a separate gate. It requires a bridge-hosted Node backend
+with either a supported local journal or the configured journal service, plus
+a permitted Python-to-backend transport. The existing HTTP test relay is
+unavailable where that browser host forbids local sockets; filesystem journal
+transport does not itself provide a Python backend relay. Keep browser
+interaction and ownership verification in TypeScript rather than adding Python
+DOM selectors.
+
 ## Browser-Bridge Smoke
 
 Run this only when you intentionally want Python to drive a live backend with browser access:
@@ -246,3 +379,7 @@ Smoke output is a redacted JSON summary. It reports output matches and lengths,
 | `0` | All browser-bridge scenarios passed. |
 | `1` | At least one scenario failed unexpectedly. |
 | `2` | Scenarios recorded documented blockers such as `browser_bridge_unavailable`, `login_required`, or `selector_drift`. |
+
+## Restricted-host journal authority
+
+The Node backend can use an explicit asynchronous journal service while keeping browser control in its active host. See [the journal service runbook](2026-09-06-journal-service.md) for startup, recovery, transport boundaries, and the intentional TypeScript host API asymmetry. Operation wire shapes and Python facades are unchanged. Python preserves `journal_rpc_unsupported_platform` when the Node backend rejects the private-file transport on Windows; it does not bypass the platform guard. Existing local Node journal behavior on Windows is unchanged.

package/references/responses-adapter.md

@@ -5,6 +5,7 @@
 Accepted fields:
 
 - `input`
+- `operationId` (TypeScript transactional opt-in; caller-owned canonical UUID)
 - `thread`
 - `existingTab`
 - `preferExistingTab`
@@ -22,6 +23,7 @@ Rejected API-only fields return `status: "unsupported"` before any prompt is sub
 
 ```ts
 const response = await chatgpt.responses.create({
+  operationId: "123e4567-e89b-42d3-a456-426614174000",
   input: "Summarize the latest plan.",
   thread: { type: "conversationId", conversationId: "abc-123" },
   experience: "chat",
@@ -31,6 +33,23 @@ const response = await chatgpt.responses.create({
 });
 ```
 
+In the TypeScript adapter, supplying `operationId` selects the additive
+transactional runner path and returns the operation ID and fresh handle in
+`response.browser_control` when the mapper reaches the operation boundary.
+Omitting it retains the legacy Responses/runner path. The transactional path
+still accepts only visible-prefix instructions, rejects API-only fields before
+browser use, and does not provide token-delta streaming. With no custom seam,
+the client creates a lazy request-local ChatGPT adapter; it fails closed when
+the bridge, target evidence, or required provider primitive is unavailable.
+Use
+[Transactional browser operations](2026-08-16-transactional-operations.md) for
+submit/collect/inspect/control recovery and capability rules.
+
+The Python `ResponsesClient` accepts the idiomatic `operation_id` alias and
+returns the same operation ID and fresh handle in `browser_control`. It validates
+transactional combinations before transport and never resubmits an accepted
+operation.
+
 `experience` and `configuration` represent visible product controls, not API
 model selection. Configuration is strict through the runner plan and must
 verify the visible postcondition. Existing callers may continue to pass

package/references/streaming.md

@@ -13,3 +13,9 @@ const result = await stream.completed;
 ```
 
 This is not token streaming. Events are emitted for browser-control milestones such as `message_submitted`, `message_completed`, `file_attached`, and `run_blocked`. Do not expect token deltas or OpenAI API stream event parity.
+
+Supplying a caller-owned `operationId` opts the runner into the transactional
+submit/collect mapper, but does not change this stream contract. Polling and
+long waits belong to operation collection outside short page transactions; use
+the returned handle with `operations.inspect`/`operations.collect` for exact
+turn recovery. See [Transactional browser operations](2026-08-16-transactional-operations.md).