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
7 changes: 7 additions & 0 deletions .changeset/optional-maestro-engine.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'agent-device': minor
---

Release prerequisite: the plugin remains private and unavailable from npm until a usable package is published through the configured release workflow.

Maestro YAML replay, suites, and export now require the optional `@agent-device/maestro` plugin. After publication, install it on each CLI and store-backed daemon host that uses these flows. Finish sessions and stop the matching daemon. Embedded hosts supply the factory through `startAgentDevice({ plugins })` and close/recreate the returned runtime; they do not use the CLI store or daemon stop command. Retry your original command to start a daemon with the updated plugin set; flow syntax and arguments stay the same. Native `.ad` replay remains available without this plugin.
2 changes: 2 additions & 0 deletions .fallowrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@
"packages/maestro/test/packed-clickability.mjs",
"packages/maestro/test/packed-screen-origin.mjs",
"packages/maestro/test/package-test-support.mjs",
"packages/maestro/test/package-smoke.mjs",
"packages/maestro/test/packed-runtime.mjs",
"packages/maestro/tsdown.config.ts",
"packages/maestro/src/plugin.ts",
"packages/provider-testmu/tsdown.config.ts",
Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/android.yml
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ jobs:
if: ${{ !github.event.pull_request.draft }}
runs-on: blacksmith-4vcpu-ubuntu-2404
timeout-minutes: 80
env:
AGENT_DEVICE_HOME: ${{ github.workspace }}/.tmp/agent-device-android-smoke-home
steps:
- name: Checkout
uses: useblacksmith/checkout@2b9fe87d796feea153b455ec2f3125b471a7b0e7 # v1.8.2
Expand Down Expand Up @@ -91,6 +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
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
3 changes: 3 additions & 0 deletions .github/workflows/apple.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ jobs:
runs-on: blacksmith-6vcpu-macos-26
timeout-minutes: 90
env:
AGENT_DEVICE_HOME: ${{ github.workspace }}/.tmp/agent-device-apple-smoke-home
BASE_SHA: ${{ github.event.pull_request.base.sha }}
IOS_STATE_DIR: ${{ github.workspace }}/.tmp/ios-agent-device-state
MACOS_STATE_DIR: ${{ github.workspace }}/.tmp/macos-agent-device-state
Expand Down Expand Up @@ -83,6 +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
- name: iOS smoke tests
id: ios
uses: ./.github/actions/smoke-ios-run
Expand Down
7 changes: 7 additions & 0 deletions .github/workflows/conformance-differential.yml
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,13 @@ 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-maestro-home"
node --experimental-strip-types scripts/install-workspace-maestro.ts
echo "AGENT_DEVICE_HOME=$AGENT_DEVICE_HOME" >> "$GITHUB_ENV"

- name: Restore and build iOS XCTest runner
uses: ./.github/actions/setup-apple-runner-build
with:
Expand Down
7 changes: 7 additions & 0 deletions .github/workflows/replays-nightly.yml
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,13 @@ 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
1 change: 1 addition & 0 deletions docs/adr/0015-direct-maestro-engine.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Accepted

## Rules at a glance

