agemu 0.1.0

package/dist/commands/ui.js

@@ -0,0 +1,115 @@
+import { mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CliError } from '../core/errors.js';
+import { redact } from '../core/redact.js';
+import { listDevices, resolveDevice } from '../native/simctl.js';
+import { runProcess } from '../process/run-process.js';
+const bundledRunner = fileURLToPath(new URL('../../runner/AgentRunner.xcodeproj', import.meta.url));
+function validatePlan(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new CliError('UI_VALIDATION_FAILED', 'The UI plan must be an object');
+    const plan = value;
+    if (plan.version !== 1 || !Array.isArray(plan.actions) || plan.actions.length === 0) {
+        throw new CliError('UI_VALIDATION_FAILED', 'The UI plan requires version 1 and at least one action');
+    }
+    return value;
+}
+async function findXctestrun(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const candidate = path.join(directory, entry.name);
+        if (entry.isFile() && entry.name.endsWith('.xctestrun'))
+            return candidate;
+        if (entry.isDirectory()) {
+            const nested = await findXctestrun(candidate);
+            if (nested)
+                return nested;
+        }
+    }
+    return undefined;
+}
+export function injectEnvironment(value, environment) {
+    if (!value || typeof value !== 'object')
+        return 0;
+    let count = 0;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            count += injectEnvironment(item, environment);
+        return count;
+    }
+    const record = value;
+    if (typeof record.TestBundlePath === 'string') {
+        record.EnvironmentVariables = { ...record.EnvironmentVariables, ...environment };
+        count += 1;
+    }
+    for (const child of Object.values(record))
+        count += injectEnvironment(child, environment);
+    return count;
+}
+async function checked(run, executable, args, message) {
+    const result = await run(executable, args);
+    if (result.exitCode !== 0)
+        throw new CliError('UI_DELIVERY_FAILED', message, { exitCode: result.exitCode, stderr: result.stderr });
+    return result;
+}
+export async function buildUiRunner(config, dependencies = {}, rebuild = false) {
+    const run = dependencies.run ?? runProcess;
+    const udid = await (dependencies.resolveUdid?.(config)
+        ?? (config.simulator.udid || listDevices().then(devices => resolveDevice(devices, config.simulator).udid)));
+    const derivedData = path.join(config.root, '.agemu', 'RunnerDerivedData');
+    const project = dependencies.runnerProject ?? bundledRunner;
+    let manifest = rebuild ? undefined : await findXctestrun(derivedData).catch(() => undefined);
+    const cached = Boolean(manifest);
+    if (!manifest) {
+        await checked(run, 'xcodebuild', [
+            '-project', project, '-scheme', 'AgentRunner', '-configuration', 'Debug',
+            '-destination', `platform=iOS Simulator,id=${udid}`, '-derivedDataPath', derivedData, 'build-for-testing',
+        ], 'Unable to build the XCTest UI runner');
+        manifest = await findXctestrun(derivedData);
+    }
+    if (!manifest)
+        throw new CliError('BUILD_FAILED', 'xcodebuild did not produce an .xctestrun file');
+    return { udid, derivedData, manifest, cached };
+}
+export async function runUiPlan(config, planFile, dependencies = {}) {
+    const run = dependencies.run ?? runProcess;
+    let value;
+    try {
+        value = JSON.parse(await readFile(planFile, 'utf8'));
+    }
+    catch (error) {
+        throw new CliError('UI_VALIDATION_FAILED', `Cannot read UI plan: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const plan = validatePlan(value);
+    const built = await buildUiRunner(config, dependencies);
+    const now = dependencies.now?.() ?? new Date();
+    const directory = path.join(config.root, '.agemu', 'runs', now.toISOString().replaceAll(':', '-'));
+    await mkdir(directory, { recursive: true });
+    const json = await checked(run, 'plutil', ['-convert', 'json', '-o', '-', built.manifest], 'Unable to read the XCTest run manifest');
+    const manifestValue = JSON.parse(json.stdout);
+    const encodedPlan = Buffer.from(JSON.stringify({ ...plan, bundleId: config.bundleId }), 'utf8').toString('base64');
+    if (injectEnvironment(manifestValue, { AGEMU_PLAN_BASE64: encodedPlan }) === 0) {
+        throw new CliError('BUILD_FAILED', 'The XCTest run manifest contains no test target');
+    }
+    const manifest = path.join(path.dirname(built.manifest), `AgentRunner-${process.pid}-${Date.now()}.xctestrun`);
+    await writeFile(manifest, JSON.stringify(manifestValue), { mode: 0o600 });
+    await checked(run, 'plutil', ['-convert', 'xml1', manifest], 'Unable to write the XCTest run manifest');
+    const resultBundle = path.join(directory, 'AgentRunner.xcresult');
+    const result = await run('xcodebuild', [
+        'test-without-building', '-xctestrun', manifest, '-destination', `platform=iOS Simulator,id=${built.udid}`,
+        '-resultBundlePath', resultBundle,
+    ]).finally(() => unlink(manifest).catch(() => undefined));
+    const transcript = path.join(directory, 'xcodebuild.log');
+    await writeFile(transcript, redact(`${result.stdout}${result.stderr}`, config.redactions ?? []), { mode: 0o600 });
+    if (result.exitCode !== 0) {
+        throw new CliError('UI_DELIVERY_FAILED', 'The XCTest UI plan failed', {
+            exitCode: result.exitCode, resultBundle: path.relative(config.root, resultBundle), transcript: path.relative(config.root, transcript),
+        });
+    }
+    const marker = result.stdout.split(/\r?\n/).find(line => line.includes('AGEMU_RESULT:'));
+    const runnerResult = marker ? JSON.parse(Buffer.from(marker.slice(marker.indexOf('AGEMU_RESULT:') + 13), 'base64').toString('utf8')) : undefined;
+    return {
+        run: path.relative(config.root, directory), udid: built.udid, bundleId: redact(config.bundleId, config.redactions ?? []),
+        actions: plan.actions.length, runnerResult, resultBundle: path.relative(config.root, resultBundle), transcript: path.relative(config.root, transcript),
+    };
+}

package/dist/config/config.js

@@ -0,0 +1,71 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { CliError } from '../core/errors.js';
+const configKeys = new Set(['version', 'project', 'workspace', 'scheme', 'configuration', 'bundleId', 'simulator', 'redactions']);
+const simulatorKeys = new Set(['udid', 'name', 'runtime']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function validate(value) {
+    if (!isRecord(value))
+        return [{ path: '$', message: 'must be an object' }];
+    const issues = [];
+    for (const key of Object.keys(value))
+        if (!configKeys.has(key))
+            issues.push({ path: key, message: 'is not allowed' });
+    if (value.version !== 1)
+        issues.push({ path: 'version', message: 'must be 1' });
+    const project = value.project;
+    const workspace = value.workspace;
+    if (project !== undefined && (typeof project !== 'string' || !project))
+        issues.push({ path: 'project', message: 'must be a non-empty string' });
+    if (workspace !== undefined && (typeof workspace !== 'string' || !workspace))
+        issues.push({ path: 'workspace', message: 'must be a non-empty string' });
+    if (Number(typeof project === 'string' && project.length > 0) + Number(typeof workspace === 'string' && workspace.length > 0) !== 1) {
+        issues.push({ path: 'project', message: 'exactly one of project or workspace is required' });
+        issues.push({ path: 'workspace', message: 'exactly one of project or workspace is required' });
+    }
+    for (const key of ['scheme', 'configuration', 'bundleId']) {
+        if (typeof value[key] !== 'string' || !value[key])
+            issues.push({ path: key, message: 'must be a non-empty string' });
+    }
+    if (!isRecord(value.simulator)) {
+        issues.push({ path: 'simulator', message: 'must be an object' });
+    }
+    else {
+        for (const key of Object.keys(value.simulator))
+            if (!simulatorKeys.has(key))
+                issues.push({ path: `simulator.${key}`, message: 'is not allowed' });
+        for (const key of ['udid', 'name', 'runtime']) {
+            if (value.simulator[key] !== undefined && (typeof value.simulator[key] !== 'string' || !value.simulator[key])) {
+                issues.push({ path: `simulator.${key}`, message: 'must be a non-empty string' });
+            }
+        }
+        if (typeof value.simulator.udid !== 'string' && typeof value.simulator.name !== 'string') {
+            issues.push({ path: 'simulator', message: 'requires udid or name' });
+        }
+    }
+    if (value.redactions !== undefined && (!Array.isArray(value.redactions) || value.redactions.some((item) => typeof item !== 'string'))) {
+        issues.push({ path: 'redactions', message: 'must be an array of strings' });
+    }
+    return issues;
+}
+export async function loadConfig(root = process.cwd()) {
+    const file = path.join(root, '.agemu.json');
+    let value;
+    try {
+        value = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        throw new CliError('CONFIG_INVALID', `Cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const issues = validate(value);
+    if (issues.length > 0)
+        throw new CliError('CONFIG_INVALID', 'Invalid .agemu.json', { issues });
+    const config = value;
+    return {
+        ...config,
+        ...(config.project ? { project: path.resolve(root, config.project) } : { workspace: path.resolve(root, config.workspace) }),
+        root: path.resolve(root),
+    };
+}

package/dist/core/errors.js

@@ -0,0 +1,10 @@
+export class CliError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'CliError';
+    }
+}

