Skip to content

feat(revyl): install local builds and start sessions without an app - #4496

Merged
thymikee merged 2 commits into
callstack:mainfrom
KayaanT:feat/revyl-deferred-app
Nov 16, 2026
Merged

thymikee merged 2 commits into
callstack:mainfrom
KayaanT:feat/revyl-deferred-app

Conversation

@KayaanT

@KayaanT KayaanT commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

connect revyl no longer requires --provider-app. Without it, the device starts with no app, and install puts a local build on it, so an agent can install what it just built without hosting the build first. --provider-app behaves as before.

install and install-from-source stream the build to the session's storage, then install it with install_async, polling install_status through host-kit's pollUntilSettled against one Deadline. The whole install gets a 420 s budget inside the command's 480 s envelope, so a slow install fails with the plugin's error instead of a daemon reset.

reinstall refuses with UNSUPPORTED_OPERATION (unsupported-provider-mode). Revyl has no uninstall, and an install over an app keeps its data, so it cannot give the clean app reinstall promises. revyl.md and the capabilities table say so.

An app-less connect reports a deferred device and a missing app, the state the connect workflow answers with install before open.

Packing a .app directory has one owner now: packGzipTar(dir, { env, signal, timeoutMs?, fileName? }) in a new @agent-device/host-kit/gzip-tar subpath, returning { archivePath, cleanup }. It passes -- before the name and refuses an already-aborted signal. Remote's upload, daemon artifact tracking and Revyl all call it. Remote and the daemon load it with a function-scoped import(), so their eager closures don't grow. Two daemon archive tests now wait for tar to start before they fire the deadline, since that import moves the start one tick later.

agent-device connect revyl --platform ios
agent-device install com.example.app ./build/Example.app
agent-device open com.example.app

Validation

At 8716f86f8:

  • check:affected --run --head passed every step through vitest-related.
  • unit: 20,154 passed and 2 failed. Both failures are -Werror Swift tests, which need the iphonesimulator SDK this Mac lacks.
  • New tests cover the packer (single top-level entry, a name starting with -, cleanup after a failed or aborted pack), a completed install without a result, the streamed upload's declared length, the reinstall refusal before any upload, and the app-less connect's next steps.

Live Revyl output

From this head's build, with the plugin packed from packages/provider-revyl. Each session was started without --provider-app, and disconnect ended each one. Local paths are shortened.

connect revyl --platform ios:

Connected successfully with Revyl.
Verified: Credentials verified; Revyl picks the device when the session starts.
Device: Provider-selected device — allocated on first device command
App: not available — No app URL; the device starts without one. Install a build, then open it.
No live device session has been created. The first device command shown below will allocate one.
Next:
  agent-device install <bundle-id> <app-path-or-url> --session revyl-4496-ios
  agent-device open <bundle-id> --relaunch --session revyl-4496-ios

Then, on an Android session started by connect revyl --platform android:

$ agent-device install-from-source https://github.com/appium/android-apidemos/releases/download/v6.0.18/ApiDemos-debug.apk --platform android --json
{
  "success": true,
  "data": {
    "launchTarget": "io.appium.android.apis",
    "appId": "io.appium.android.apis",
    "package": "io.appium.android.apis",
    "message": "Installed: io.appium.android.apis"
  }
}

$ agent-device open io.appium.android.apis
Opened: io.appium.android.apis

$ agent-device snapshot -i
Page: io.appium.android.apis
App: io.appium.android.apis
Snapshot: 22 nodes
@e6 [text] "API Demos"
@e8 [list] [focused]
@e10 [text] "Accessibility"
@e11 [text] "Animation"
@e12 [text] "App"
...

$ agent-device reinstall io.appium.android.apis ./ApiDemos-debug.apk --json
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_OPERATION",
    "message": "Revyl cannot reinstall an app: it has no uninstall, and installing over an app keeps its data.",
    "hint": "Run install to update the build in place, or start a new session for a clean app.",
    "details": {
      "reason": "unsupported-provider-mode",
      "dispatched": "unknown"
    }
  }
}

The snapshot -i output is trimmed to its labelled rows. The earlier head's live runs also installed a local .apk (Android) and a local .app directory (iOS) with plain install.

CI obligations: the Apple-runner lanes.

@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 17 files

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

View guided diff | Re-trigger cubic

Comment thread website/docs/docs/revyl.md Resolved
Comment thread website/docs/docs/revyl.md Resolved
@thymikee

Copy link
Copy Markdown
Member

Thanks for this. At 6231cea I found two problems to fix before merge: the .app packer is a third copy of existing code, and the live evidence does not cover the new install-from-source and reinstall paths.

packAppBundle is a near-verbatim copy of createGzipTarArchive in packages/remote/src/upload-client-artifact.ts, which packages/daemon/src/resources/artifact-tracking.ts already duplicates. The three copies will drift. The daemon copy already guards the basename with -- and sets a timeout, and the Revyl copy does neither. One owner should pack an .app directory into a gzip tar for upload. Please move the packer to host-kit (provider-revyl already depends on it for runCmd) as packGzipTar(dir, { env, signal }) returning { archivePath, cleanup }, and call it from remote, daemon artifact-tracking and Revyl.

