daedalus: Instructions file for Codex

Daedalus

Daedalus is a Chrome-extension-based remote control system for matching web pages — eval bridge, screenshots, CDP, cookies, network capture, hotfixes, declarativeNetRequest blocking.

Read README.md first — it is the reference for the command surface, install, and usage.

<investigate_before_answering> Never claim anything about this codebase's API, field names, or endpoints without opening the file. Field names (id, code, type, tab, token) are exact — verify against server.py or this file before writing bridge commands. </investigate_before_answering>

Extension (extension/)

• Token: auto-generated on first install, stored in chrome.storage.local.
• content.js (ISOLATED world): message relay between page and background. On load it asks the background to replay hotfixes (replayHotfixes); the background picks the eligible fixes from the extension-wide daedalus-hotfixes record and runs each through the eval routing below, so a page whose CSP forbids dynamic compilation is reached over CDP. Hotfix source is page-observable by design — it executes in the page — but is no longer posted into it.
• page.js (MAIN world): the last-resort page relay's new Function / eval and Blob-script paths, reached only after the background's source-free probe and CDP fallback cannot run submitted source. A hostile same-tab page can choose the relay's one-shot JavaScript value. Exposes the documented window.GM Tampermonkey-style subset (xmlhttpRequest, openInTab, storage methods, addStyle, segmentJob, etc.); cookie operations remain typed operator commands, with no page-facing GM.cookie surface.
• background.js (service worker): SSE stream, command dispatch, fetch relay, screenshots, CDP, cookies, tabs, downloads, notifications, segment mint. The mint (worker/segment_mint.js) decides on the content script's sender.origin alone, compared verbatim against the daedalus-segment-origins allowlist, and fails closed: an origin Chrome does not report, one not on the list, or an empty list is refused before any bridge request.
  • Eval routing: a constant MAIN-world Function probe carrying no submitted source runs first. true selects banner-free page-main injection; any other result selects the CDP CSP fallback, whose successful attachment shows Chrome's debugger banner. Once either channel dispatches submitted source, every outcome is terminal; only attach or shape failure before source runs reaches the page relay.
  • CDP Runtime.evaluate uses REPL mode, reads direct values by reference, bounds promise settlement at 10 seconds, and releases result and exception handles even when a kept session or capture holds the attachment.
  • Trust: a page you do not control can choose the returned value on any channel. On page-main its own eval and Function bindings can also read the submitted source; on cdp it can choose the value whenever that source uses page-controlled state or page promise machinery. The world field (page-main, cdp, page:<hostname>) records the channel, not whether to trust the value; the background adds the mandatory page: prefix, so relay hostnames cannot collide with the other two — a descriptive property, not a trust boundary.
  • The relay admits 1,000 live entries; a new one at capacity gets a terminal error without eviction, and a live entry expires with one terminal error after 300,000 ms.
  • store-hotfix's site scope: match is a Chrome match pattern, and the command takes three forms — absent, which includes an explicit null and keeps the scope the fix already has; a pattern that parses, which sets it; and clearScope: true, which removes it and leaves the code and permanent alone. clearScope is a boolean beside match and never a value in it, so nothing placed in the scope's own slot is ever a removal: a value there that is neither absent nor a pattern is refused, as is a clearScope that is present and not a boolean — null among them — or one that travels beside a stated pattern, and each refusal leaves the stored record untouched.
• Tab tracking: chrome.tabs API, registered on create/update with a 30s chrome.alarms heartbeat.