package/dist/core/output.js

@@ -0,0 +1,18 @@
+import { CliError } from './errors.js';
+export function writeResult(result, pretty) {
+    process.stdout.write(`${JSON.stringify(result, null, pretty ? 2 : 0)}\n`);
+}
+export function errorResult(error, debug) {
+    const normalized = error instanceof CliError
+        ? error
+        : new CliError('PROCESS_FAILED', error instanceof Error ? error.message : String(error));
+    return {
+        ok: false,
+        error: {
+            code: normalized.code,
+            message: normalized.message,
+            ...(normalized.details ? { details: normalized.details } : {}),
+            ...(debug && normalized.stack ? { stack: normalized.stack } : {}),
+        },
+    };
+}

package/dist/core/redact.js

@@ -0,0 +1,4 @@
+const replacement = '[REDACTED]';
+export function redact(value, secrets = []) {
+    return secrets.filter(Boolean).reduce((text, secret) => text.replaceAll(secret, replacement), value);
+}

package/dist/doctor/doctor.js

@@ -0,0 +1,91 @@
+import { access, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from '../config/config.js';
+import { listDevices, resolveDevice } from '../native/simctl.js';
+import { runProcess } from '../process/run-process.js';
+const message = (error) => error instanceof Error ? error.message : String(error);
+const passed = (result, fallback) => result.exitCode === 0
+    ? { ok: true, message: 'available' }
+    : { ok: false, message: result.stderr || fallback };
+export async function doctor(dependencies = {}) {
+    const root = dependencies.root ?? process.cwd();
+    const run = dependencies.run ?? runProcess;
+    const readConfig = dependencies.loadConfig ?? loadConfig;
+    const devices = dependencies.listDevices ?? listDevices;
+    const selectDevice = dependencies.resolveDevice ?? resolveDevice;
+    const canWrite = dependencies.canWrite ?? (async (directory) => {
+        const stateDirectory = path.join(directory, '.agemu');
+        try {
+            const metadata = await stat(stateDirectory);
+            if (!metadata.isDirectory())
+                throw new Error(`${stateDirectory} must be a directory`);
+            await access(stateDirectory, constants.W_OK | constants.X_OK);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            await access(directory, constants.W_OK | constants.X_OK);
+        }
+    });
+    const checks = {};
+    checks.node = Number((dependencies.nodeVersion ?? process.versions.node).split('.')[0]) >= 24
+        ? { ok: true, message: dependencies.nodeVersion ?? process.version }
+        : { ok: false, message: `Node.js ${dependencies.nodeVersion ?? process.version} is below 24` };
+    for (const [name, executable, args] of [
+        ['xcode', 'xcodebuild', ['-version']],
+        ['simctl', 'xcrun', ['simctl', 'help']],
+    ]) {
+        try {
+            checks[name] = passed(await run(executable, [...args]), `${executable} failed`);
+        }
+        catch (error) {
+            checks[name] = { ok: false, message: message(error) };
+        }
+    }
+    let config;
+    try {
+        config = await readConfig(root);
+        checks.config = { ok: true, message: 'valid' };
+    }
+    catch (error) {
+        checks.config = { ok: false, message: message(error) };
+    }
+    if (!config) {
+        for (const name of ['project', 'scheme', 'simulator'])
+            checks[name] = { ok: false, message: 'configuration is unavailable' };
+    }
+    else {
+        const source = config.project ?? config.workspace;
+        try {
+            await access(source, constants.F_OK);
+            checks.project = { ok: true, message: path.relative(root, source) || '.' };
+        }
+        catch (error) {
+            checks.project = { ok: false, message: message(error) };
+        }
+        try {
+            const arguments_ = [config.project ? '-project' : '-workspace', source, '-scheme', config.scheme, '-configuration', config.configuration, '-showBuildSettings'];
+            checks.scheme = passed(await run('xcodebuild', arguments_), `Scheme ${config.scheme} failed validation`);
+        }
+        catch (error) {
+            checks.scheme = { ok: false, message: message(error) };
+        }
+        try {
+            selectDevice(await devices(), config.simulator);
+            checks.simulator = { ok: true, message: 'resolved' };
+        }
+        catch (error) {
+            checks.simulator = { ok: false, message: message(error) };
+        }
+    }
+    try {
+        await canWrite(root);
+        checks.stateDirectory = { ok: true, message: '.agemu/ can be created' };
+    }
+    catch (error) {
+        checks.stateDirectory = { ok: false, message: message(error) };
+    }
+    const ready = Object.values(checks).every((check) => check.ok);
+    return { ready, checks };
+}

package/dist/native/simctl.js

@@ -0,0 +1,104 @@
+import { CliError } from '../core/errors.js';
+import { runProcess } from '../process/run-process.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function runtimeName(identifier) {
+    return identifier.replace(/^com\.apple\.CoreSimulator\.SimRuntime\./, '');
+}
+function isAvailable(device) {
+    return device.isAvailable !== false && !String(device.availability ?? '').toLowerCase().includes('unavailable');
+}
+function normalizedRuntime(value) {
+    return runtimeName(value).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+export function parseDevices(json) {
+    if (!isRecord(json) || !isRecord(json.devices)) {
+        throw new CliError('PROCESS_FAILED', 'simctl returned invalid device JSON');
+    }
+    const devices = [];
+    for (const [runtime, entries] of Object.entries(json.devices)) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const value of entries) {
+            if (!isRecord(value))
+                continue;
+            const device = value;
+            if (typeof device.udid !== 'string' || typeof device.name !== 'string' || typeof device.state !== 'string')
+                continue;
+            devices.push({
+                udid: device.udid,
+                name: device.name,
+                runtime: runtimeName(runtime),
+                state: device.state,
+                isAvailable: isAvailable(device),
+            });
+        }
+    }
+    return devices;
+}
+export async function simctl(args, options) {
+    return runProcess('xcrun', ['simctl', ...args], options);
+}
+function processFailure(args, result) {
+    return new CliError('PROCESS_FAILED', result.stderr.trim() || `simctl ${args[0] ?? 'command'} failed`, {
+        command: ['xcrun', 'simctl', ...args],
+        exitCode: result.exitCode,
+        signal: result.signal,
+    });
+}
+async function runChecked(runner, args, options) {
+    const result = await runner(args, options);
+    if (result.exitCode !== 0)
+        throw processFailure(args, result);
+    return result;
+}
+export async function listDevices(runner = simctl) {
+    const result = await runChecked(runner, ['list', '--json']);
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new CliError('PROCESS_FAILED', 'simctl returned invalid JSON');
+    }
+    return parseDevices(parsed).filter((device) => device.isAvailable && device.runtime.startsWith('iOS-'));
+}
+export function resolveDevice(devices, selector) {
+    const available = devices.filter((device) => device.isAvailable);
+    const matches = selector.udid
+        ? available.filter((device) => device.udid === selector.udid)
+        : available.filter((device) => device.name === selector.name && (!selector.runtime || normalizedRuntime(device.runtime) === normalizedRuntime(selector.runtime)));
+    if (matches.length === 0) {
+        throw new CliError('SIMULATOR_NOT_FOUND', 'Simulator selector matched no available device', { selector });
+    }
+    if (matches.length > 1) {
+        throw new CliError('SIMULATOR_AMBIGUOUS', 'Simulator selector matched multiple devices', {
+            selector,
+            candidates: matches,
+        });
+    }
+    return matches[0];
+}
+async function currentDevice(udid, runner) {
+    return (await listDevices(runner)).find((device) => device.udid === udid);
+}
+export async function bootDevice(device, runner = simctl) {
+    if (device.state !== 'Booted') {
+        const result = await runner(['boot', device.udid]);
+        if (result.exitCode !== 0 && (await currentDevice(device.udid, runner))?.state !== 'Booted') {
+            throw processFailure(['boot', device.udid], result);
+        }
+    }
+    await runChecked(runner, ['bootstatus', device.udid, '-b'], { timeoutMs: 120_000 });
+    return { ...device, state: 'Booted' };
+}
+export async function shutdownDevice(device, runner = simctl) {
+    if (device.state === 'Shutdown')
+        return device;
+    const result = await runner(['shutdown', device.udid]);
+    if (result.exitCode !== 0 && (await currentDevice(device.udid, runner))?.state !== 'Shutdown') {
+        throw processFailure(['shutdown', device.udid], result);
+    }
+    return { ...device, state: 'Shutdown' };
+}

