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

package/references/localization.md

@@ -52,9 +52,9 @@ workflow selector.
 
 Two rules that never change regardless of language:
 
-- **API keys stay English.** Callers pass `model: "Pro"`,
-  `intelligence: "Pro"`, `modelVersion: "5.4"`, `effort: "Thinking"`, or
-  `tool: "web_search"`. Only the *matched DOM text* is localized. You add the
+- **API keys stay English.** Callers pass `experience: "work"`,
+  `model: "GPT-5.6 Sol"`, `intelligence: "Pro"`, `effort: "High"`,
+  `speed: "Standard"`, or `tool: "web_search"`. Only the *matched DOM text* is localized. You add the
   German label to the registry array; the caller-facing key is untouched.
 - **Structural anchors are language-agnostic and are not in this file.** Element ids
   (`#composer-plus-btn`, `#upload-files`), `data-message-author-role`,
@@ -68,6 +68,11 @@ Localized — lives in `src/dom/locale/en.ts` (English) and per-locale files, sa
 | Registry key | Surface | Capture from |
 |---|---|---|
 | `composerTextbox` | composer textbox | `aria-label` |
+| `workComposerTextbox` | Work composer textbox | `aria-label` / placeholder |
+| `newWork` | start-another-Work-task control | visible button or link text |
+| `experienceOptions.chat` / `.work` | Chat/Work switch controls | visible button, tab, link, or menu text |
+| `configurationAxes.*` | model/intelligence/effort/speed/advanced rows | visible row text |
+| `configurationOptions.*` | Chat and Work configuration values | visible menu text |
 | `sendButton` | send button | `aria-label` |
 | `searchChatsButton` | search-chats button | `aria-label` |
 | `searchChatsPlaceholder` | search input | `placeholder` (mind the ellipsis — see caveats) |
@@ -77,7 +82,8 @@ Localized — lives in `src/dom/locale/en.ts` (English) and per-locale files, sa
 | `projectSourcesTab` / `projectSourcesAddSource` / `projectSourcesUploadFiles` | Project Sources tab and append-add flow | visible tab/button/menu text |
 | `copyResponse` | copy-response button | `aria-label` |
 | `download` / `downloadImage` / `imageContainerHint` | download affordances | `aria-label` / container hint |
-| `modeLabels` / `modeOpenerExtra` | model/effort switcher | visible button + menu text |
+| `modeLabels` / `modeOpenerExtra` | model/effort switcher recognition and openers | visible button + menu text |
+| `modeOptions.<semantic-id>` | selectable model/intelligence mode options | visible picker rows, keyed by stable ids such as `high`, `extraHigh`, and `pro` |
 | `tools.web_search` / `tools.deep_research` / `tools.create_image` | tool menu items | visible menu text |
 | `signedInMarkers` | signed-in detection | sidebar/shell words |
 | `transientAssistant` | streaming placeholder filter | assistant streaming text ("Thinking", etc.) |
@@ -100,6 +106,27 @@ Localized — lives in `src/dom/locale/en.ts` (English) and per-locale files, sa
 The type definitions for `LocaleStrings` (complete) and `LocaleContribution` (partial, for
 non-English files) live in [`src/dom/locale/types.ts`](../src/dom/locale/types.ts).
 
+The first Chat/Work profile fixtures are English evidence. The nested locale
+combiner lets existing locale files omit the new groups without breaking
+compilation, but that is not proof that Work configuration is localized in
+those languages. Add observed labels and a sanitized surface-profile fixture
+before claiming support for a new locale/profile combination.
+
+Create a read-only draft from an already-open authorized ChatGPT tab:
+
+```bash
+npm run capture:surface-profile -- \
+  --id work-basic-de \
+  --locale de-DE
+```
+
+The command defaults region, plan, account, and workspace metadata to
+`not-recorded`, defaults support state to `unverified`, strips conversation
+identifiers, and excludes prompt/response/sidebar text. Review the draft under
+`outputs/surface-profiles/`, add only verified localized labels to the registry,
+then move a sanitized fixture into `contracts/v1/fixtures/` and update the
+manifest/parity matrix.
+
 ## Adding a new language
 
 ### Step 1 — put a real ChatGPT session into the target language
