# Chrome Extension Deep Research Contract

This contract defines how OfOne hands Deep Research work to a Chrome extension/plugin without taking over the user's active desktop session.

## Purpose

The extension surface is the primary launch and observation mechanism for recursive reviews and frontier benchmark runs. It should create clean isolated ChatGPT tabs, submit one packet or arm per tab, observe launch proof, and leave a durable result for local harvest. Desktop takeover surfaces are not valid launch proof.

## Queue

The current machine-readable queue is:

- `research/deep-research-launch-queue.json`
- Extension payloads: `research/deep-research-extension-payloads.json`
- Extension report intake: `research/deep-research-extension-report.json`
- Manual recovery gate: `research/deep-research-manual-recovery.json`
- Schema: `schemas/ofone.deep-research-launch.schema.json`
- Payload schema: `schemas/ofone.deep-research-extension-payloads.schema.json`
- Report schema: `schemas/ofone.deep-research-extension-report.schema.json`
- Manual recovery schema: `schemas/ofone.deep-research-manual-recovery.schema.json`
- Checker: `npm run deep-research:check`
- Payload freshness checker: `npm run deep-research:payloads`
- Report intake checker: `npm run deep-research:report`
- Manual recovery checker: `npm run deep-research:manual-recovery`
- Manual recovery source scanner: `npm run deep-research:manual-recovery:scan`

Each queue item identifies the benchmark slot, packet path, prompt anchor, expected output path, expected review path, required launch proof, and disallowed surfaces. A queue item may be ready for extension launch, blocked, active, harvested, reviewed, or rejected, but it is not complete until local harvest, review, verification, publication, and Pages parity all exist.

The extension payload file expands each queue item into one isolated tab lane with the exact prompt text extracted from the packet, packet and prompt SHA-256 hashes, expected harvest paths, isolation constraints, and launch-block status. Regenerate it after queue edits with `npm run deep-research:payloads:write`, then verify it with `npm run deep-research:payloads` and `npm run deep-research:check`.

The extension report file is the only accepted local intake for launch and harvest observations from the Chrome extension/plugin. It records whether the extension surface is unavailable, launch-ready, launched, active, completed, harvested, or rejected; binds that report to the exact payload file hash; records the current Chrome-extension availability diagnostic; and requires explicit launch or harvest proof before a blocked queue item can advance.

The manual recovery gate is only for a narrow completed-visible state: Chrome extension control is callable, launch proof exists, the completed report is visible, allowed extension probes have failed to expose raw Markdown, and no disallowed browser/desktop/OCR fallback may be used. It is hash-bound to the current queue, payload, and report files. It may validate a native ChatGPT Markdown export from the recorded conversation, and its source scanner can check the expected Downloads glob for a marker-valid native export, but it cannot by itself promote a slot to harvested, reviewed, complete, or aggregate-eligible.

## Extension Duties

For each queue item, the extension should:

1. Open a clean isolated ChatGPT tab or conversation.
2. Select the current Pro/frontier-capable model and highest available reasoning mode.
3. Enable Deep Research when available.
4. Submit only the `prompt_text` from the matching item in `research/deep-research-extension-payloads.json`.
5. Capture launch proof: model label, reasoning label, Deep Research state, conversation URL, generated plan title, Start/countdown action, active research state, and stop-control evidence.
6. Preserve the queue item as active while stop-control remains visible.
7. Harvest only after a completed report is visible.
8. Write or update `research/deep-research-extension-report.json` with the matching `item_id`, `tab_lane`, extension namespace, isolated-tab proof, launch proof, completed-report/raw-output hash proof, and allowed Chrome-extension harvest probes as applicable.

The extension may run multiple tabs concurrently only when each arm is isolated and no tab can inspect another arm's output before raw harvest.

## Blocker Rule

If callable Chrome extension/plugin control is unavailable, troubleshoot extension availability before any other work. Do not continue benchmark, harvest, launch, or repo-promotion work until extension control is restored or the blocker is proven.

The current Codex Desktop callable path may not appear as a standalone `mcp__chrome__*` namespace. Treat `node_repl` plus `globalThis.browser` as the canonical Chrome extension probe when tool discovery exposes it:

1. Record the tool discovery query and whether it exposed `node_repl`.
2. Read `nodeRepl.requestMeta["x-codex-browser-use-available-backends"]` and require `chrome` when claiming availability.
3. Record whether `globalThis.browser` exists, plus `browser.browserId`, `browser.capabilities`, and available `browser.tabs` operations when present.
4. Attempt `browser.tabs.list()` and record either the observed tab count or the exact thrown error.
5. If no standalone Chrome namespace is exposed but `node_repl` can see the `chrome` backend and list tabs, the Chrome extension is available; continue only through that extension surface.