package/dist/native/xcodebuild.js

@@ -0,0 +1,49 @@
+import path from 'node:path';
+export function buildArguments(config, udid, action) {
+    const source = config.workspace
+        ? ['-workspace', config.workspace]
+        : ['-project', config.project];
+    return [
+        ...source,
+        '-scheme', config.scheme,
+        '-configuration', config.configuration,
+        '-destination', `platform=iOS Simulator,id=${udid}`,
+        '-derivedDataPath', path.join(config.root, '.agemu', 'DerivedData'),
+        ...(action === 'build' ? ['build'] : ['-showBuildSettings']),
+    ];
+}
+export function parseBuildProducts(output) {
+    const products = [];
+    let target = '';
+    let settings = {};
+    const add = () => {
+        const directory = settings.TARGET_BUILD_DIR;
+        const wrapper = settings.WRAPPER_NAME;
+        const bundleId = settings.PRODUCT_BUNDLE_IDENTIFIER;
+        const executableName = settings.EXECUTABLE_NAME;
+        if (target && directory && wrapper && bundleId && executableName) {
+            products.push({ target, appPath: path.join(directory, wrapper), bundleId, executableName });
+        }
+        settings = {};
+    };
+    for (const line of output.split(/\r?\n/)) {
+        const heading = line.match(/^Build settings for action .* and target (.+):$/);
+        if (heading) {
+            add();
+            target = heading[1];
+            continue;
+        }
+        const setting = line.match(/^\s+([A-Z0-9_]+)\s*=\s*(.*)$/);
+        if (setting)
+            settings[setting[1]] = setting[2].trim();
+    }
+    add();
+    return products;
+}
+export function selectBuildProduct(output, bundleId) {
+    const matches = parseBuildProducts(output).filter((product) => product.bundleId === bundleId && product.appPath.endsWith('.app'));
+    if (matches.length !== 1) {
+        throw new Error(`Expected one app product for ${bundleId}, found ${matches.length}`);
+    }
+    return matches[0];
+}