@@ -141,7 +168,13 @@ import type { LocaleContribution } from "./types.js";
 
 export const de = {
   sendButton: ["Nachricht senden"],
-  modeLabels: ["Neueste", "Schnell", "Denken", "Erweitert", "Pro"],
+  modeLabels: ["Sofort", "Mittel", "Hoch", "Extra hoch"],
+  modeOptions: {
+    instant: ["Sofort"],
+    medium: ["Mittel"],
+    high: ["Hoch"],
+    extraHigh: ["Extra hoch"],
+  },
   tools: {
     web_search: ["Websuche"],
   },
@@ -150,11 +183,14 @@ export const de = {
 ```
 
 Leave the canonical English first (it comes from `en.ts`), and leave the API keys
-(`web_search`, the `effort` values) unchanged.
+(`web_search`, `modeOptions.pro`, `modeOptions.high`, and the other semantic ids)
+unchanged.
 
 Newer ChatGPT rollouts may expose `Medium`, `High`, `Extra High`, and `Pro`
 under an `Intelligence` picker. Add localized equivalents only after observing
-those exact labels in the target locale.
+those exact labels in the target locale. Put broad picker/opening labels in
+`modeLabels`, but put selectable labels under `modeOptions.<semantic-id>` so
+short labels such as `Pro` cannot match unrelated rows like `Move to project`.
 
 Then open [`src/dom/locale/index.ts`](../src/dom/locale/index.ts) and register the new
 locale:
@@ -239,9 +275,11 @@ Notes:
 - All consumer import paths (`from "../dom/locale-labels.js"`) are unchanged — the barrel
   `locale-labels.ts` re-exports everything from `locale/index.ts`.
 - `doctor({ check: ["localization"] })` verifies that the registry is populated and
-  canonical English values are present. It does not yet prove full localized selector
-  coverage; treat localized workflow failures as selector-wiring work unless the registry
-  is missing the observed labels.
+  canonical English values are present. It also reports running-state localization coverage
+  separately from the flattened selector list, because `stopControl` and
+  `stoppedAssistant` require a live mid-generation capture. It does not yet prove full
+  localized selector coverage; treat localized workflow failures as selector-wiring work
+  unless the registry is missing the observed labels.
 - The public-export plugin bundles under `plugins/codex-chatgpt-control/runtime/node/` are
   produced by a separate pipeline (`tools/public-export/export-public.mjs`) and are not
   updated by the sync above.

package/references/python-parity.md

@@ -26,9 +26,14 @@ Wire fields stay TypeScript-compatible. Python exposes idiomatic aliases:
 | `totalBytes` | `total_bytes` |
 | `projectUrl` | `project_url` |
 | `displayPath` | `display_path` |
+| `selectorProfile` | `selector_profile` |
+| `newTask` | `new_task` |
+| `includeArtifacts` | `include_artifacts` |
 
 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.
+
 Generated-image behavior stays owned by the TypeScript runtime. Python exposes
 the same backend commands through `chatgpt.artifacts.list_latest(...)`,
 `chatgpt.artifacts.wait(...)`, and `chatgpt.artifacts.download_latest(...)`.
@@ -39,6 +44,13 @@ claimed conversation in a temporary bridge-owned tab and exporting through
 `pageAssets`, Python observes the same command result through the backend
 protocol without any Python-side browser logic.
 
+Chat/Work behavior follows the same authority boundary. Python exposes matching
+sync and async `experience`, `configuration`, and `work` groups, but surface
+detection, selector profiles, configuration state machines, submit-once Work
+semantics, and artifact extraction remain owned by TypeScript. Nested Python
+dictionaries and model instances are recursively converted from snake_case to
+the camelCase wire contract.
+
 Blocker explainability follows the same rule. TypeScript owns blocker creation,
 runner interruption decisions, and existing-tab diagnostics. Python exposes
 `explain_blocker(...)` over the backend blocker dictionary and is checked against
@@ -49,7 +61,7 @@ the shared `blocker-explanation-profiles.json` and
 
 Python does not reinterpret attachment paths. It sends the path string to the Node backend, and the backend validates the path against its own host operating system. Attachment paths must be absolute on the backend host. On macOS/Linux/WSL backends, use POSIX paths such as `/example/user/file.pdf` or `/mnt/c/example/user/file.pdf`. On Windows backends, use fully qualified paths such as `C:\Users\you\file.pdf` or UNC paths such as `\\server\share\file.pdf`. Drive-relative paths, root-relative paths, and Windows-looking paths sent to a POSIX backend are rejected before filesystem access.
 
-Python exposes the backend-visible `files.preflight` command as `chatgpt.files.preflight(...)`. It returns the same `CommandResult` as TypeScript and can be decoded with `FilePreflightData` when callers want typed metadata. The command validates paths, readability, file-vs-directory status, size limits, duplicate basenames, duplicate resolved paths, zero-byte files, and extension-based MIME/category guesses without opening ChatGPT or reading file contents for MIME detection.
+Python exposes the backend-visible `files.preflight` command as `chatgpt.files.preflight(...)`. It returns the same `CommandResult` as TypeScript and can be decoded with `FilePreflightData` when callers want typed metadata. The command validates paths, readability, file-vs-directory status, size limits, duplicate basenames, duplicate resolved paths, zero-byte files, and extension-based MIME/category guesses without opening ChatGPT or reading file contents for MIME detection. Zero-byte files are blocked before browser interaction. Optional `include_hashes=True` / wire `includeHashes: true` adds SHA-256 metadata to `FilePreflightFile.sha256` for local diagnostics; file contents are never returned.
 
 ## Project Sources
 
@@ -121,7 +133,7 @@ Report results may include `metaPath` plus `integrity` metadata. Python exposes
 
 ## Streaming
 
-`stream-*.ndjson` fixtures are milestone streams. They are not token streams. The final `completed` event contains a normal `ChatGPTRunResult` wire object, including blockers when the run cannot proceed.
+`stream-*.ndjson` fixtures are milestone streams. They are not token streams. The final `completed` event contains a normal `ChatGPTRunResult` wire object, including blockers when the run cannot proceed. Running partial assistant text uses `message.in_progress` / `message_in_progress`; completion-confirmed assistant output uses `message.completed` / `message_completed`.
 
 ```python
 from codex_chatgpt_control import ChatGPTStreamEvent
@@ -161,7 +173,7 @@ Python is a native SDK facade over the local backend protocol. The initial brows
 
 - `dist/codex-chatgpt-control-backend.mjs` is the stdio backend bundle.
 - `BackendClient` and `StdioBackendTransport` keep Python backend calls long-lived.
-- `NodeSidecarTransport.run(...)` remains as a compatibility wrapper over backend `runner.run`.
+- `NodeSidecarTransport.run(...)` remains as a compatibility wrapper over backend `runner.run`. By default each call spawns and tears down its own backend subprocess; use it as a context manager (or call `open()`/`close()`) to reuse one persistent backend process across calls in multi-command workflows. Transport-level failures close the persistent session; protocol-level errors keep it open.
 - 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.
 
@@ -199,7 +211,7 @@ python scripts/live_smoke.py --mode browser-bridge
 When the live backend is hosted inside the Codex Chrome plugin runtime, do not test bridge availability from a normal shell or an unbootstrapped Node REPL. First initialize the Chrome runtime:
 
 ```js
-const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/26.602.40724/scripts/browser-client.mjs");
+const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/latest/scripts/browser-client.mjs");
 await setupBrowserRuntime({ globals: globalThis });
 globalThis.browser = await agent.browsers.get("extension");
 ```

package/references/responses-adapter.md

@@ -6,8 +6,12 @@ Accepted fields:
 
 - `input`
 - `thread`
+- `existingTab`
+- `preferExistingTab`
+- `experience`
+- `configuration`
 - `attachments`
-- `mode`
+- `mode` (legacy compatibility)
 - `tools`
 - `text.format`
 - `stream: false`
@@ -20,9 +24,16 @@ Rejected API-only fields return `status: "unsupported"` before any prompt is sub
 const response = await chatgpt.responses.create({
   input: "Summarize the latest plan.",
   thread: { type: "conversationId", conversationId: "abc-123" },
+  experience: "chat",
+  configuration: { intelligence: "High" },
   text: { format: "markdown" },
   stream: false
 });
 ```
 
+`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
+`mode`; new callers should prefer the surface-aware fields.
+
 Use `chatgpt.runner.run()` for lower-level browser-control workflows, multi-step command planning, attachments, downloads, reports, and explicit interruption handling.

package/references/troubleshooting.md

@@ -33,7 +33,7 @@ Use `chatgpt.explainBlocker(result)` or Python `explain_blocker(result)` when re
 Do not conclude that Chrome or the extension is broken from a plain shell result, or from checking `globalThis.agent` before the Chrome plugin runtime is initialized. For a true Codex Chrome-plugin live run, bootstrap the runtime first:
 
 ```js
-const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/26.602.40724/scripts/browser-client.mjs");
+const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/latest/scripts/browser-client.mjs");
 await setupBrowserRuntime({ globals: globalThis });
 globalThis.browser = await agent.browsers.get("extension");
 ```
@@ -69,6 +69,17 @@ The ChatGPT UI changed or the page loaded an unexpected surface. Return visible
 
 Runner results surface this as `interruptions[0].type === "selector_drift"` with `blocker.candidates` when visible candidates were available. Do not retry automatically; ask the user or update selectors.
 
+For Chat/Work drift, capture only scoped capability evidence: composer label,
+main controls, configuration rows/options, locale, URL shape, selector profile,
+and observation date. Do not retain sidebar thread titles or conversation
+content. An unknown profile, missing axis, or unverified postcondition is a
+normal blocker during staged account/region/workspace rollouts.
+
+If `work.start` returns `work_new_task_control_not_found`, a task is already
+loaded and the SDK refused to append. Pass `newTask: false` only when the user
+intends to continue that exact task. If a Work submission returns partial or
+timeout, use `work.status`, `work.wait`, or `work.readLatest`; do not resubmit.
+
 ## Existing Tab Not Found Or Ambiguous
 
 When `existingTab` targeting cannot select one already-open tab, inspect `blocker.diagnostics.existingTab` or the rendered blocker explanation. Diagnostics are metadata-only: requested target, whether user-open tabs were available, candidate tab IDs, URLs, titles, conversation IDs, omitted candidate count, and mismatch reason. They must not include page text or chat content.
@@ -90,9 +101,24 @@ Agent-facing remediation text should name both settings:
 
 Attachment paths are validated against the backend host's operating system. If a Windows-looking path is rejected on macOS/Linux, do not retry with the same string. Convert it to the backend host's real path, for example `/mnt/c/example/user/file.pdf` for a WSL/Linux backend. Drive-relative paths like `C:Users\you\file.pdf`, root-relative paths like `\tmp\file.pdf`, and empty or relative paths are always rejected.
 
+## Empty Or Stripped Attachments
+
+Zero-byte files are blocked by `files.preflight` before browser upload because
+ChatGPT rejects empty attachments with a generic help-center error. If a user
+reports that manual upload works but automated upload fails, compare local and
+browser-side metadata instead of guessing:
+
+1. Run `files.preflight({ paths, includeHashes: true })` and inspect `bytes`
+   plus `sha256` for the backend-visible file.
+2. Run `files.attach({ paths, includeDiagnostics: true, includeHashes: true })`
+   and inspect `data.diagnostics.browserInput.files[].size` when available.
+3. If preflight `bytes` is zero, investigate the source path, generation race,
+   cloud placeholder, or host/container path mapping. If preflight bytes are
+   nonzero but browser-side size is zero, investigate the Chrome handoff.
+
 ## Clipboard Unavailable
 
-`response.copy` falls back to DOM text extraction when the macOS system clipboard does not change.
+`response.copy` falls back to DOM text extraction when the system clipboard does not change. Clipboard reads use `pbpaste` on macOS, PowerShell `Get-Clipboard` on Windows, and `xclip`/`xsel`/`wl-paste` on Linux; hosts without any of these tools always use the DOM fallback.
 
 ## Flattened Or Unreadable Response Capture
 
@@ -100,16 +126,33 @@ Use `readLatest({ format: "markdown" })`, `copyLatest()`, or the default SDK `re
 
 ## Long Responses Return `partial`
 
-Long Pro, Thinking, Deep Research, or file-backed answers can take longer than the default wait window. Treat `status: "partial"` and `data.complete: false` as an incomplete capture even when `output_text` is non-empty. Re-run `messages.wait(...)` on the same thread with a larger timeout, then call `readLatest(...)` or `copyLatest(...)` only after completion is confirmed.
+Long Pro, Thinking, Deep Research, or file-backed answers can take longer than the default wait window. Treat `status: "partial"` and `data.complete: false` as an incomplete capture even when `output_text` is non-empty. Check `data.completionState` and `data.generationActive`; `completionState: "generating"` or `generationActive: true` means ChatGPT is still running and the prompt must not be resubmitted. For repeated polling, prefer `messages.status({ maxPreviewChars })` for a cheap snapshot, or `messages.wait({ responseContent: "metadata", ... })` so Codex receives compact status metadata instead of the same growing partial answer body. Re-run `messages.wait(...)` on the same thread (with a larger timeout if needed) until completion is confirmed, then call `readLatest(...)` or `copyLatest(...)` once.
 
 Recommended long-answer wait:
 
 ```ts
-wait: { timeoutMs: 600000, stableMs: 8000, pollMs: 1000 }
+await chatgpt.messages.wait({
+  timeoutMs: 45_000,
+  stableMs: 2_000,
+  pollMs: 1_000,
+  mode: "deep_research",
+  responseContent: "metadata"
+});
+
+const final = await chatgpt.messages.readLatest({ format: "markdown" });
 ```
 
 Active generation may appear as a visible or accessible-name control such as `Stop answering`, `Stop generating`, or `Stop streaming`. Stopped generation may appear as `Stopped thinking`. Treat all of those as incomplete states.
 
+When the outer host tool-call ceiling is short, poll in bounded chunks instead of issuing a single very long wait:
+
+```ts
+const status = await chatgpt.messages.status({ maxPreviewChars: 400 });
+if (status.data?.completionState === "generating" || status.data?.generationActive) {
+  await chatgpt.messages.wait({ timeoutMs: 30000, stableMs: 8000, pollMs: 1000 });
+}
+```
+
 `maxChars` limits captured text returned by the SDK. It does not control ChatGPT generation. When set and clipping occurs, inspect result warnings and `data.captureLimit`, then rerun without `maxChars` for full capture.
 
 ## Response Branch Ambiguity
@@ -144,6 +187,6 @@ Doctor also supports opt-in scenario checks:
 
 - `existing_tab`: claims only the requested already-open tab target by default and reports `existing_tab_not_found` / `existing_tab_ambiguous` diagnostics without opening a replacement tab unless `existingTab.ifMissing` explicitly allows that.
 - `artifacts`: verifies current-page artifact selector/download/asset support without requesting generation.
-- `file_preflight`: validates supplied local file paths without opening ChatGPT or attempting upload. It reports path count, total bytes, duplicate/zero-byte warnings, and extension-based MIME/category metadata; fatal local file problems map to the same structured blockers as `files.preflight`.
-- `localization`: checks locale-label registry readiness and English canonical labels without changing the ChatGPT account language; it is not yet proof of full localized selector coverage.
+- `file_preflight`: validates supplied local file paths without opening ChatGPT or attempting upload. It reports path count, total bytes, duplicate warnings, zero-byte blockers, and extension-based MIME/category metadata; fatal local file problems map to the same structured blockers as `files.preflight`.
+- `localization`: checks locale-label registry readiness and English canonical labels without changing the ChatGPT account language. It reports running-state label coverage (`stopControl` and `stoppedAssistant`) separately so English-only, partial, and complete live-capture coverage are visible. It is not yet proof of full localized selector coverage.
 - `reports`: checks redacted-report policy and existing destination writability when possible without writing a report.