[cryptotavares]

Summary: Let each tool call choose observe: 'none' | 'diff' | 'full'. Remove app state from observations and stop the mobile driver from inventing wallet-state values.

Stack context: mm CLI v2, Phase 1, P1-06 + P1-07, combined at the shared observation boundary. Base: cryptotavares/mmcli-p1-05-observe-mutating-only; review #61 first. Followed by #64.

Problem

Tool categories fix the observation policy. Callers cannot skip a snapshot while chaining clicks or request one after a read. run_steps uses a separate includeObservations policy.

Observations also combine screen data with app state. Mobile returns guessed wallet values, including isUnlocked: true and currentScreen: "unknown". Browser observation collection reads extension state and can spend another 500 ms rechecking an unknown screen.

These concerns belong at different boundaries: the daemon controls observations, while get_state reports platform state.

Solution

Add one shared observation field to registered tool schemas. Consume it in the daemon, outside the tool-handler contract.

flowchart TD
    A[CLI --observe or HTTP observe] --> B[Validate the shared observe field]
    B --> C[Strip observe before handler dispatch]
    C --> D[Execute the tool or batch]
    D --> E[Resolve explicit level or default]
    E -->|none or no active session| F[Return the tool response]
    E -->|diff or full with active session| G[Collect test IDs and a11y only]
    G --> H[Compact options; full skips diff]
    H --> F

    classDef new fill:#fff3cd,stroke:#d39e00
    class A,B,C,E,G,H new

Loading

Yellow boxes are new.

withObserve() preserves existing schema refinements and defaults through intersections. Both HTTP and batch dispatch call omitObserve() before the handler. Consumer launch implementations therefore receive their existing input shape.

For run_steps, the top-level level wins. Otherwise, the last executed step's args.observe wins, then diff. Timeout-skipped steps do not count. Earlier per-step levels do not trigger separate observations.

Observation collection reads only test IDs and accessibility nodes. It no longer calls getExtensionState() or getAppState(). Browser collection waits for page settling for mutating, batch, and CDP calls. Read-only and discovery calls skip that wait.

What changes