package/dist/process/run-process.js

@@ -0,0 +1,62 @@
+import { spawn } from 'node:child_process';
+import { CliError } from '../core/errors.js';
+export function runProcess(executable, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const started = Date.now();
+        const startedAt = new Date(started).toISOString();
+        const child = spawn(executable, args, { cwd: options.cwd, env: options.env, shell: false });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let timer;
+        let killTimer;
+        let termination;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            options.signal?.removeEventListener('abort', abort);
+            fn();
+        };
+        const result = (exitCode, signal) => ({
+            stdout,
+            stderr,
+            exitCode,
+            signal,
+            startedAt,
+            durationMs: Date.now() - started,
+        });
+        const terminate = (error) => {
+            if (termination || settled)
+                return;
+            termination = error;
+            child.kill('SIGTERM');
+            killTimer = setTimeout(() => child.kill('SIGKILL'), 1_000);
+        };
+        const abort = () => terminate(new CliError('PROCESS_TIMEOUT', 'Process cancelled'));
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+        child.once('error', (error) => finish(() => reject(new CliError(error.code === 'ENOENT' ? 'TOOL_NOT_FOUND' : 'PROCESS_FAILED', error.message))));
+        child.once('close', (exitCode, signal) => finish(() => {
+            if (termination) {
+                reject(new CliError(termination.code, termination.message, { ...termination.details, result: result(exitCode, signal) }));
+            }
+            else {
+                resolve(result(exitCode, signal));
+            }
+        }));
+        if (options.signal) {
+            if (options.signal.aborted)
+                abort();
+            else
+                options.signal.addEventListener('abort', abort, { once: true });
+        }
+        if (options.timeoutMs !== undefined) {
+            timer = setTimeout(() => terminate(new CliError('PROCESS_TIMEOUT', `Process timed out after ${options.timeoutMs}ms`)), options.timeoutMs);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "agemu",
+  "version": "0.1.0",
+  "description": "Build, run, inspect, and control iOS apps in Simulator from a JSON-first CLI.",
+  "license": "MIT",
+  "author": "Illia Puzanov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zoilorys/agemu.git"
+  },
+  "homepage": "https://github.com/zoilorys/agemu#readme",
+  "bugs": "https://github.com/zoilorys/agemu/issues",
+  "keywords": ["ios", "simulator", "xcode", "cli", "testing"],
+  "engines": { "node": ">=24" },
+  "packageManager": "pnpm@11.24.0",
+  "files": ["dist", "runner", "README.md", "LICENSE"],
+  "type": "module",
+  "bin": { "agemu": "dist/cli/main.js" },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "pnpm clean && tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json && vitest run",
+    "test:integration:native": "pnpm build && AGEMU_NATIVE=1 vitest run test/integration/native-workflow.test.ts",
+    "prepack": "pnpm build"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  }
+}