- Load the optional `@agent-device/maestro` engine through the managed version 2 replay-backend plugin contract. Keep help declarations in core. Keep session authority, request cancellation, sensitive-value registration, and device dispatch with the host.
- Parse supported Maestro YAML into a source-preserving typed program. Execute it directly through a narrow compatibility runtime port.
- Do not lower the program through `SessionAction`, private command names, positional JSON, or a recursive replay dispatcher.
- One explicit execution context owns variables and the current observation generation.
Expand Down
2 changes: 2 additions & 0 deletions docs/adr/0034-provider-plugin-registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +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.
- 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 @@ -22,6 +23,7 @@ Status: accepted. Umbrella #3747; contract and registry #3755.
- The registry receives candidates. Composition chooses the sources.
- `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.
- 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
5 changes: 2 additions & 3 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": "tsdown",
"build": "pnpm --filter @agent-device/maestro 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",
"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: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 @@ -317,7 +317,6 @@
"@agent-device/device-selection": "workspace:*",
"@agent-device/host-kit": "workspace:*",
"@agent-device/kernel": "workspace:*",
"@agent-device/maestro": "workspace:*",
"@agent-device/platform-android": "workspace:*",
"@agent-device/platform-apple": "workspace:*",
"@agent-device/platform-harmonyos": "workspace:*",
Expand Down
5 changes: 4 additions & 1 deletion packages/client/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import type { ReplayBackendResolver } from '@agent-device/contracts/replay-backend';
import type { CommandFlags, InternalRequestOptions } from '@agent-device/contracts/command';
import {
readSerializedSnapshotCaptureAnnotations,
Expand Down Expand Up @@ -81,6 +82,8 @@ export function createAgentDeviceClient(
config: AgentDeviceClientConfig = {},
deps: {
transport?: AgentDeviceDaemonTransport;
/** The embedded runtime registry, shared by source preparation and execution. */
resolveReplayBackend?: ReplayBackendResolver;
host?: HostEnvironment;
/** The operator-configured device selector enforced on every request. */
devicePin?: DevicePin;
Expand Down Expand Up @@ -182,7 +185,7 @@ export function createAgentDeviceClient(
command: DaemonCommandName,
options: InternalRequestOptions = {},
): Promise<T> => {
const request = await prepareDaemonCommandRequest(command, options, host);
const request = await prepareDaemonCommandRequest(command, options, host, deps);
return (await execute(
request.command,
request.positionals,
Expand Down
2 changes: 1 addition & 1 deletion packages/command-registry/src/flag-definitions-workflow.ts
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ export const WORKFLOW_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
usageLabel: '--maestro',
usageDescription:
'Replay: treat input as a supported Maestro YAML subset; unsupported syntax fails loudly. ' +
'See agent-device help maestro for commands and boundaries',
'Requires the @agent-device/maestro plugin, install separately. See agent-device help maestro for commands and boundaries',
projectConfig: true,
recorded: false,
},
Expand Down
6 changes: 4 additions & 2 deletions packages/command-surface/src/batch/projection.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import { AppError } from '@agent-device/kernel/errors';
import { request } from '../cli-grammar/common.ts';
import type {
AsyncDaemonWriter,
DaemonWriterDependencies,
CommandInput,
DaemonCommandRequest,
} from '../cli-grammar/types.ts';
Expand All @@ -26,6 +27,7 @@ type PrepareDaemonCommandRequest = (
input: CommandInput,
stepNumber: number,
host: HostEnvironment,
deps?: DaemonWriterDependencies,
) => Promise<DaemonCommandRequest>;

type PrepareBatchStep = (
Expand All @@ -37,11 +39,11 @@ type PrepareBatchStep = (
export function createBatchDaemonWriter(
prepareDaemonCommandRequest: PrepareDaemonCommandRequest,
): AsyncDaemonWriter {
return async (input, host) =>
return async (input, host, deps) =>
request(PUBLIC_COMMANDS.batch, [], {
...input,
batchSteps: await readBatchDaemonSteps(input.steps, (command, input, stepNumber) =>
prepareDaemonCommandRequest(command, input, stepNumber, host),
prepareDaemonCommandRequest(command, input, stepNumber, host, deps),
),
batchOnError: input.onError,
batchMaxSteps: input.maxSteps,
Expand Down
6 changes: 6 additions & 0 deletions packages/command-surface/src/cli-grammar/types.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import type { ReplayBackendResolver } from '@agent-device/contracts/replay-backend';
import type { HostEnvironment } from '@agent-device/kernel/source-value';
import type {
CliFlags,
Expand Down Expand Up @@ -91,6 +92,10 @@ export type CliReader = (positionals: string[], flags: CliFlags) => CliInput;
/** Builds the daemon request for one command. Most writers are pure projections of their input. */
export type DaemonWriter = (input: CommandInput) => DaemonCommandRequest;

export type DaemonWriterDependencies = Readonly<{
resolveReplayBackend?: ReplayBackendResolver;
}>;

/**
* A writer that has caller-side work to do before the request exists: reading the replay script
* files the request carries (#1802), which for a Maestro flow also loads the engine that walks its
Expand All @@ -100,6 +105,7 @@ export type DaemonWriter = (input: CommandInput) => DaemonCommandRequest;
export type AsyncDaemonWriter = (
input: CommandInput,
host: HostEnvironment,
deps?: DaemonWriterDependencies,
) => Promise<DaemonCommandRequest>;

export type AnyDaemonWriter = DaemonWriter | AsyncDaemonWriter;
15 changes: 12 additions & 3 deletions packages/command-surface/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
import type { HostEnvironment } from '@agent-device/kernel/source-value';
import { createBatchDaemonWriter } from './batch/projection.ts';
import type { AnyDaemonWriter, CommandInput, DaemonCommandRequest } from './cli-grammar/types.ts';
import type {
AnyDaemonWriter,
CommandInput,
DaemonCommandRequest,
DaemonWriterDependencies,
} from './cli-grammar/types.ts';
import { findCommandMetadata } from './command-metadata.ts';
import { refuseRetiredCommonInput } from './common-input-fields.ts';
import { readMetadataCommandFlags } from './command-flags.ts';
Expand Down Expand Up @@ -54,6 +59,7 @@ async function prepareBatchDaemonCommandRequest(
input: CommandInput,
stepNumber: number,
host: HostEnvironment,
deps?: DaemonWriterDependencies,
): Promise<DaemonCommandRequest> {
const writer = (daemonWriters as Readonly<Record<string, AnyDaemonWriter>>)[command];
if (!writer) {
Expand All @@ -69,6 +75,7 @@ async function prepareBatchDaemonCommandRequest(
metadata,
metadata.readInput(input) as CommandInput,
host,
deps,
);
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
Expand All @@ -86,23 +93,25 @@ export async function prepareDaemonCommandRequest(
command: DaemonCommandName,
input: CommandInput,
host: HostEnvironment,
deps?: DaemonWriterDependencies,
): Promise<DaemonCommandRequest> {
const writer = daemonWriters[command];
if (!writer) {
throw new Error(`Missing daemon writer for command: ${command}`);
}
refuseRetiredCommonInput(input as Record<string, unknown>);
const metadata = findCommandMetadata(command);
return await prepareRequestWithMetadataFlags(writer, metadata, input, host);
return await prepareRequestWithMetadataFlags(writer, metadata, input, host, deps);
}

async function prepareRequestWithMetadataFlags(
writer: AnyDaemonWriter,
metadata: ReturnType<typeof findCommandMetadata>,
input: CommandInput,
host: HostEnvironment,
deps?: DaemonWriterDependencies,
): Promise<DaemonCommandRequest> {
const request = await writer(input, host);
const request = await writer(input, host, deps);
return {
...request,
...(metadata ? { metadataFlags: readMetadataCommandFlags(metadata, request.options) } : {}),
Expand Down
2 changes: 1 addition & 1 deletion packages/command-surface/src/replay/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ describe('replay command interface', () => {

test('validates -e keys with the grammar of the resolved replay format', async () => {
fs.writeFileSync(path.join(SCRIPT_ROOT, 'flow.yaml'), 'appId: demo.app\n---\n- back\n');
const host = { env: {}, cwd: SCRIPT_ROOT };
const host = { env: { AGENT_DEVICE_HOME: process.env.AGENT_DEVICE_HOME }, cwd: SCRIPT_ROOT };
await expect(
replayDaemonWriter({ path: './checkout.ad', backend: 'maestro', env: ['user=x'] }, host),
).rejects.toMatchObject({ code: 'INVALID_ARGS' });
Expand Down
59 changes: 39 additions & 20 deletions packages/command-surface/src/replay/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,7 @@ export const testCliReader: CliReader = (positionals, flags) => ({
testIme: flags.testIme,
});

export const replayDaemonWriter: AsyncDaemonWriter = async (input, host) => {
export const replayDaemonWriter: AsyncDaemonWriter = async (input, host, deps) => {
const inputPath = requiredDaemonString(input.path, 'replay requires path');
const replayBackend = readReplayBackend(input);
const replayShellEnv = collectReplayClientShellEnv(host.env);
Expand All @@ -259,6 +259,8 @@ export const replayDaemonWriter: AsyncDaemonWriter = async (input, host) => {
// client-collects-local-input move `replayShellEnv` already makes — and
// the daemon executes only what arrives in this bundle.
replayScriptSource: await loadReplayScriptSourceBundle({
hostEnv: host.env,
resolveReplayBackend: deps?.resolveReplayBackend,
inputPath,
cwd: readReplayClientCwd(input, host.cwd),
replayBackend,
Expand All @@ -275,35 +277,52 @@ export const replayDaemonWriter: AsyncDaemonWriter = async (input, host) => {
});
};

export const testDaemonWriter: AsyncDaemonWriter = async (input, host) => {
export const testDaemonWriter: AsyncDaemonWriter = async (input, host, deps) => {
const inputs = input.paths ?? [];
const replayBackend = readReplayBackend(input);
const cwd = readReplayClientCwd(input, host.cwd);
const replayShellEnv = collectReplayClientShellEnv(host.env);
// #1802: `test` inputs belong to the caller, including expansion and source collection.
const sourcePaths = discoverReplaySourcePaths({ inputs, cwd, replayBackend });
const collectSources = async (resolveReplayBackend = deps?.resolveReplayBackend) => {
const sources = [];
for (const inputPath of sourcePaths) {
sources.push(
await loadReplayScriptSourceBundle({
hostEnv: host.env,
resolveReplayBackend,
inputPath,
cwd,
replayBackend,
env: readReplayScriptSourceEnv(
input,
replayShellEnv,
resolveReplayFormat(inputPath, replayBackend),
),
}),
);
}
return sources;
};
const replayScriptSources = sourcePaths.some(
(inputPath) => resolveReplayFormat(inputPath, replayBackend) === 'maestro',
)
? await (
await import('@agent-device/replay-port/replay-backend-registry')
).withReplayBackend(
'maestro',
host.env,
(backend) => collectSources(async () => backend),
deps?.resolveReplayBackend,
)
: await collectSources();
return request(TEST_COMMAND_NAME, inputs, {
...stripReplayTestPresentationInput(input),
replayUpdate: input.update,
replayBackend,
replayEnv: input.env,
replayShellEnv,
// #1802: `test` inputs are paths, directories, and globs on the CALLER's
// filesystem. Expanding them here keeps discovery order identical for a
// local and a remote daemon and ships each discovered source's text.
replayScriptSources: await Promise.all(
discoverReplaySourcePaths({ inputs, cwd, replayBackend }).map(
async (inputPath) =>
await loadReplayScriptSourceBundle({
inputPath,
cwd,
replayBackend,
env: readReplayScriptSourceEnv(
input,
replayShellEnv,
resolveReplayFormat(inputPath, replayBackend),
),
}),
),
),
replayScriptSources,
});
};

Expand Down
1 change: 1 addition & 0 deletions packages/contracts/src/command-flags.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ import {
// wire cannot enforce a shape. This is the typed view of the same field, one rank above the wire
// and below every consumer.

/** Shared replay-compatibility hints; these remain core runtime behavior without the flow engine. */
export type MaestroRuntimeFlags = {
allowNonHittableCoordinateFallback?: boolean;
expectedTapPoint?: Point;
Expand Down
Loading
Loading