Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/optional-native-replay.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
'agent-device': minor
'@agent-device/replay': minor
---

Release prerequisite: the replay plugin remains private and unpublished. Its npm installation command below is unavailable until a usable package is published through the configured release workflow.

Native `.ad` replay and all test suites require the optional `@agent-device/replay` plugin on the daemon host. Run `agent-device plugins add @agent-device/replay`, finish your sessions and restart that daemon, then retry the original invocation with all its arguments. Remote hosts need their own installation. Embedded hosts supply the version 2 factory through `startAgentDevice({ plugins: [replay()] })` and own runtime replacement. Existing scripts, resume and repair syntax stay the same. Ordinary script recording remains in core.
8 changes: 6 additions & 2 deletions .fallowrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,13 @@
"packages/maestro/test/packed-screen-origin.mjs",
"packages/maestro/test/package-test-support.mjs",
"packages/maestro/test/package-smoke.mjs",
"packages/replay/test/package-smoke.mjs",
"packages/replay/test/packed-runtime.mjs",
"packages/maestro/test/packed-runtime.mjs",
"packages/maestro/tsdown.config.ts",
"packages/maestro/src/plugin.ts",
"packages/replay/src/plugin.ts",
"packages/replay/tsdown.config.ts",
"packages/provider-testmu/tsdown.config.ts",
"packages/provider-revyl/test/package-smoke.mjs",
"packages/provider-revyl/tsdown.config.ts",
Expand Down Expand Up @@ -159,7 +163,7 @@
},
{
// A published plugin's default export is its contract; the plugin loader imports the installed package's resolved entry at runtime and reads `default`.
"file": "packages/{provider-*/src/index,maestro/src/plugin}.ts",
"file": "packages/{provider-*/src/index,maestro/src/plugin,replay/src/plugin}.ts",
"exports": ["default"]
},
{
Expand Down Expand Up @@ -289,7 +293,7 @@
},
{
// Tool config default exports, loaded by the tool rather than imported.
"file": "{oxlint.config.ts,tsdown.config.ts,packages/provider-*/tsdown.config.ts,packages/maestro/tsdown.config.ts,packages/proxy/tsdown.config.ts,vitest.mutation.config.ts}",
"file": "{oxlint.config.ts,tsdown.config.ts,packages/provider-*/tsdown.config.ts,packages/maestro/tsdown.config.ts,packages/replay/tsdown.config.ts,packages/proxy/tsdown.config.ts,vitest.mutation.config.ts}",
"exports": ["default"]
},
{
Expand Down
9 changes: 9 additions & 0 deletions .github/actions/run-gate/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,15 @@ outputs:
runs:
using: composite
steps:
- name: Install first-party replay plugins for execution gates
if: contains(fromJSON('["unit", "unit-ci", "provider-integration", "integration-node", "macos-coverage", "web-smoke", "mutation", "fuzz-parsers", "maestro-differential", "replay-ios", "replay-ios-device", "replay-macos", "replay-linux", "replay-android", "linux-command-evidence", "concurrency-torture"]'), inputs.gate)
shell: bash
run: |
set -euo pipefail
pnpm --filter @agent-device/maestro --filter @agent-device/replay build
export AGENT_DEVICE_HOME="${AGENT_DEVICE_HOME:-$RUNNER_TEMP/agent-device-replay-plugins}"
node --experimental-strip-types scripts/install-workspace-replay-plugins.ts
echo "AGENT_DEVICE_HOME=$AGENT_DEVICE_HOME" >> "$GITHUB_ENV"
- id: run
shell: bash
env:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/android.yml
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ jobs:
ANDROID_SERIAL="$(adb devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')"
test -n "$ANDROID_SERIAL"
pnpm gate build
node --experimental-strip-types scripts/install-workspace-maestro.ts
node --experimental-strip-types scripts/install-workspace-replay-plugins.ts
pnpm clean:daemon
AGENT_DEVICE_ANDROID_E2E=1 AGENT_DEVICE_ANDROID_E2E_TIER=smoke AGENT_DEVICE_ANDROID_SERIAL="$ANDROID_SERIAL" AGENT_DEVICE_FIXTURE_APP_PATH="${{ steps.fixture-app.outputs.apk-path }}" AGENT_DEVICE_FIXTURE_APP_ID="${{ steps.fixture-app.outputs.app-id }}" node --experimental-strip-types scripts/node-test-tmpdir.ts --test test/integration/smoke-android-emulator.test.ts
node --experimental-strip-types src/bin.ts test test/integration/replays/android/emulator/01-settings.ad --retries 2 --report-junit test/artifacts/replays-android-smoke.junit.xml
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/apple.yml
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,8 @@ jobs:
uses: ./.github/actions/run-gate
with:
gate: build
- if: steps.build.outcome == 'success'
run: node --experimental-strip-types scripts/install-workspace-maestro.ts
- if: matrix.platform == 'ios' && steps.build.outcome == 'success'
run: node --experimental-strip-types scripts/install-workspace-replay-plugins.ts
Comment thread
thymikee marked this conversation as resolved.
Resolved
- name: iOS smoke tests
id: ios
uses: ./.github/actions/smoke-ios-run
Expand Down
3 changes: 2 additions & 1 deletion .github/workflows/conformance-differential.yml
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,9 @@ jobs:
- name: Build and install the workspace Maestro plugin
run: |
pnpm --filter @agent-device/maestro build
pnpm --filter @agent-device/replay build
export AGENT_DEVICE_HOME="$RUNNER_TEMP/agent-device-maestro-home"
node --experimental-strip-types scripts/install-workspace-maestro.ts
node --experimental-strip-types scripts/install-workspace-replay-plugins.ts
echo "AGENT_DEVICE_HOME=$AGENT_DEVICE_HOME" >> "$GITHUB_ENV"

- name: Restore and build iOS XCTest runner
Expand Down
7 changes: 0 additions & 7 deletions .github/workflows/replays-nightly.yml
Original file line number Diff line number Diff line change
Expand Up @@ -53,13 +53,6 @@ jobs:
- name: Setup toolchain
uses: ./.github/actions/setup-node-pnpm

- name: Build and install the workspace Maestro plugin
run: |
pnpm --filter @agent-device/maestro build
export AGENT_DEVICE_HOME="$RUNNER_TEMP/agent-device-fuzz-home"
node --experimental-strip-types scripts/install-workspace-maestro.ts
echo "AGENT_DEVICE_HOME=$AGENT_DEVICE_HOME" >> "$GITHUB_ENV"

# A lane whose classifier or watchdog regressed would pass forever. This runs the
# broken-on-purpose targets first and fails unless each violation is caught.
- name: Self-check the harness
Expand Down
4 changes: 4 additions & 0 deletions docs/adr/0012-interactive-replay.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ At acceptance, replay had three gaps:

## Decision

### Optional execution boundary (0.22)

Native `.ad` execution and test-suite scheduling require the first-party `@agent-device/replay` version 2 plugin. Maestro suites additionally require `@agent-device/maestro`. The managed registry owns loading, backend claims, failure isolation and disposal. Core keeps session and repair-transaction authority, device dispatch, selectors, refs, recording, cancellation and cleanup. The existing explicit step and suite ports cross the package boundary without a second session store or request context. Shared `.ad` data and divergence wire functions remain in core. This extraction changes installation requirements, not the identity, divergence, resume or repair decisions below. A missing plugin is refused before device binding. A stale daemon requires an explicit host restart, never automatic installation or session termination.

### 1. Retire `--update` healing as an actor; repurpose its candidate machinery as ranked suggestions

`--update`/`-u` does not rewrite `.ad` files.
Expand Down
2 changes: 2 additions & 0 deletions docs/adr/0016-active-session-script-publication.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ Implementation owners are `packages/daemon/src/sessions/handlers/session-script-

## Rules at a glance

Ordinary recording and publication remain core capabilities without the replay plugin. Native `.ad` replay/test execution or replay repair requires `@agent-device/replay` on the daemon host.

This section is a normative summary.
[Decision](#decision) contains the binding contracts and refusal cases.

Expand Down
4 changes: 3 additions & 1 deletion docs/adr/0034-provider-plugin-registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Status: accepted. Umbrella #3747; contract and registry #3755.
- One contract. A provider plugin is a factory that returns `{ apiVersion: 2, provider, credentials,
connection?, setup(host) }`. `setup` returns `{ runtime, platformModule, dispose? }` or
`{ webDriver, dispose? }`. A `{ webDriver }` result stays a data descriptor the host interprets.
- A replay plugin uses the same version 2 factory with `kind: 'replay-backend'`, `backend`, and `setup(host)`. Setup returns `{ replayBackend: { create(host) }, dispose? }`. Provider and backend ids have separate claim sets in this registry. A replay plugin registers no provider runtime.
- A replay plugin uses the same version 2 factory with `kind: 'replay-backend'`, `backend`, and `setup(host)`. Setup returns `{ replayBackend: { create(host) }, dispose? }` for a format backend. Provider and backend ids have separate claim sets in this registry. A replay plugin registers no provider runtime.
- One registry. Composition selects built-in, store, or embedder sources. Built-in providers use the
same shape as an installed plugin, and one function validates what every factory returns.
- Plugins import only types from agent-device. The type-only contract is `agent-device/plugins`;
Expand All @@ -24,6 +24,8 @@ Status: accepted. Umbrella #3747; contract and registry #3755.
- `daemon.json` has one reader. Its states are `absent`, `unreadable`, and `invalid`. A missing or
stale record reads as a stopped daemon; an unreadable or invalid one never does.
- Keep replay setup engine-free. Load the engine only when its backend is selected. The runtime's registry memoizes creation and owns disposal after requests drain. Client-side source collection and export close their scoped registry.
- Engine-free vetted declarations supply help and missing-plugin installation commands. They do not establish whether an engine is installed or working. Unknown names produce no inferred package.
- Missing replay execution returns `plugin-not-installed` before device binding. A selected package retains its load, validation, compatibility or setup reason. A package added after daemon startup returns `daemon-plugin-set-stale`; the caller finishes sessions and restarts that host. An embedded registry never consults the store for recovery.
- The plugin set is fixed for a daemon's lifetime. A plugin change takes effect on the next daemon.
- A store package is discovered through its package targets: the `./agent-device` export, else the
root export, which is `main` for a package that declares no `exports`. Nothing is read from
Expand Down
1 change: 1 addition & 0 deletions examples/sdk/tsconfig.json
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@
{ "path": "../../packages/proxy" },
{ "path": "../../packages/react-native" },
{ "path": "../../packages/remote" },
{ "path": "../../packages/replay" },
{ "path": "../../packages/replay-port" },
{ "path": "../../packages/replay-test" },
{ "path": "../../packages/selectors" },
Expand Down
6 changes: 2 additions & 4 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@
"agent-device": "bin/agent-device.mjs"
},
"scripts": {
"build": "pnpm --filter @agent-device/maestro build && tsdown",
"build": "pnpm --filter @agent-device/maestro build && pnpm --filter @agent-device/replay build && tsdown",
"clean:daemon": "node --experimental-strip-types scripts/clean-daemon.ts",
"daemon:state-dir": "node --experimental-strip-types scripts/print-daemon-state-dir.ts",
"explain:command": "node --experimental-strip-types scripts/explain-command.ts",
Expand Down Expand Up @@ -165,7 +165,7 @@
"depgraph:test": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/depgraph/model.test.ts scripts/depgraph/entries.test.ts scripts/depgraph/import-graph.test.ts scripts/depgraph/affected.test.ts scripts/depgraph/structure-summary.test.ts tools/depgraph-view/*.test.mjs",
"check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",
"check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts",
"check:package": "node --experimental-strip-types scripts/check-package.ts && node --experimental-strip-types scripts/node-test-tmpdir.ts --test packages/maestro/test/package-artifact.test.mjs packages/maestro/test/package-smoke.mjs",
"check:package": "node --experimental-strip-types scripts/check-package.ts && node --experimental-strip-types scripts/node-test-tmpdir.ts --test packages/maestro/test/package-artifact.test.mjs packages/maestro/test/package-smoke.mjs packages/replay/test/package-smoke.mjs",
"check:command-docs": "vitest run --project unit-core test/repo-guards/command-doc-coverage.test.ts",
"check:adr-citations": "vitest run --project unit-core test/repo-guards/adr-citations.test.ts",
"check:capabilities-matrix": "vitest run --project unit-core test/repo-guards/capability-matrix.test.ts",
Expand Down Expand Up @@ -301,7 +301,6 @@
}
},
"devDependencies": {
"@agent-device/ad-replay": "workspace:*",
"@agent-device/ad-script": "workspace:*",
"@agent-device/apple-runner": "workspace:*",
"@agent-device/capture-kit": "workspace:*",
Expand Down Expand Up @@ -331,7 +330,6 @@
"@agent-device/react-native": "workspace:*",
"@agent-device/remote": "workspace:*",
"@agent-device/replay-port": "workspace:*",
"@agent-device/replay-test": "workspace:*",
"@agent-device/selectors": "workspace:*",
"@agent-device/session-journal": "workspace:*",
"@agent-device/test-kit": "workspace:*",
Expand Down
1 change: 1 addition & 0 deletions packages/ad-script/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ export {
} from './internal/vars.ts';

export {
getReplayPluginInstallation,
isMaestroYamlPath,
isReplayBackendId,
maestroBackendRequiredMessage,
Expand Down
20 changes: 20 additions & 0 deletions packages/ad-script/src/internal/format.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,26 @@ import path from 'node:path';

export type ReplayFormat = 'ad' | 'maestro';

const REPLAY_PLUGIN_INSTALLATIONS = {
ad: {
package: '@agent-device/replay',
summary: 'Native .ad replay and test suites',
installationHint:
'Install on the daemon host for native .ad replay and all test suites. Core clients can read and send native .ad sources without this plugin.',
},
maestro: {
package: '@agent-device/maestro',
summary: 'Supported Maestro YAML commands, grammar, and runtime boundaries',
installationHint:
'Install on the client for source collection/export and on the daemon host for Maestro execution.',
},
} as const;

/** Vetted installation facts for the replay format vocabulary, without loading an engine. */
export function getReplayPluginInstallation(id: ReplayFormat) {
return { id, ...REPLAY_PLUGIN_INSTALLATIONS[id] };
}

export function isMaestroYamlPath(sourcePath: string): boolean {
const extension = path.extname(sourcePath).toLowerCase();
return extension === '.yaml' || extension === '.yml';
Expand Down
14 changes: 12 additions & 2 deletions packages/command-surface/src/replay/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ import { METRO_RELOAD_FLAGS, REPLAY_FLAGS } from '@agent-device/command-registry
import { withCommandRuntimeHints } from '../runtime-hints.ts';
import {
collectReplayShellEnv,
getReplayPluginInstallation,
parseReplayCliEnvEntries,
readReplayCliEnvEntries,
resolveReplayFormat,
Expand All @@ -39,6 +40,13 @@ import { discoverReplaySourcePaths } from '@agent-device/replay-port/source-disc
const REPLAY_COMMAND_NAME = 'replay';
const TEST_COMMAND_NAME = 'test';

const replayPluginMcpDetail = (['ad', 'maestro'] as const)
.map((id) => {
const declaration = getReplayPluginInstallation(id);
return `${declaration.summary} (plugin, install separately). ${declaration.installationHint}`;
})
.join(' ');

const REPLAY_SHELL_ENV_PREFIX = 'AD_VAR_';

const replayCommandDescription =
Expand Down Expand Up @@ -330,7 +338,8 @@ export const replayCommandFacet = defineCommandFacet({
name: REPLAY_COMMAND_NAME,
effect: 'destructive',
text: {
summary: 'Replay a recorded session or Maestro flow',
summary: 'Replay a recorded session or Maestro flow (plugin, install separately)',
mcpDetail: replayPluginMcpDetail,
cliDetail:
'Replay has a 60-second work budget inside a 90-second client timeout; --timeout <ms> sets a work budget of X and client timeout of X + 30000 ms. The running step receives ordinary request cancellation at the budget. When it settles, failure returns details.reason daemon_request_timeout and details.timeoutMs, preserving the failing script path and line. The daemon and other sessions stay available if it responds; an authored close may already have ended its session. A completed replay returns success even if it settles just after the deadline. Cancellation does not prove native device work stopped. A step that ignores cancellation beyond the 30-second margin may cause a transport timeout; an unresponsive daemon retains the client liveness-based reset. Direct test keeps its own timeout behavior. For Maestro YAML compatibility flows, use replay <flow.yaml> --maestro and keep the target binding such as --platform ios on the replay command. A script with no terminal close leaves its session (and daemon) running until you close it or it idle-reaps — no different from a session opened interactively. For native .ad scripts, --keep-session suppresses exactly an authored terminal close so you can continue interactively. replay export <file.ad> converts compatible actions to Maestro YAML locally, including app switches with explicit launchApp.appId targets, deep links (including tel: and mailto:) as openLink, and home as pressKey: Home.',
},
Expand All @@ -345,7 +354,8 @@ export const testCommandFacet = defineCommandFacet({
name: TEST_COMMAND_NAME,
effect: 'destructive',
text: {
summary: 'Run replay test suites',
summary: 'Run replay test suites (plugin, install separately)',
mcpDetail: replayPluginMcpDetail,
cliDetail:
"Relative globs are expanded on the caller from its working directory, whose name is treated literally. Quote glob inputs to defer expansion to test. Copied diagnostic artifacts receive numbered filenames when needed to preserve other artifacts, replay sources, timing traces, and attempt manifests. JUnit reports (--reporter junit:<path>) replace characters forbidden by XML 1.0 with U+FFFD and preserve legal Unicode and whitespace. JSON and other reporters retain the original suite values. Custom reporter getExitCode hooks must return an integer from 0 to 255 or undefined; the highest valid code wins and cannot lower a failing suite's exit code. A nested test stops after a bounded resource refusal even with --retries; other failures keep their configured retries.",
},
Expand Down
1 change: 1 addition & 0 deletions packages/contracts/src/replay-backend.ts
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,7 @@ export type ReplayBackendHost = Readonly<{
export type ReplayBackendDeclaration<TId extends string = string> = Readonly<{
id: TId;
package: string;
installationHint: string;
help: Readonly<{ summary: string; body: string }>;
}>;

Expand Down
5 changes: 3 additions & 2 deletions packages/daemon/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@
"@agent-device/platform-apple": "workspace:*",
"@agent-device/platform-web": "workspace:*",
"@agent-device/replay-port": "workspace:*",
"@agent-device/replay-test": "workspace:*",
"@agent-device/selectors": "workspace:*",
"@agent-device/session-journal": "workspace:*"
},
Expand All @@ -31,7 +30,9 @@
"vitest": "5.0.4",
"yaml": "^2.9.0",
"@agent-device/maestro": "workspace:*",
"@agent-device/ad-replay": "workspace:*"
"@agent-device/ad-replay": "workspace:*",
"@agent-device/plugins": "workspace:*",
"@agent-device/replay": "workspace:*"
},
"exports": {
".": {
Expand Down
Loading
Loading