package/runner/AgentRunner/AgentRunner.swift

@@ -0,0 +1,82 @@
+import XCTest
+
+final class AgentRunner: XCTestCase {
+    private struct Plan: Decodable { let bundleId: String; let actions: [Action] }
+    private struct Action: Decodable {
+        let launch: Launch?
+        let tap: Target?
+        let type: TypeAction?
+        let wait: WaitAction?
+        let assertVisible: Target?
+        let assertValue: ValueAssertion?
+        let screenshot: Screenshot?
+        let inspect: Empty?
+    }
+    private struct Launch: Decodable { let arguments: [String]?; let environment: [String: String]? }
+    private struct Target: Decodable { let identifier: String?; let label: String?; let x: Double?; let y: Double? }
+    private struct TypeAction: Decodable { let identifier: String?; let label: String?; let text: String }
+    private struct WaitAction: Decodable { let identifier: String?; let label: String?; let timeout: Double? }
+    private struct ValueAssertion: Decodable { let identifier: String?; let label: String?; let value: String }
+    private struct Screenshot: Decodable { let name: String? }
+    private struct Empty: Decodable {}
+    private struct Result: Encodable { let completed: Int; let bundleId: String; let trees: [String] }
+
+    @MainActor
+    func testPlan() throws {
+        let encoded = try XCTUnwrap(ProcessInfo.processInfo.environment["AGEMU_PLAN_BASE64"])
+        let data = try XCTUnwrap(Data(base64Encoded: encoded))
+        let plan = try JSONDecoder().decode(Plan.self, from: data)
+        let app = XCUIApplication(bundleIdentifier: plan.bundleId)
+        var trees: [String] = []
+
+        for (index, action) in plan.actions.enumerated() {
+            if let launch = action.launch {
+                app.launchArguments = launch.arguments ?? []
+                app.launchEnvironment = launch.environment ?? [:]
+                app.launch()
+            } else if let target = action.tap {
+                try tap(target, in: app)
+            } else if let type = action.type {
+                let element = try element(Target(identifier: type.identifier, label: type.label, x: nil, y: nil), in: app)
+                element.tap()
+                element.typeText(type.text)
+            } else if let wait = action.wait {
+                let candidate = try element(Target(identifier: wait.identifier, label: wait.label, x: nil, y: nil), in: app)
+                XCTAssertTrue(candidate.waitForExistence(timeout: wait.timeout ?? 5), "Action \(index): element did not appear")
+            } else if let target = action.assertVisible {
+                XCTAssertTrue(try element(target, in: app).exists, "Action \(index): element is not visible")
+            } else if let assertion = action.assertValue {
+                let candidate = try element(Target(identifier: assertion.identifier, label: assertion.label, x: nil, y: nil), in: app)
+                XCTAssertEqual(candidate.value as? String, assertion.value, "Action \(index): element value does not match")
+            } else if let shot = action.screenshot {
+                let attachment = XCTAttachment(screenshot: XCUIScreen.main.screenshot())
+                attachment.name = shot.name ?? "action-\(index)"
+                attachment.lifetime = .keepAlways
+                add(attachment)
+            } else if action.inspect != nil {
+                trees.append(app.debugDescription)
+            } else {
+                XCTFail("Action \(index) has no supported operation")
+            }
+        }
+
+        let output = try JSONEncoder().encode(Result(completed: plan.actions.count, bundleId: plan.bundleId, trees: trees))
+        print("AGEMU_RESULT:\(output.base64EncodedString())")
+    }
+
+    @MainActor
+    private func element(_ target: Target, in app: XCUIApplication) throws -> XCUIElement {
+        if let identifier = target.identifier { return app.descendants(matching: .any)[identifier] }
+        if let label = target.label { return app.descendants(matching: .any).matching(NSPredicate(format: "label == %@", label)).firstMatch }
+        throw NSError(domain: "AgentRunner", code: 1, userInfo: [NSLocalizedDescriptionKey: "Element target requires identifier or label"])
+    }
+
+    @MainActor
+    private func tap(_ target: Target, in app: XCUIApplication) throws {
+        if let x = target.x, let y = target.y {
+            app.coordinate(withNormalizedOffset: .zero).withOffset(CGVector(dx: x, dy: y)).tap()
+        } else {
+            try element(target, in: app).tap()
+        }
+    }
+}