Required diagnostics are: current tool discovery result, `nodeRepl.requestMeta` backend list when `node_repl` is callable, `globalThis.browser` presence or absence, `browser.tabs.list()`/tab-list attempt or error, and the exact namespace or backend failure. Do not treat a missing standalone Chrome namespace or missing `browser.tabs.query()` helper as extension failure when the current Chrome bridge exposes `browser.tabs.list()`. The queue and report stay blocked until those diagnostics either restore callable extension control or prove a real extension blocker. If extension control is available but raw Markdown harvest is blocked, the report must enumerate the allowed Chrome-extension probes already attempted before the item can remain `completed_report_visible`; if the next action becomes operator export, the manual recovery gate must be present and passing. Browser, Computer Use, coordinate clicking, AppleScript/JXA, and generic desktop automation are not fallbacks for launch or harvest because they can hijack the user's active workspace and blur launch evidence. OCR and screenshot reconstruction are also barred because they reconstruct non-verbatim report text.

Current bridge method-shape notes are part of the troubleshooting contract. `browser.tabs.list()` can return only `id`, `title`, and `url`; call `browser.tabs.get(tabId)` before expecting `playwright`, `dom_cua`, `content`, `clipboard`, or `dev` helpers. `browser.tabs.content(...)` expects `{ urls, contentType }` with camelCase `contentType`, not `{ urls, content_type }`; even correctly shaped calls may fail because the Chrome backend rejects the `tabs_content` command. `tab.content.export()` takes no format argument and may fail with unsupported `tab_content_export`. `tab.content.exportGsuite(format)` takes a string format and is valid only for Google Workspace documents. These failures are valid Chrome-extension harvest probes, not evidence that a desktop-control fallback is allowed.

## No-Start Handoff Rule

If the Chrome extension is callable but ChatGPT Deep Research does not produce a generated plan, Start/countdown action, active research state, or stop-control evidence after submission, keep the item `prepared_not_launched` / `launch_ready`. This is a Deep Research handoff failure, not proof that the Chrome extension is unavailable.

Record no-start evidence through the Chrome extension only: conversation URL, visible Deep Research/Pro controls, whether only the submitted prompt is visible, whether the internal Deep Research iframe is mounted but empty, and relevant `tab.dev.logs` entries such as `Ignoring message from unknown source MessageEvent`. A minimal Deep Research smoke-test prompt may be used to isolate whether the failure is prompt-specific, but it is not benchmark evidence and must not advance any benchmark slot.

After two same-shape no-starts or one benchmark no-start plus one minimal smoke-test no-start, do not keep retrying the same launch shape. The next valid action is either a changed extension-only launch condition with fresh proof or a blocked state that preserves the prepared packet. Browser, Computer Use, coordinate clicking, AppleScript/JXA, generic desktop automation, OCR, and screenshot reconstruction remain disallowed.

## Current State

The formal proof-search frontier repeat-1 direct-answer item is currently `reviewed` in `research/deep-research-launch-queue.json` and `harvested` in `research/deep-research-extension-report.json`. Chrome extension launch and harvest proof is recorded for https://chatgpt.com/c/6a0f0a85-c75c-83e8-b0d0-4c15a041cb7b with visible metadata `Research completed in 10m`, `8 citations`, `101 searches`, report title `Benchmark Raw Output`, and run metadata `Status: completed`. The raw output and local review are saved; publication parity is confirmed only after commit, push, and `npm run pages:check`.

The formal proof-search frontier repeat-1 light-structured item has a completed report visible at https://chatgpt.com/c/6a0f1fe5-3494-83e8-9f92-1a2b732c4958 with visible metadata `Research completed in 9m`, `6 citations`, `120 searches`, report title `Benchmark Raw Output`, and run metadata `Status: completed`. It remains `completed_report_visible`, not harvested or aggregate-eligible, because raw Markdown export is blocked by the cross-origin Deep Research iframe and no disallowed fallback may be used. The current report records Chrome availability through `mcp__node_repl__js` plus allowed extension probes for full browser-client tab control, DOM, iframe, page-storage, sandbox-tab, response-menu, conversation-options, Share modal, View sources, View files in chat, content-export, GSuite export, browser.tabs.content schema and backend limits, dev-log, backend-request, page-eval, and Copy response paths. The manual recovery gate at `research/deep-research-manual-recovery.json` is currently `awaiting_operator_export`; its checker verifies that no raw output or review file exists and that future promotion still requires native Markdown export, local review, state update, commit, push, and Pages parity.