Skip to content

feat(open): let a polling caller skip the first-screen wait - #4599

Merged
thymikee merged 4 commits into
mainfrom
feat/open-settle-opt-out
Nov 16, 2026
Merged

thymikee merged 4 commits into
mainfrom
feat/open-settle-opt-out

Conversation

@thymikee

@thymikee thymikee commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Summary

Since #4513, the first capture after open on a local iOS simulator waits up to 10 s for a labeled first screen. An app whose first screen labels nothing, such as a game canvas, always waits the full 10 s. open now accepts the existing postGestureStabilization opt-out, so a caller that polls the screen itself can skip the wait:

agent-device open com.example.game --foreground --no-post-gesture-stabilization
AGENT_DEVICE_POST_GESTURE_STABILIZATION=0 agent-device open com.example.game   # operator-wide
await client.apps.open({ app: 'com.example.game', postGestureStabilization: false });

With the opt-out set, open marks no wait. On every platform, it still drops the record the replaced screen left pending, such as a scroll's stabilization record. The field stays operator-only: MCP and AI SDK schemas do not offer it, so the always-loaded schema budget doesn't change, and ./agent-device.json still rejects the key.

Rebased on #4601. The open docs paragraph also takes two wording fixes from #4601's review: "An unlabeled splash image", and the game-canvas example moved to the no-labeled-element clause.

10 files: the open surface and client type, the daemon mark, flag and client docs, the guarantee cell, the user docs, and one test.

Validation

At 1c9adf2, with the review fixes rechecked at b0126a4 (typecheck, lint, 1,992 affected tests):

  • pnpm typecheck and pnpm lint pass.
  • Vitest passes for command-surface, command-registry, contracts, client, daemon sessions, src/commands, src/mcp and the deferred-outcome tests: 3,662 tests.
  • Probe: prepareDaemonCommandRequest('open', { postGestureStabilization: false }) carries the field to the daemon.
  • Live, iPhone 17 Pro simulator on iOS 27.0, Settings: open --relaunch --foreground with and without the flag, 3 runs each. All succeed with the full tree and no postGestureOutcome. Settings labels its first screen at once, so timing doesn't separate the two modes; the daemon test covers the skip.
  • Live on React Native at cb1bbfd: same simulator, Agent Device Tester Debug dev build, Metro serving. open --relaunch --foreground --metro-port 8081, interleaved, 4 runs per mode. All 12 runs returned the 52-node home screen with no postGestureOutcome. Median time: 7.3 s by default, 6.5 s with --no-post-gesture-stabilization, 6.3 s with AGENT_DEVICE_POST_GESTURE_STABILIZATION=0. The relaunch itself takes about 6 s, so the home screen is already drawn when open reads it, and the opt-out saves the confirming second read. The env run shows the operator config reaches open.
  • After the rebase, at 65294d3: build, typecheck and lint pass, and 2,611 affected tests pass.
  • CI owns the remaining gates.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.32 MB 6.32 MB +492 B
Package (unpacked) 6.32 MB 6.32 MB +492 B
Package (download) 1.92 MB 1.92 MB +95 B

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 33.3 ms 27.6 ms -5.7 ms
CLI --help 81.7 ms 70.9 ms -10.8 ms

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 10 files

You’re at about 96% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread website/docs/docs/commands.md Resolved
Comment thread website/docs/docs/configuration.md Resolved
@apex-sentinel-staging

apex-sentinel-staging Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve

Since the last review: 0 new · 0 still open · 0 no longer raised

No open findings.

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (b3c1a3c8abd9).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

Earlier reviews

Review of cb1bbfda · 16.11.2026 16:12 UTC

Apex Sentinel · ✅ Approve

Since the last review: 0 new · 0 still open · 1 no longer raised (1 marked fixed)

No open findings.

Reviewed with this repository's own Sentinel configuration (244d1ff68344).

Review of 3f990900 · 16.11.2026 16:03 UTC

Apex Sentinel · ✅ Approve

1 finding(s): 1 minor.

🟡 Minor (1)

Where Finding
packages/daemon/src/core/deferred-interaction-outcome.ts:251 open --no-post-gesture-stabilization drops a pending stabilization even when the open launches no app

Reviewed with this repository's own Sentinel configuration (cfe08502f0f6).

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on 3f99090. The verdict and the full list are in the summary comment.

thymikee and others added 4 commits November 16, 2026 17:47
An app whose first screen labels nothing, such as a game canvas, held the
first capture after open for the full 10 s first-screen budget. open now
accepts the existing postGestureStabilization opt-out
(--no-post-gesture-stabilization, the user config key, or
AGENT_DEVICE_POST_GESTURE_STABILIZATION=0). With it, open marks no wait and
still drops the record the replaced screen left pending.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t-out is set

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed an app

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee
thymikee force-pushed the feat/open-settle-opt-out branch from cb1bbfd to 65294d3 Compare November 16, 2026 16:50
@thymikee

Copy link
Copy Markdown
Member Author

This PR is ready at 65294d3: I found no problems in the code, and the first-screen skip follows the issue. All 13 CI jobs are still running on this head and none has failed, so they need to pass before merge. There are no conflicts.

Not blocking, and you can take or leave each: (1) the only committed tests call markPostOpenStabilization directly, so dropping the req.flags argument at https://github.com/callstack/agent-device/blob/65294d3/packages/daemon/src/sessions/session-lifecycle/internal/session-open-execution.ts#L406 or the flag in the open reader or allowedFlags would leave them green, and one route-level assertion next to the scroll case in command-surface/src/interaction/metadata.test.ts would cover it; (2) the flag branch at https://github.com/callstack/agent-device/blob/65294d3/packages/daemon/src/core/deferred-interaction-outcome.ts#L251 runs before the Apple and mobile gates, so an opt-out open on Android or desktop now drops a pending scroll record, and moving it after those gates would leave other platforms untouched; (3) the open --foreground usage line at https://github.com/callstack/agent-device/blob/65294d3/packages/command-registry/src/flag-definitions-action.ts#L414 still mentions the 10s wait without pointing to the opt-out; (4) the unlabeled-first-screen case the docs promise at https://github.com/callstack/agent-device/blob/65294d3/website/docs/docs/commands.md#L102 was not run live, since both live series used apps with labeled first screens; and (5) the user config key and env var now also change open for existing users, which the bullet at https://github.com/callstack/agent-device/blob/65294d3/website/docs/docs/commands.md#L570 states, so a release note is optional.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 16, 2026
@thymikee
thymikee merged commit d97c714 into main Nov 16, 2026
22 checks passed
@thymikee
thymikee deleted the feat/open-settle-opt-out branch November 16, 2026 17:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-human Valid work that needs human implementation, judgment, or maintainer merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant