stealth-cli: Instructions file for Codex

stealth-cli — Agent Development Guide

Core reminder

Reason from first principles, end to end. When the evidence does not support a conclusion, say "no basis found" instead of presenting an inference as a finding. Read the current file before editing it; keep changes scoped to the request; prefer an existing repository pattern over a new abstraction.

Product direction

Stealth Browser is a Camoufox cloud browser and hosted-agent platform, matching Browser Use's product capabilities: hand a task to the platform's agent, or create and control a cloud browser through the API and SDK. Browser execution is stealth-cli / SDK — the component this repository ships today, also usable on its own as a CLI, SDK, daemon, and MCP server over one engine, Camoufox. The Agent Core is Penguin Harness (selected, not integrated). Freepost, Travel Agent, and other applications integrate as external consumers of the generic API and SDK. Whether the platform's modules live in this repository or another is not decided; the browser component stays independent either way.

The goal, the interactions the product is judged on, the current implementation status, the requirements, and the scope it declines are the root of the documentation: SPEC.md. Read it before proposing a feature; it settles whether the feature belongs, and at which level.

Hard rules

1. Camoufox through playwright-core's Firefox driver is the only engine. Never chromium.launch(), never the playwright bundle, never a second engine behind a flag. The product's one claim rests on the engine (decision).
2. Do not guess the camoufox-js API. It is a small library with little public documentation. Read src/utils/browser-factory.js and src/browser.js for actual usage; the launch call is reproduced in docs/architecture.md.
3. Nothing the browser component does leaves a footprint in the page. No marker attributes, no globals, no injected panels. Perception runs in Playwright's utility world; if a feature needs to draw or remember something, it does so outside the page or not at all. This is a stated boundary, not a claim that the operation as a whole is undetectable: clicks are synthetic and isTrusted is false, and documents say so where it applies.
4. Named state is single-writer and fails closed. Leases live in module-private WeakMaps and never on a handle; writes are validated with the branded ownsStateLock; stale locks and cross-process .claim / .tmp / .rollback artifacts are reported with their exact path and never auto-removed (decision).
5. Every surface tells the same truth. A daemon-mode operation has the same result shape, error code, and state effect as its direct-mode twin, or the difference is documented at the command. Errors cross a transport only through serializeErrorForTransport(); raw causes, credential-bearing URLs, and cleanup internals stay non-enumerable.
6. The browser component's dependencies are exactly camoufox-js, playwright-core, commander, chalk, ora, and vitest for development. Not playwright, not yargs/meow/oclif, not a second image or DOM library. Adding one is a decision written under docs/decisions/ first. Platform modules, when they exist, carry their own dependency rule.
7. ESM, plain JavaScript with JSDoc, Commander. Never require(), no TypeScript. New commands go in src/commands/<name>.js exporting register<Name>(program); new extractors in src/extractors/<engine>.js exporting name, canHandle(url), extractResults(page, max).
8. Every change leaves the living documents true. A change that alters a boundary, a contract, or a default updates docs/architecture.md and the affected guideline in the same commit; one that settles a trade-off worth remembering adds a note under docs/decisions/. A document left describing the old behaviour is part of the defect, not a follow-up.
9. English is the working language of living documents — code, comments, commit messages, SPEC.md, this file, docs/architecture.md, docs/guidelines/, docs/decisions/, docs/postmortem/, tasks/. Dated records under docs/research/ and docs/design/ may be in the author's language; see the writing rules.