Condition or boundary	Before	After
Default tool call	Category controls collection; batch has a separate policy	diff for mutating tools and batches; none for read-only, discovery, and CDP tools
Explicit observe: 'none'	No shared override	Skips collection and returns no observations; observationMs is zero
Explicit observe: 'diff' or 'full' with an active session	No shared override	diff uses the previous snapshot; full returns the whole option-collapsed tree without diff metadata
CLI --observe <level>	Unsupported	Accepted anywhere; injected into POST /tool/*, /launch, and /cleanup object bodies; an existing body field wins
run_steps.includeObservations	Accepts all, none, or failures	Fails validation with includeObservations was removed; use observe
Observation payload	App state, test IDs, and a11y	Test IDs and a11y only; use get_state for app state
Mobile getAppState()	Adds guessed wallet fields	Returns { isLoaded, extensionId, source: 'stub' }; unread fields are omitted

For ordinary calls, a full observation becomes the next diff baseline; none leaves it unchanged. Existing reset tools still clear it: describe_screen, accessibility_snapshot, launch, and cleanup.

An invalid CLI level exits with code 1 and prints:

Error: --observe requires one of: none, diff, full

Decisions for reviewers

Decision	Reason
Combine P1-06 and P1-07	Observation selection and state removal change the same collection path. Keeping one boundary avoids separate platform policies.
Consume observe outside handlers	The daemon owns collection. Shared validation accepts the field without passing it into consumer implementations.
Collect once after a batch	The final screen supplies the batch observation. Top-level configuration takes precedence over the last executed step.
Keep full compacted	Callers skip diffing but retain option collapsing. The existing discovery tools remain available for unfiltered trees.
Mark mobile state as partial	Optional ExtensionState fields distinguish unread data from real false, empty, or null values.
Keep the registered-function dispatch guard	The HTTP executor checks registry membership and callable type before dispatching a request-derived tool name.

Review guide

Read the files in this order:

#	File	What to check
1	src/validation/schemas.ts, src/tools/types/tool-inputs.ts	Shared levels, schema intersections, removed batch policy, and omitObserve.
2	src/server/create-server.ts, src/tools/batch.ts, src/tools/registry.ts	Override precedence, timeout-skipped steps, handler isolation, category defaults, and registered-function dispatch.
3	src/tools/types/observation.ts, src/server/observation-compaction.ts	State-free snapshots, option compaction, full-versus-diff behavior, and baseline handling.
4	src/capabilities/types.ts, src/platform/mobile-platform-driver.ts	Optional state fields and the mobile partial-state result.
5	src/cli/mm.ts	Global parsing, exact error text, request-body injection, and body-field precedence.
6	Changed tests, README.md, SKILL.md	HTTP and batch behavior, CLI injection, mobile state, and caller migration guidance.

Testing

• Fresh check at remote head 9f8803964119722b13c10e989be20aa5e035c0bc: CI=true yarn vitest run src/cli/mm.test.ts src/platform/mobile-platform-driver.test.ts src/server/create-server.test.ts src/server/observation-compaction.test.ts src/tools/batch.test.ts src/tools/registry.test.ts src/tools/types/observation.test.ts src/validation/schemas.test.ts --coverage.enabled=false --maxWorkers=2 passes: 8 files, 683 tests. Vitest reports no type errors.
• yarn lint and the production type check, yarn tsc --noEmit --emitDeclarationOnly false -p tsconfig.build.json, pass.
• Standalone yarn tsc --noEmit -p tsconfig.json fails with nine test-fixture diagnostics already present at this remote head. These affect Hermes, mobile backend mocks, a server test table, mock-network result narrowing, and a screenshot fixture.
• The tests cover category defaults, explicit overrides, last-executed-step selection, stripped handler input, full/diff baselines, and state-free observations.
• The Proof and Unit tests sections below retain the original historical evidence. These fresh checks do not repeat live platform validation.

Breaking changes

• run_steps.includeObservations is removed. Sending it is a validation error (includeObservations was removed; use observe). The 'failures' mode is gone.
• Observations no longer contain state:
  • StepRecordObservation has no state field;
  • createDefaultObservation(testIds, nodes) drops its first parameter.
• ExtensionState: currentUrl, isUnlocked, currentScreen, accountAddress, networkName, chainId and balance are optional. New field: source?: 'stub'.
• MobilePlatformDriver.getAppState() returns { isLoaded, extensionId, source: 'stub' } only.
• shouldCollectObservations and shouldIncludeObservationsInResponse are replaced by resolveObserveLevel(category, input, toolResult).
• toolSchemas entries are now intersections that include observe. The individual *InputSchema exports are unchanged.

Consumer impact

Consumer	Change needed	Done on branch
Extension test/e2e/playwright/llm-workflow/	None. Its own ExtensionState with required fields still type-checks against the looser core type, and nothing reads observations.state or includeObservations. Jest: 144 passed.	n/a
Mobile tests/llm-workflow/	The state snapshot capability stops inventing isUnlocked/currentScreen/null fields: with no session it reports {isLoaded:false, extensionId:'', source:'stub'}, and it omits currentScreen when no known testId matches. Jest: 232 passed.	cryptotavares/mm-cli-v2-mobile 35fc72cc609

Follow-up, not in this PR: on mobile, core get_state calls the driver directly, so the Mobile capability's screen detection only runs on browser. Phase 2 mm state (P2-09) covers this.

Proof

Tested with a yalc build of this branch in the Extension (e2e build, headless) and Mobile (dev client on iOS sim and Android emulator), on wallet home after unlock. Before = #61 tip; its proof is reused, except the Extension click bench, which was run on both builds back to back.

Same command at each level (after; bytes / totalMs):

Platform	none	diff	full
ext (click a home tab)	197 / 17	6760 / 581	9441 / 586
iOS (wait-for wallet-screen)	183 / 880	7495 / 2923	58865 / 2905
Android (click tab-bar-item-Wallet)	193 / 1794	7672 / 3671	1059191 / 3666

Check	Result
click --observe none	no observations, observationMs 0, on all 3 platforms
get-state --observe full	observation with testIds + a11y only: no state, no diff
run-steps, top-level observe: none / last step observe: full	no observations / full tree without diff (all 3 platforms)
run-steps with includeObservations	exit 1: includeObservations was removed; use observe
observations.state in any of the 55 after outputs	none
Mobile get-state, before → after	isUnlocked: true, currentScreen: "unknown", currentUrl: "", 4 × null → {isLoaded, extensionId, source: "stub"}
ext click observationMs p50 (bench, 5 runs, back to back)	564 → 555 ms; bytes 7335 → 6760 (the state block)
ext smoke click-unlock (unlock → home) observationMs	71 → 15 ms (the re-check loop no longer runs while the screen is unknown)

The bench gain is small because on home the screen is already known, so the 500 ms re-check rarely ran. Most of the remaining ~550 ms is the animation wait plus the a11y snapshot. P1-10 targets the animation wait.

Transcripts (ext)

$ yarn mm click --testid unlock-submit --observe none
{
  "clicked": true,
  "target": "testId:unlock-submit",
  "meta": { "timing": { "queueMs": 0, "toolMs": 32, "observationMs": 0, "totalMs": 33 } }
}

$ yarn mm run-steps '{"steps":[{"tool":"get_state"}],"includeObservations":"none"}'
Error: includeObservations: includeObservations was removed; use observe
exit=1

$ yarn mm --observe bogus get-state
Error: --observe requires one of: none, diff, full
exit=1

Unit tests

Test Files  46 passed (46)
     Tests  1450 passed (1450)
Type Errors no errors
All files | 96.94 | 93.52 | 94.91 | 97.12
yarn lint → exit 0

New or changed:

• resolveObserveLevel: category defaults, an explicit level wins, an invalid level is ignored, run_steps last executed step and failure fallback.
• Endpoint tests: click with none; get_state with full/diff; cdp with full waits for animations; observe is not passed to the handler; /cleanup body.
• No getExtensionState during observation (spy).
• Mobile getAppState shape.
• withObserve/omitObserve, includeObservations rejected, and the CLI --observe parsing and injection.

[cryptotavares]

Fixed CodeQL js/unvalidated-dynamic-method-call in 1bbfc70 (check the registry entry is a function before calling it).

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

[seaona]

2 small comments, let me know what you think 🙏

[seaona]

Minor: with --observe none the mutation returns without settling, and reads skip the settle even with --observe full
When both are chained in one shell call (mm click … --observe none && mm get-state --observe full), the snapshot can land mid-animation. Is it worth settling whenever an observation is collected, or is it fine to just note it in SKILL.md?

[cryptotavares]

Documented in #71 (SKILL.md and README): only mutating, batch and cdp calls wait for animations; reads and describe-screen read the page at once, so click --observe none && get-state --observe full can catch a screen mid-animation. The recommendation is to let the action itself observe (click --observe full). Since #65 made the settle cheap (about one frame on an idle page), waiting on every observation is an option for later.

[seaona]

With --observe none the ref map isn't refreshed, so the next ref-based action (e.g. mm click e5) uses selectors from the previous screen. If the screen changed, that selector can match a different element.
Some refs fail loudly with MM_TARGET_NOT_FOUND (after #66, the ones backed by a data-testid or id). But role-and-name and nth-child path refs, and mobile label refs, can silently click the wrong element.

Maybe worth adding a small note: "after --observe none, call describe-screen before using refs again" ?

[cryptotavares]

Yes, added to SKILL.md, the README and mm --help in #71: after --observe none refs are not refreshed, testId/id refs fail with MM_TARGET_NOT_FOUND, but role/name, DOM-path and mobile label refs can match a different element, so target by testId or run describe-screen before using refs again.