The live evidence in the PR body covers only plain install of a local file, and it has no command output. install-from-source takes a different route (platform-runtime.ts:158: host prepareArtifact, then deployMaterializedApp merging the materialized identity with Revyl's result). reinstall has no proof at all. So the install-from-source and reinstall cells in capabilities.md have no live proof against a real Revyl session. On a Revyl session started without --provider-app, please paste the output of: (1) agent-device install-from-source <https url to a simulator .zip or .apk> --json, showing the returned bundleId or packageName, followed by a successful open <id>; (2) reinstall <id> <path>, followed by evidence that app state was reset, or the typed refusal if you choose to refuse; (3) the connect revyl --platform ios next-steps output.

Not blocking, take or leave: deployApp ignores input.replaceExisting, which the daemon sets for reinstall, and Revyl's uninstallApp is still unavailable, so reinstall is likely an in-place install that keeps app data (either refuse it with a typed UNSUPPORTED_OPERATION reason or show that install_async resets state and say so in revyl.md); the comment above supportsDeferredAppSelection in index.ts says Revyl cannot attach an app to a running device, which this PR makes false; installAndWait could poll install_status with pollUntilSettled and a Deadline from host-kit/retry instead of its own sleep and backoff loop; ARTIFACT_UPLOAD_TIMEOUT_MS repeats REVYL_INSTALL_BUDGET_MS and the scoped signal already carries the budget, so the upload timer can go; and uploadAndInstall could stream the file to fetch instead of reading the whole build into memory.

Four open inline threads still stand: accept a completed install without a result, revyl.md omits reinstall and install-from-source, "zipped or tarred" accepts only .zip, .tar.gz and .tgz, and connect next steps miss install. The Windows PATH thread does not apply, because no CI job here runs on Windows and packing a simulator .app is a macOS-host path, so please resolve it.

Only an external review check has reported for this head. The repo CI lanes, including the Apple-runner lanes named in the PR body, have not reported yet, so I cannot attribute any CI result. I read the code and tests only. I did not run the new tests or reproduce the local gate results in the PR body. No conflicts are known. Before merge, extract the shared packer and paste the live Revyl output above.

`connect revyl` no longer requires --provider-app. Without it, Revyl
starts the device with no app, and `install` puts a local build on it:
the build is uploaded to the session's storage and the worker installs it
through install_async, polled with install_status until it ends. A
simulator .app directory is packed as a gzip tar; a .zip, .tar.gz or .tgz
(iOS) and an .apk (Android) are uploaded as they are. install-from-source
uses the host's materializer and the same upload.

The upload and install share one 420 s budget, inside the install
command's 480 s envelope, so a slow install ends with the plugin's own
error rather than a client timeout that resets the daemon holding the
rented device.
…it, refuse reinstall

The .app packer was a third copy of the one in remote and daemon artifact
tracking. host-kit now owns it as packGzipTar, with the -- guard and an
optional timeout, and all three call it.

The Revyl install polls install_status with pollUntilSettled against a
Deadline, accepts a completed install without a result, and streams the
build to storage with its length declared instead of reading it into
memory. reinstall refuses with UNSUPPORTED_OPERATION: Revyl has no
uninstall, and an install over an app keeps its data.

An app-less connect reports a deferred device and a missing app, so its
next steps run install before open.
@KayaanT
KayaanT force-pushed the feat/revyl-deferred-app branch from 6231cea to 8716f86 Compare November 16, 2026 18:06
@thymikee

Copy link
Copy Markdown
Member

This PR is ready at 8716f86. The earlier findings (#4496 (comment)) are now fixed: the shared packer, the reinstall refusal, connect next steps, and the install-from-source docs are in place, and the live Revyl output for install-from-source, reinstall and connect matches. All 19 checks pass at this commit, there are no conflicts, and nothing else must happen before merge.

Not blocking, take or leave: the install budget in packages/provider-revyl/src/deployment.ts is armed twice (a Deadline and AbortSignal.timeout), both ending in the same timeout error, so deriving one from the other would drop the extra undefined return; and the reinstall refusal in packages/provider-revyl/src/platform-runtime.ts runs inside deployApp after the ref frame is expired, so a refused reinstall expires refs although nothing was deployed, which would need the deploy fact to declare reinstall unavailable so the daemon can refuse earlier.

Of the earlier inline threads, four are fixed at this head and can be resolved: install completed without a result (#4496 (comment)), Revyl docs on install and reinstall (#4496 (comment)), archive extension list (#4496 (comment)), and connect showing install before open (#4496 (comment)). One does not apply and can be resolved: no CI job runs on Windows and packing a simulator .app is a macOS-host path (#4496 (comment)).

Live iOS evidence at this head is the connect output only. The iOS .app install was shown live only at the earlier head with the old packer (same tar arguments plus --), and iOS install-from-source has no live run; the Android run covers the earlier ask.

@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 a30accf into callstack:main Nov 16, 2026
19 checks passed
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.

2 participants