@deeeed/metamask-harness 0.17.5 → 0.19.0

package/docs/architecture.md

@@ -1,398 +0,0 @@
-# MetaMask Recipe Runner Architecture
-
-**Control flows DOWN only — a DAG, never a loop.**
-
-```
-  bin/mm-harness          ← entry (thin bootstrap)
-        │
-        ▼
-  ┌───────────────────────────────────────────────┐
-  │  src/   THE BRAIN — all TypeScript             │
-  │  CLI · decisions · state machines · run        │
-  │  engine · healing/errors · evidence            │
-  └───────────────────────────────────────────────┘
-        │ spawns                    │ reads
-        ▼                           ▼
-  adapters/<platform>/        library/
-  DEVICE LEAVES (shell)       VOCABULARY (data)
-  one op · args in ·          recipes · actions ·
-  result out · exit           flows — pure JSON/mjs
-  (yarn-setup, start-metro,
-   open-device, xcrun, adb,
-   webpack, chrome)
-```
-
-| dir | is | rule |
-|---|---|---|
-| `bin/` | entry | one thin bootstrap |
-| `src/` | the brain | ALL TypeScript, ALL decisions/sequencing |
-| `adapters/<platform>/` | device leaves | one op each · never orchestrates · **never calls `mm-harness`** |
-| `library/` | vocabulary | pure recipe/action/flow data |
-
-**The one rule everything follows:** nothing under `adapters/` or `library/` ever calls `mm-harness`. TS orchestrates and spawns leaves; leaves do one device op and exit; vocabulary is data. (External callers — farm hooks, skills, overlay delegate — invoking `mm-harness` at the top level is fine; the ban is on the harness's OWN scripts calling back in.)
-
-**Why:** every past mess (half-wired porcelain, commands referenced-but-unbuilt, stub tests faking the thing under test) came from control looping back up. Down-only makes that class of bug unrepresentable — and means less code.
-
----
-
-This repo is the MetaMask-specific adapter layer for Recipe Protocol v1. It is
-not the protocol engine, not a skills repo, not a slot farm, and not product
-code. Its job is to publish reviewable MetaMask capabilities and run them
-against a local Mobile or Extension checkout without committing harness runtime
-into that checkout.
-
-The core model is standalone: install or check out this runner, point it at a
-MetaMask checkout, and run `mm-harness`. Farm/slot orchestration is only a
-way to scale the same loop across many checkouts, machines, ports, and agents;
-it is not required to understand or use the runner.
-
-## TL;DR
-
-The four questions that come up whenever this repo needs explaining.
-
-**Responsibility split.** This runner owns the logic; skills and farms are a
-minimum overlay that call its CLI. Rule of thumb: if a skill's shell script is
-doing more than parsing flags and calling `mm-harness`, that logic
-belongs in this runner instead. Concrete example in flight: the
-`recipe-harness` skill currently locates and execs runner internals in
-hundreds of lines of bash (resolve runner source, dispatch to
-`adapters/<platform>/{inject,cleanup}.{sh,mjs}` — `.sh` for Mobile/Core,
-`.mjs` for Extension); the fix is a
-[`mm-harness <install|verify|cleanup|live>`](CLI-SPEC.md) command here, so the
-skill thins to a few lines that call it. Same pattern applies to every other
-`recipe-*` skill over time.
-
-**Language policy — bash vs ts vs mjs vs cjs.** Current mix: 65 `.sh`, 62
-`.mjs`, 17 `.ts`, 9 `.cjs` (excluding `node_modules`).
-
-| Extension | Where | Use for | Why |
-|---|---|---|---|
-| `.ts` | `src/**` | CLI parsing, manifests, adapter binding, runtime decisions — typed/testable/shared logic | Compiled and typed; the maintainable core that everything else should grow into |
-| `.mjs` | `library/actions/**`, `adapters/**`, `scripts/**` | Standalone action adapters and injected runtime helpers | Run-anywhere with zero build step, whether invoked from a published package or a raw checkout |
-| `.cjs` | scattered, quarantined | Compatibility islands: portable `require()` from shell, bridge code for older runtime contexts | Only when the runtime context makes ESM brittle — not a default choice |
-| `.sh` | `bin/`, `adapters/{mobile,extension,core}/`, `adapters/shared/` | Thin OS/device glue at the edge: `simctl`, `adb`, Chrome process flags, git-exclude, filesystem setup | Must run before/without Node business logic; never recipe graph execution or MetaMask domain semantics |
-
-The mix is bash-heavy today because sandbox setup crosses OS/device boundaries
-(see "Why there are shell scripts" below) — that is current reality, not the
-target ratio. The direction is less bash over time: when a shell helper starts
-accumulating domain behavior, move it into `.ts` or a focused `.mjs` adapter
-(see [Runtime File Conventions](runtime-file-conventions.md) for the full
-rule).
-
-**Packaging — one package, not several.** This stays one npm package while the
-runtime API is still moving; see [Package Boundaries](package-boundaries.md)
-for the full rationale. Splitting now would force every wrapper (skills,
-farmslot) to pin two coordinated versions before the boundary between "recipe
-execution" and "runtime lifecycle" has stabilized — coordination cost for no
-current benefit. Split when the runtime CLI contract is stable, all wrappers
-call it exclusively (no copied adapter scripts), and the two areas have gone
-several releases without a change that touches both.
-
-## Layer map (front door → engine → schema)
-
-The whole stack is three layers with a strictly one-way dependency. `mm-harness`
-is the MetaMask-facing **front door**; underneath it the runner is a thin
-**adapter layer** over a fat generic **engine** (`@farmslot/recipe-harness`) and
-**schema** (`@farmslot/protocol`). The runner never re-implements engine logic —
-it imports it.
-
-```text
-mm-harness (the one bin — no per-platform binaries)    ← front door: one verb vocabulary
-        │  launch · logs · debug · fixtures (daily loop) · run/flows/doctor/actions/manifest (prove)
-        │  install/verify/cleanup/live (runtime overlay lifecycle)
-        ▼
-metamask-recipe-runner (MetaMask ADAPTER layer)         ← this repo
-        │  MetaMask action manifests, metamask.* live adapters, Mobile/Extension
-        │  runtime overlay install, runtime health/decision probes
-        ▼
-@farmslot/recipe-harness  (GENERIC engine)              ← npm dependency
-        │  recipe graph execution, official ui.* transports, RecordingTarget
-        │  evidence framework, runtime modules, generic run/flows/validate CLI
-        ▼
-@farmslot/protocol        (GENERIC schema)              ← npm dependency
-        │  Recipe v1 schema, action-manifest document, artifact contract
-        ▼
-MetaMask app under test
-        │  local debug runtime only; product source should not own runner logic
-        ▼
-summary.json · trace.json · artifact-manifest.json · screenshots/logs
-```
-
-**Dependency direction is one-way and provable.** The runner *depends on*
-`@farmslot/recipe-harness` + `@farmslot/protocol` (see `package.json`), and
-`src/**` *imports* the generic contracts rather than forking them:
-
-- `src/cli.ts` imports `RecipeRunResult` from `@farmslot/recipe-harness`
-  and delegates library `flows` to the harness CLI (`importRecipeHarnessCli`).
-- `src/runner.ts` wires `metamask.*` adapters INTO the farmslot
-  `RecipeRunner`; it does not implement graph execution.
-- `src/manifest.ts` loads *MetaMask* manifests typed by the *farmslot*
-  protocol document type.
-- `src/recording-target.ts` is a MetaMask provider over the farmslot
-  `RecordingTarget` contract.
-
-**The invariant both repos assert:** farmslot stays MetaMask-free; the runner
-never re-implements engine logic, only binds to it. Decision lens for placing any
-new capability: *would a non-MetaMask project reuse this unchanged?* → yes =
-generic (farmslot); encodes MetaMask app knowledge = runner.
-
-> Note on naming: "harness" refers to the tool (`mm-harness`) and the generic
-> engine package (`@farmslot/recipe-harness`). The per-checkout files the tool
-> installs into a target are the **runtime overlay** (`install`/`verify`/
-> `cleanup`/`live`), never "the harness" — see [CLI-SPEC.md](CLI-SPEC.md).
-
-## One-minute model
-
-```text
-human CLI / optional skill wrapper
-        │ resolve + invoke
-        ▼
-metamask-recipe-runner
-        │ MetaMask action manifests, live adapters, runtime overlay install, runtime probes
-        ▼
-Recipe harness package
-        │ generic graph execution, official ui.* transports, traces, artifacts
-        ▼
-Recipe protocol package
-        │ Recipe v1 schema, manifest contract, artifact contract
-        ▼
-MetaMask app under test
-        │ local debug runtime only; product source should not own runner logic
-        ▼
-summary.json · trace.json · artifact-manifest.json · screenshots/logs
-```
-
-Dependency direction is one-way. Wrappers call the runner; the runner calls the
-shared harness/protocol packages; product apps are only driven at runtime.
-
-## Package shape
-
-This repo remains one npm package for now, but it has two internal areas: recipe execution and runtime lifecycle. See [Package Boundaries](package-boundaries.md) for the stability policy and why we are not splitting packages yet.
-
-## The two subsystems
-
-This repo has two intentionally different kinds of code. Keeping them separate
-is the main way to understand the repository.
-
-| Subsystem | Question it answers | Primary files | Should contain | Should not contain |
-|---|---|---|---|---|
-| Recipe capability/execution | “What can a MetaMask recipe do, and how does a node execute?” | `library/manifests/`, `library/recipes/`, `src/runner.ts`, `src/adapters.ts`, `src/live-adapter-contract.ts`, `library/actions/` | action manifests, domain actions, UI transport binding, adapter outputs, proof semantics | Metro startup, Chrome process flags, simulator boot, git-exclude/rsync cleanup |
-| Runtime lifecycle / sandbox helpers | “How do I give an agent an isolated app session that is ready to inspect or run recipes?” | `adapters/porcelain/`, `adapters/{mobile,extension,core}/`, `adapters/shared/` | install/sync harness, start/reuse Metro or Chrome, prewarm bundles, open Extension full-screen or popup-style, prepare dedicated profiles/fixtures, check build/runtime health, cleanup local files | new recipe schema, graph traversal, MetaMask business semantics, task-specific proof logic |
-
-When reviewing a change, first decide which subsystem it touches. Recipe changes
-should be validated against manifests and action artifacts. Runtime lifecycle changes should be validated by install/launch/live/verify
-behavior on a real checkout. Some commands cross the boundary, but they should
-do so by delegating: sandbox helpers get the runtime ready, then
-`mm-harness run` executes the recipe.
-
-## Ownership boundaries
-
-| Layer | Owns | Must not own |
-|---|---|---|
-| Human CLI / optional wrapper | Target selection, runner invocation, evidence handoff | Copied adapter scripts, recipe graph execution, product runtime logic |
-| This runner | MetaMask action manifests, `metamask.*` adapters, Mobile/Extension harness install, runtime health/decision commands | Shared Recipe v1 schema, generic `ui.*` semantics, task-specific acceptance criteria |
-| `Recipe harness package` | Recipe graph execution, standard core/ui adapters, trace/summary/artifact writing | MetaMask wallet/Perps behavior |
-| `Recipe protocol package` | Recipe/manifest/artifact schemas | Runtime control or product-specific actions |
-| Product checkout | App code and debug hooks exposed by the app | Harness scripts, runner copy, skills, private workflow logic |
-
-Rule of thumb: if code describes **what MetaMask can do**, it belongs here. If it
-describes **how Recipe v1 works**, it belongs in the shared protocol/runtime packages. If it
-describes **how an agent should work**, it belongs in skills.
-
-## Key files and directories
-
-| Path | Responsibility |
-|---|---|
-| `src/cli.ts` | Typed command handlers: manifests, actions, doctor, runtime health/decision/launch, `run`. |
-| `src/runner.ts` | Creates the Recipe runner by combining shared core/ui adapters with MetaMask live adapters. Enables the Recipe HUD metadata. |
-| `src/adapters.ts` | MetaMask adapter binding and `ui.*` transport selection for Mobile vs Extension. Refuses static placeholders for live-only proof actions. |
-| `src/live-adapter-contract.ts` | Script adapter contract and lookup rules for `library/actions/<platform>/<domain>/*.mjs`. |
-| `library/manifests/*.action-manifest.json` | Reviewable capability contract. A recipe may only call declared actions. |
-| `library/actions/mobile/` | Mobile action implementations. Talks to the runner bridge and app-exposed `globalThis.__AGENTIC__` hooks. |
-| `library/actions/extension/` | Extension action implementations. Talks to Chrome/extension pages over CDP. |
-| `adapters/mobile/inject.sh` | Installs/syncs the Mobile runtime overlay under the configured harness root and protects cleanup/git-exclude behavior. |
-| `adapters/extension/inject.mjs` | Installs/syncs Extension runtime helpers under the configured harness root. |
-| `adapters/mobile/` | Runner-owned Mobile launch/live/inject/cleanup and verify helpers copied into installed harnesses. |
-| `adapters/extension/` | Runner-owned Extension launch/live/watch/windows/wallet-state/readiness helpers (orchestration) and verify (recipe) copied into installed harnesses. |
-| `adapters/shared/path-defaults.json` | Single source for default `recipeHarnessRoot` and `recipeRuntimeDir`. |
-| `adapters/shared/harness-path.sh`, `src/paths.ts` | Shell and TypeScript accessors for those defaults plus validation. |
-| `library/recipes/` | Reusable smoke/runner.action-validation recipes only. Task-specific proof recipes stay task-local. |
-| `library/library.json`, `library/flows/` | Canonical recipe library: minimal, stable flows recipes can `call`. Personal/team libraries shadow it by default — see [Recipe Libraries](recipe-libraries.md). |
-| `docs/` | Runner architecture, contracts, and operational conventions. |
-
-## Runtime paths and installed harnesses
-
-Defaults are centralized in `adapters/shared/path-defaults.json`:
-
-```json
-{
-  "recipeHarnessRoot": "temp/recipe/harness",
-  "recipeRuntimeDir": "temp/recipe/runtime"
-}
-```
-
-All shell, standalone Node, and TypeScript code must read these through the
-shared helpers instead of hardcoding defaults. Environment overrides are allowed
-through `RECIPE_HARNESS_ROOT` and `RECIPE_RUNTIME_DIR`, but they must stay safe
-relative paths.
-
-Install commands write a small runtime package into the target checkout:
-
-```text
-<target>/<recipeHarnessRoot>/<adapter>/
-  manifest.json              installed source/revision/cleanup metadata
-  action-manifest.json        snapshot of the adapter manifest
-  runner/bin/mm-harness       delegate back to the resolved runner source
-  runner/recipes/             reusable recipe snapshot
-  scripts/                    adapter runtime helpers copied from this repo
-```
-
-The installed harness exists so a running slot has stable helper paths even when
-called from skills, orchestration hooks, or a human shell. The source of truth remains
-this runner.
-
-## Recipe execution vs sandbox lifecycle
-
-`mm-harness run <recipe.json> --adapter ...` is the recipe path. It creates
-a shared Recipe runner (`src/runner.ts`), validates the recipe against the
-manifest, executes nodes, and writes artifacts. If a bug is about action fields,
-trace output, adapter semantics, or whether a recipe proves a claim, start in
-`library/manifests/`, `src/`, `library/actions/`, and `library/recipes/`.
-
-`prepare`, `launch`, `live`, `verify`, `status`, `decision`, and `ready` are
-sandbox lifecycle paths. They give the agent a reproducible local app session:
-Mobile with Metro/dev-client/simulator and the bridge online; Extension with an
-isolated browser profile, unpacked extension loaded, and a known home/popup-style
-UI target. If a bug is about Metro, bundle prewarm, simulator launch, Chrome CDP,
-Extension full-screen vs popup presentation, build freshness, wallet fixture
-placement, git-exclude, or cleanup, start in `adapters/{mobile,extension,core}/`.
-
-Do not put recipe graph traversal into shell scripts. Shell scripts may prepare
-or inspect the sandboxed runtime, then delegate graph execution to
-`mm-harness run`.
-
-## HUD vs bridge vs product hooks
-
-These names are easy to mix up; they are different concerns.
-
-| Term | What it is | Why it exists |
-|---|---|---|
-| Recipe HUD | A visual overlay driven by Recipe runner metadata (`intent`, current node, status). | Makes screenshots/videos explain what the recipe is doing without exposing secrets. |
-| Mobile bridge | Runner-side CDP/Hermes bridge process under `adapters/mobile/bridge-runtime/`. | Lets the runner call app-exposed commands, read state, press UI targets, and capture status from React Native. |
-| `globalThis.__AGENTIC__` | Development-only in-app command surface exposed by the Mobile overlay/patch. | Gives the bridge a stable API for route/status/wallet/UI operations when the app lacks a built-in automation API. |
-| Extension CDP hooks | Chrome DevTools Protocol access to extension pages/background state hooks. | Lets the runner inspect/drive the unpacked Extension without patching product source. |
-
-The HUD does not control the app. The bridge/CDP control the app. The HUD only
-renders proof context.
-
-## Mobile runtime shape
-
-Mobile has the most moving parts because React Native does not expose a browser
-DOM by default.
-
-```text
-mm-harness launch ios|android
-      │ prepareMobile() in-process → yarn-setup / start-metro / open-device leaves
-      ▼
-adapters/mobile/bridge-runtime/cdp-bridge.cjs
-      │ connects to Hermes / RN debug runtime
-      ▼
-globalThis.__AGENTIC__ inside the app
-      │ route/status/wallet/ui commands + optional HUD rendering
-      ▼
-library/actions/mobile/{wallet,perps,ui,platform}/*.mjs
-```
-
-Ideally the app would expose a product-owned debug automation surface directly,
-so the runner would not need to patch or inject Mobile client files at all. The
-current injection exists as a compatibility bridge: it lets recipes run against
-older Mobile versions, historical PR branches, and eval/replay runs that do not yet include that
-client-side automation surface.
-
-The Mobile injection currently may touch development-only product files on older
-checkouts to install the `AgenticService`, navigation hook, and HUD mount. That
-is the fragile compatibility path, not the desired long-term product contract.
-Those product patches are local runtime state: never commit them to MetaMask
-Mobile. The runner also installs ignored helper files under
-`temp/recipe/harness/mobile`.
-
-Mobile `ensure_*` actions must be idempotent: if the wallet is already unlocked,
-`metamask.wallet.ensure_unlocked` should report success or converge cheaply, not
-fail because the starting state differed.
-
-## Extension runtime shape
-
-Extension does not need an in-product source patch. The runner works through an
-unpacked `dist/chrome` build and Chrome CDP.
-
-```text
-mme-recipe / adapters/extension/*.sh
-      │ checks dist freshness, build health, fixture/profile state
-      ▼
-Chrome for Testing with --load-extension=<runtime-dist>
-      │ CDP target discovery + deterministic extension id
-      ▼
-library/actions/extension/{wallet,perps,ui,platform}/*.mjs
-      │ extension page/background hooks and UI events
-```
-
-`runtime-launch --start-watch` is the clean-build path. Without `--start-watch`,
-verify can prove the existing runtime is reachable but may fail `dist-freshness`
-if `dist/chrome` does not match `HEAD`. That failure is intentional: it prevents
-silently proving stale product code.
-
-## Why there are shell scripts
-
-The shell scripts are large because sandbox setup crosses OS/device boundaries:
-`simctl`, `adb`, Metro, Watchman, Chrome process flags, isolated browser
-profiles, git exclude files, symlink safety checks, and cleanup all live outside
-Node's typed domain logic. Their purpose is to give an agent a reliable app
-session, not to define recipe semantics.
-
-Allowed in shell:
-
-- parsing CLI flags for lifecycle commands;
-- calling OS/device tools;
-- copying/removing installed harness files;
-- starting/stopping/reusing local dev servers;
-- writing small runtime summaries from command results.
-
-Not allowed in shell:
-
-- Recipe v1 graph execution;
-- MetaMask domain semantics that can live in `src/**/*.ts` or `library/actions/**/*.mjs`;
-- duplicated action manifest logic;
-- product-specific business decisions beyond runtime boot/health checks.
-
-When a shell helper starts accumulating domain behavior, move that behavior into
-TypeScript or a focused `.mjs` adapter and keep shell as the launcher.
-
-## Adding or changing capabilities
-
-1. Add/adjust the shared capability in both Mobile and Extension manifests when
-   the concept exists on both platforms.
-2. Implement durable behavior under `library/actions/<platform>/<domain>/`.
-3. Keep parameterized actions instead of multiplying action names.
-4. Ensure every `ensure_*` action proves a postcondition.
-5. Use official `ui.*` actions and screenshot claims for visible acceptance
-   criteria; do not add task-specific `metamask.*` actions for exact copy,
-   styling, ticket IDs, or one-off selectors.
-6. Update smoke/runner.action-validation recipes only when the capability is reusable.
-
-## Standalone use first; farm later
-
-This runner should make sense without any slot farm:
-
-1. choose a local MetaMask Mobile or Extension checkout;
-2. run `mm-harness launch <platform>` (or `mm-harness install` for the overlay only);
-3. run `mm-harness doctor` (or the advanced `runtime-health`);
-4. run `mm-harness run <recipe.json> --adapter <platform> --artifacts-dir <dir>`.
-
-Skills are optional workflow wrappers around that same CLI. A wrapper may resolve
-the runner source and package evidence, but it should dispatch `install`,
-`launch`, `live`, `verify`, and `cleanup` to this repo or to the installed
-harness helper. It should not carry Mobile or Extension adapter scripts.
-
-Farm/slot orchestration belongs one layer outside this runner. It can scale the
-standalone loop by choosing checkouts, machines, ports, simulators, and agents,
-but it should not change the runner contract or copy runner implementation.

package/docs/live-adapter-contract.md

@@ -1,188 +0,0 @@
-# Live Adapter Contract
-
-The MetaMask runner implements Recipe Protocol v1 through the shared recipe
-harness package. Project-specific live behavior is supplied by
-manifest-declared action adapters.
-
-Official `ui.*` semantics are implemented by
-`createStandardUiAdapters({ transport })` plus shared CDP/React Native base
-transports. The MetaMask runner supplies only tiny runtime bindings that point
-those base transports at the Extension CDP page or Mobile React Native bridge.
-MetaMask-specific actions remain separate manifest-declared live adapters.
-
-For actions that must prove real product behavior, especially `metamask.perps.*`, static placeholders are refused by default. A live adapter script must exist in one of these locations. Domain-grouped paths are preferred so code ownership stays obvious:
-
-```text
-$METAMASK_RECIPE_LIVE_ADAPTER_DIR/<platform>/<domain>/<action-local-name>.mjs
-$METAMASK_RECIPE_LIVE_ADAPTER_DIR/shared/<domain>/<action-local-name>.mjs
-<runner>/library/actions/<platform>/<domain>/<action-local-name>.mjs
-<runner>/library/actions/shared/<domain>/<action-local-name>.mjs
-```
-
-Legacy external `.js` adapters are still resolved for compatibility, and `.sh` remains available for edge orchestration. New committed adapter code should use grouped `.mjs` modules. Fully-qualified flat filenames are still searched after grouped paths, but new adapter code should use grouped modules. Do not add `ui.*` files here; official UI actions go through shared base transports. Examples:
-
-```text
-library/actions/extension/perps/ensure_positions.mjs
-library/actions/extension/perps/close_positions.mjs
-library/actions/extension/perps/close_orders.mjs
-library/actions/mobile/perps/place_order.mjs
-library/actions/mobile/wallet/ensure_unlocked.mjs
-```
-
-The runner invokes the script with one argument: a JSON input file path. The same path is also available as `METAMASK_RECIPE_ADAPTER_INPUT`. The script must write JSON to `outputPath` from the input document, or print JSON to stdout.
-
-Input shape:
-
-```json
-{
-  "schemaVersion": 1,
-  "platform": "mobile|extension",
-  "action": "metamask.perps.ensure_positions",
-  "node": {},
-  "context": {
-    "nodeId": "ensure-clean",
-    "projectRoot": "/path/to/product",
-    "artifactsDir": "/path/to/artifacts"
-  },
-  "outputPath": "/tmp/.../output.json"
-}
-```
-
-Output shape is action-specific, but must be redacted and suitable for `trace.json`. If the adapter captures evidence files, write them under `context.artifactsDir` and return relative artifact paths for the runner adapter to index in a follow-up implementation.
-
-Proof rule: live adapters must drive real supported app/API paths. They must not write directly into UI state, DOM state, React/Redux/MobX state, local storage, controller internals, or any mid-recipe state that fabricates the proof condition.
-
-## Controller/API calls vs visible UI proof
-
-Recipe authors should choose the layer based on what must be proven:
-
-| Need | Use | Rule |
-|---|---|---|
-| Fast reproducible setup/teardown before or after the proof window | `metamask.*` domain actions such as `start_state`, `ensure_positions`, `close_orders` | May use supported product/controller APIs, but must read/assert the final state. |
-| Read-only state proof | `metamask.*.read_*` or `metamask.*.assert_*` | Must return redacted live state in trace output. |
-| Human-visible acceptance criterion | official `ui.*` actions | Drive the actual visible path: press/tap, input/keypad, scroll into view, screenshot. Do not replace it with a controller call. |
-| Ticket-specific visual detail | task-local recipe assertions/evidence | Do not add a reusable action only for one ticket. |
-
-## Shared action-surface boundaries
-
-The manifest is a durable capability contract, not a place to encode one
-ticket's acceptance criteria. Do not add shared `metamask.*` actions for ticket
-IDs, POCs, exact test IDs, exact copy, styling, placement, or other one-off UI
-proof needs.
-
-Use:
-
-- official `ui.*` actions for reusable presence, input, scroll, and screenshot
-  behavior;
-- screenshot `claims` for visual, copy, and layout proof;
-- task-local composed flows under the task artifact directory when a ticket
-  needs a reusable helper for that ticket only;
-- safe direct CDP/controller calls for read/assert or supported setup paths,
-  never state fabrication.
-
-Add or keep a shared action only when it represents a durable parameterized
-domain capability useful across many tasks, such as `metamask.perps.start_state`,
-`metamask.perps.place_order`, `metamask.perps.close_positions`, or
-`metamask.perps.assert_positions`.
-
-`ui.scroll` is part of the current executable contract and runner.action-validation must
-prove both normal scrolling and `scroll_into_view` before screenshot capture.
-`ui.gesture` is intentionally not advertised yet; drag/swipe proof must wait
-until the shared runtime and this runner expose and validate that action on both
-platforms.
-
-
-
-## Flow catalog follow-up
-
-Action adapters fulfill one manifest-declared operation. Production recipes should also be able to call domain flow catalogs that compose these operations into idempotent `ensure_*` start states. These flows are owned by this runner/domain layer, not by shared runtime packages or wrapper glue.
-
-For Perps, recipes should use the runner-provided `metamask.perps.start_state({ network, provider, page, market, positions, orders })` and `metamask.perps.teardown_state(...)` actions as the default reproducibility boundary. These actions compose primitive bulk operations such as `close_positions({ mode: "all" })` and `close_orders({ mode: "all" })` instead of multiplying one-off cleanup actions.
-
-## Built-in Extension live adapters
-
-The first Extension adapter set is bundled under `library/actions/extension/` and talks directly to the Chrome extension page target over CDP. It does not execute a second recipe graph. The v1 runner still owns workflow traversal; each script only fulfills one manifest-declared action.
-
-Runtime input:
-
-```text
-node.cdp_port | CDP_PORT | RECIPE_CDP_PORT
-```
-
-Optional autolaunch input for existing Extension builds:
-
-```text
-METAMASK_RECIPE_EXTENSION_AUTOLAUNCH=1
-METAMASK_RECIPE_EXTENSION_LAUNCH_EXISTING_DIST=1
-node.launch_existing_dist=true
-```
-
-When enabled, the adapter reuses the requested CDP port if a compatible extension target exists; otherwise it launches Chrome from the target checkout's existing `dist/chrome` without rebuilding the product. The runtime copy, profile, logs, and `runtime.json` are written under `context.artifactsDir/extension-runtime/`.
-
-CLI equivalent:
-
-```bash
-mm-harness run <recipe.json> --adapter extension --cdp-port 6664 --launch-existing-dist --artifacts-dir <dir>
-```
-
-The CLI maps `--cdp-port` to `CDP_PORT`/`RECIPE_CDP_PORT` and maps `--launch-existing-dist` to `METAMASK_RECIPE_EXTENSION_AUTOLAUNCH=1` for the duration of the recipe run.
-
-Currently implemented Extension actions:
-
-```text
-ui.navigate                  # extension: page alias or hash/path/url
-metamask.perps.read_positions
-metamask.perps.read_orders
-metamask.perps.close_positions # primitive bulk close selected positions
-metamask.perps.close_orders    # primitive bulk cancel selected orders
-metamask.perps.place_order
-metamask.perps.assert_positions
-metamask.perps.assert_orders
-metamask.perps.ensure_positions # high-level read/close/place/assert wrapper
-metamask.perps.ensure_orders    # high-level read/cancel/assert wrapper
-ui.press
-ui.scroll
-ui.wait_for
-ui.screenshot
-```
-
-Navigation supports a small discoverable `page` alias set (`home`, `perps`, `perps-market`) plus raw extension hash/url fallback. Check the action manifest before hardcoding routes.
-
-Task-specific UI styling checks, such as one ticket proving a banner color or placement, must not be implemented as reusable `metamask.perps.*` actions. Use official `ui.wait_for` for reusable presence/absence checks plus screenshot/task-local validation evidence for that ticket.
-
-Read-only position checks use `stateHooks.submitRequestToBackground('perpsGetPositions', [{ skipCache: true }])`. State-changing actions prefer UI interaction through CDP mouse/keyboard events. Bulk cleanup primitives may call product background APIs such as `perpsClosePositions` or `perpsCancelOrders` when the UI control is unavailable; this is a supported app/API path, not direct state mutation. Adapters must not mutate Redux/React state, DOM state, local storage, or controller internals to fabricate proof.
-
-## Built-in Mobile live adapters
-
-The Mobile adapter is bundled under `library/actions/mobile/`. Its CDP bridge, wallet setup, target discovery, and screenshot helpers run from the runner runtime; the Mobile checkout must not own harness control scripts. The app still needs a development-only in-app bridge/HUD overlay when a historical checkout does not expose the required `globalThis.__AGENTIC__` hooks.
-
-Runtime input:
-
-```text
-node.watcher_port | node.metro_port | node.cdp_port | WATCHER_PORT | CDP_PORT | RECIPE_CDP_PORT
-node.simulator | node.ios_simulator | IOS_SIMULATOR
-node.android_device | ANDROID_DEVICE
-```
-
-Currently implemented Mobile actions:
-
-```text
-ui.navigate                  # mobile: page alias or route/screen + params
-metamask.perps.read_positions
-metamask.perps.read_orders
-metamask.perps.close_positions # primitive bulk close selected positions
-metamask.perps.close_orders    # primitive bulk cancel selected orders
-metamask.perps.place_order
-metamask.perps.assert_positions
-metamask.perps.assert_orders
-metamask.perps.ensure_positions # high-level read/close/place/assert wrapper
-metamask.perps.ensure_orders    # high-level read/cancel/assert wrapper
-ui.press
-ui.scroll
-ui.wait_for
-ui.screenshot
-```
-
-Navigation supports a small discoverable `page` alias set (`home`, `perps`, `perps-market`) plus raw React Navigation route/params fallback. Check the action manifest before hardcoding routes.
-
-Read-only position checks use `Engine.context.PerpsController.getPositions()` through Hermes CDP. State-changing Perps actions use supported controller APIs (`placeOrder`, `closePositions`) through the same app bridge rather than mutating Redux/React/local storage. UI actions delegate to existing bridge capabilities such as `press-test-id` and `scroll-view`. Screenshot capture uses `xcrun simctl io <simulator> screenshot` for iOS simulator proof.

package/docs/package-boundaries.md

@@ -1,47 +0,0 @@
-# Package Boundaries
-
-This package intentionally stays as **one npm package** with a clear internal
-split. Splitting into two packages now would make users choose between packages
-before the runtime API is stable. Instead, keep one install surface and separate
-responsibilities inside the repo.
-
-## Internal split
-
-| Area | Owns | Does not own |
-|---|---|---|
-| Recipe layer | Action manifests, reusable recipes, typed runner binding, Mobile/Extension live adapters, proof semantics. | Starting Metro/Chrome, simulator boot, native builds, git cleanup. |
-| Runtime lifecycle layer | Harness install/cleanup, Metro/dev-client launch, bundle prewarm, Chrome/CDP launch, fixture/profile setup, readiness gates. | Recipe graph execution, action vocabulary decisions, task-specific proof logic. |
-
-## Stable command contract
-
-Keep the public package simple:
-
-```bash
-mm-harness launch ios ...               # runtime lifecycle, then readiness proof (mobile)
-mm-harness launch ...                   # runtime lifecycle, then readiness proof (extension)
-mm-harness run <recipe.json> ...        # recipe execution only
-```
-
-Wrappers such as skills or slot farms should call those commands. They should not
-copy adapter scripts or reimplement Metro/Chrome launch behavior.
-
-## Why not two packages yet?
-
-A future split may be useful, for example:
-
-- `@metamask/recipe-runner` for manifests/adapters/proof execution;
-- `@metamask/recipe-runtime` for Mobile/Extension sandbox launch.
-
-Do that only after the runtime CLI is stable, all wrappers call it exclusively
-(no copied adapter scripts), and the two areas have gone several releases
-without a change that touches both. Until then, two packages would likely
-increase confusion and version skew.
-
-## Change discipline
-
-1. Prefer moving behavior into the runner before changing farms/skills.
-2. Keep compatibility wrappers when renaming files or commands.
-3. Validate both paths after runtime changes:
-   - direct runner/skill path;
-   - Farmslot/Command Center prepare path.
-4. Do not move files just for tidiness if callers still depend on old paths.