agent-scenario-loop 0.1.0

package/dist/runner/agent-device-driver.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAgentDeviceGlobalArgs = buildAgentDeviceGlobalArgs;
+exports.createAgentDeviceDriver = createAgentDeviceDriver;
+exports.formatAgentDeviceRawOutput = formatAgentDeviceRawOutput;
+exports.formatAgentDeviceSelector = formatAgentDeviceSelector;
+/**
+ * Adds stable driver metadata to one agent-device command result.
+ *
+ * @param {{action: string, capturePath?: string, rawFileName: string, result: Awaited<ReturnType<AgentDeviceCommandExecutor>>}} options
+ * @returns {AgentDeviceCommandResult}
+ */
+function buildAgentDeviceResult({ action, capturePath, rawFileName, result, }) {
+    return {
+        action,
+        args: result.args,
+        command: result.command,
+        exitCode: result.exitCode,
+        rawFileName,
+        stderr: result.stderr,
+        stdout: result.stdout,
+        ...(capturePath ? { capturePath } : {}),
+    };
+}
+/**
+ * Builds global CLI flags shared by all agent-device driver actions.
+ *
+ * @param {AgentDeviceDriverOptions} options
+ * @returns {string[]}
+ */
+function buildAgentDeviceGlobalArgs(options) {
+    const args = ['--platform', options.platform];
+    if (options.target) {
+        args.push('--target', options.target);
+    }
+    if (options.device) {
+        args.push('--device', options.device);
+    }
+    if (options.udid) {
+        args.push('--udid', options.udid);
+    }
+    if (options.serial) {
+        args.push('--serial', options.serial);
+    }
+    if (options.session) {
+        args.push('--session', options.session);
+    }
+    if (options.extraArgs?.length) {
+        args.push(...options.extraArgs);
+    }
+    if (options.json !== false) {
+        args.push('--json');
+    }
+    return args;
+}
+/**
+ * Formats one portable selector as an agent-device selector expression.
+ *
+ * @param {AgentDeviceSelector} selector
+ * @returns {string}
+ */
+function formatAgentDeviceSelector(selector) {
+    if (selector.match && selector.match !== 'exact') {
+        throw new Error(`agent-device selector match \`${selector.match}\` is not supported yet.`);
+    }
+    const escapedValue = selector.value.replace(/\\/gu, '\\\\').replace(/"/gu, '\\"');
+    if (selector.kind === 'accessibilityId' || selector.kind === 'resourceId' || selector.kind === 'testId') {
+        return `id="${escapedValue}"`;
+    }
+    if (selector.kind === 'accessibilityLabel') {
+        return `label="${escapedValue}"`;
+    }
+    if (selector.kind === 'text') {
+        return `text="${escapedValue}"`;
+    }
+    if (selector.kind === 'xpath') {
+        return `xpath="${escapedValue}"`;
+    }
+    throw new Error(`Unsupported agent-device selector kind \`${selector.kind}\`.`);
+}
+/**
+ * Combines stdout and stderr into the raw evidence text written by callers.
+ *
+ * @param {{stdout: string, stderr: string}} result
+ * @returns {string}
+ */
+function formatAgentDeviceRawOutput(result) {
+    return [result.stdout, result.stderr].filter(Boolean).join('\n');
+}
+/**
+ * Creates an agent-device-backed driver for portable mobile actions.
+ *
+ * The adapter shells out through an injected executor so consumers can choose
+ * local, remote, or test doubles without making agent-device a package dependency.
+ *
+ * @param {AgentDeviceDriverOptions} options
+ * @returns {AgentDeviceDriver}
+ */
+function createAgentDeviceDriver(options) {
+    const globalArgs = buildAgentDeviceGlobalArgs(options);
+    const run = async (action, rawFileName, commandArgs, capturePath) => {
+        const result = await options.executor(options.agentDevicePath, [...commandArgs, ...globalArgs]);
+        return buildAgentDeviceResult({
+            action,
+            rawFileName,
+            result,
+            ...(capturePath ? { capturePath } : {}),
+        });
+    };
+    return {
+        async alert({ action = 'get', rawFileName = 'agent-device-alert.txt', timeoutMs, } = {}) {
+            const args = ['alert', action];
+            if (typeof timeoutMs === 'number' && Number.isFinite(timeoutMs)) {
+                args.push(String(timeoutMs));
+            }
+            return run('alert', rawFileName, args);
+        },
+        async assertVisible({ rawFileName = 'agent-device-assert-visible.txt', selector, }) {
+            return run('assertVisible', rawFileName, ['is', 'visible', formatAgentDeviceSelector(selector)]);
+        },
+        async close(app) {
+            return run('close', 'agent-device-close.txt', ['close', app]);
+        },
+        async inspectTree({ interactive = true, rawFileName = 'agent-device-snapshot.txt', } = {}) {
+            return run('inspectTree', rawFileName, ['snapshot', ...(interactive ? ['-i'] : [])]);
+        },
+        async open({ appOrUrl, rawFileName = 'agent-device-open.txt', url, }) {
+            return run('open', rawFileName, ['open', appOrUrl, ...(url ? [url] : [])]);
+        },
+        async readLogs({ rawFileName = 'agent-device-logs.txt', } = {}) {
+            return run('readLogs', rawFileName, ['logs', 'path']);
+        },
+        async screenshot({ outputPath, rawFileName = 'agent-device-screenshot.txt', }) {
+            return run('screenshot', rawFileName, ['screenshot', outputPath], outputPath);
+        },
+        async scroll({ amount, direction = 'down', durationMs, endX, endY, pixels, rawFileName = 'agent-device-scroll.txt', startX, startY, } = {}) {
+            const hasCoordinates = [startX, startY, endX, endY].every((value) => typeof value === 'number');
+            if (hasCoordinates) {
+                return run('scroll', rawFileName, [
+                    'swipe',
+                    String(startX),
+                    String(startY),
+                    String(endX),
+                    String(endY),
+                    ...(typeof durationMs === 'number' ? [String(durationMs)] : []),
+                ]);
+            }
+            return run('scroll', rawFileName, [
+                'scroll',
+                direction,
+                ...(amount ? [amount] : []),
+                ...(typeof pixels === 'number' ? ['--pixels', String(pixels)] : []),
+            ]);
+        },
+        async tap({ rawFileName = 'agent-device-tap.txt', ref, selector, x, y, }) {
+            if (selector) {
+                return run('tap', rawFileName, ['click', formatAgentDeviceSelector(selector)]);
+            }
+            if (ref) {
+                return run('tap', rawFileName, ['click', ref.startsWith('@') ? ref : `@${ref}`]);
+            }
+            if (typeof x === 'number' && typeof y === 'number') {
+                return run('tap', rawFileName, ['click', String(x), String(y)]);
+            }
+            throw new Error('agent-device tap requires a selector, ref, or x/y coordinates.');
+        },
+    };
+}

package/dist/runner/agent-device.d.ts

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+type CliArgs = {
+    app?: string | boolean;
+    'agent-device'?: string | boolean;
+    check?: string | boolean;
+    'command-timeout-ms'?: string | boolean;
+    device?: string | boolean;
+    open?: string | boolean;
+    out?: string | boolean;
+    platform?: string | boolean;
+    'require-platforms'?: string | boolean;
+    'run-id'?: string | boolean;
+    scenario?: string | boolean;
+    serial?: string | boolean;
+    session?: string | boolean;
+    'session-mode'?: string | boolean;
+    target?: string | boolean;
+    udid?: string | boolean;
+    'wait-ms'?: string | boolean;
+    [key: string]: string | boolean | undefined;
+};
+type CommandResult = {
+    args: string[];
+    command: string;
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+};
+type CommandExecutor = (command: string, args: string[]) => Promise<CommandResult>;
+type ScenarioExecutionStep = import('../core/execution-plan').ScenarioExecutionStep;
+type AgentDeviceSessionMode = 'bind' | 'reuse';
+type AgentDeviceAvailabilityOptions = {
+    agentDevicePath?: string;
+    commandTimeoutMs?: number;
+    executor?: CommandExecutor;
+    requiredCommands?: string[];
+    requiredPlatforms?: import('./agent-device-driver').AgentDevicePlatform[];
+};
+type AgentDeviceAvailabilityCheck = {
+    args: string[];
+    code: string;
+    command: string;
+    exitCode: number;
+    metadata?: Record<string, string | number | boolean | null>;
+    message: string;
+    name: string;
+    stderrPreview?: string;
+    status: 'failed' | 'passed';
+    stdoutPreview?: string;
+};
+type AgentDeviceAvailabilityResult = {
+    agentDevicePath: string;
+    checks: AgentDeviceAvailabilityCheck[];
+    devices: Array<Record<string, unknown>>;
+    requiredCommands: string[];
+    requiredPlatforms: string[];
+    sessions: Array<Record<string, unknown>>;
+    status: 'failed' | 'passed';
+};
+type AgentDeviceAvailabilityArtifactOptions = {
+    outputDir: string;
+    result: AgentDeviceAvailabilityResult;
+    runId?: string;
+};
+type AgentDeviceDriverStep = {
+    amount?: string;
+    captureFileName?: string;
+    direction?: string;
+    driverAction: 'assertVisible' | 'inspectTree' | 'readLogs' | 'screenshot' | 'scroll' | 'tap';
+    durationMs?: number;
+    endX?: number;
+    endY?: number;
+    pixels?: number;
+    rawFileName?: string;
+    ref?: string;
+    required?: boolean;
+    selector?: import('./agent-device-driver').AgentDeviceSelector;
+    stepId?: string;
+    startX?: number;
+    startY?: number;
+    waitMs?: number;
+    x?: number;
+    y?: number;
+};
+type AgentDeviceCaptureOptions = {
+    agentDevicePath?: string;
+    app?: string | null;
+    commandTimeoutMs?: number;
+    delay?: (ms: number) => Promise<void>;
+    device?: string | null;
+    driverSteps?: AgentDeviceDriverStep[];
+    executor?: CommandExecutor;
+    open?: boolean;
+    outputDir?: string;
+    platform: import('./agent-device-driver').AgentDevicePlatform;
+    runId?: string;
+    scenario?: Record<string, unknown> | null;
+    serial?: string | null;
+    session?: string | null;
+    sessionMode?: AgentDeviceSessionMode;
+    target?: 'desktop' | 'mobile' | 'tv';
+    udid?: string | null;
+    waitMs?: number;
+};
+type AgentDeviceCaptureResult = {
+    agentSummary: string;
+    captures: {
+        screenshots: string[];
+    };
+    health: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    raw: Record<string, string>;
+    runDir: string;
+    verdict: Record<string, unknown>;
+};
+/**
+ * Prints CLI usage.
+ *
+ * @returns {void}
+ */
+declare function usage(output?: {
+    write: (message: string) => unknown;
+}): void;
+/**
+ * Parses `--key value` CLI arguments.
+ *
+ * @param {string[]} argv
+ * @returns {CliArgs}
+ */
+declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * Runs a command and captures stdout, stderr, and exit code without throwing.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {Promise<CommandResult>}
+ */
+declare function execFileCommand(command: string, args: string[]): Promise<CommandResult>;
+/**
+ * Runs a command with a bounded timeout and captures stdout, stderr, and exit code without throwing.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @param {number} [timeoutMs]
+ * @returns {Promise<CommandResult>}
+ */
+declare function execFileCommandWithTimeout(command: string, args: string[], timeoutMs?: number): Promise<CommandResult>;
+/**
+ * Parses a comma-separated platform requirement list for availability checks.
+ *
+ * @param {unknown} value
+ * @returns {import('./agent-device-driver').AgentDevicePlatform[]}
+ */
+declare function parseRequiredPlatforms(value: unknown): import('./agent-device-driver').AgentDevicePlatform[];
+/**
+ * Parses how a named agent-device session should participate in target selection.
+ *
+ * @param {unknown} value
+ * @returns {AgentDeviceSessionMode}
+ */
+declare function parseAgentDeviceSessionMode(value: unknown): AgentDeviceSessionMode;
+/**
+ * Parses agent-device active session JSON.
+ *
+ * @param {CommandResult} result
+ * @returns {Array<Record<string, unknown>>}
+ */
+declare function readAgentDeviceSessions(result: CommandResult): Array<Record<string, unknown>>;
+/**
+ * Verifies that the configured agent-device command exposes ASL-required surfaces.
+ *
+ * @param {AgentDeviceAvailabilityOptions} options
+ * @returns {Promise<AgentDeviceAvailabilityResult>}
+ */
+declare function checkAgentDeviceAvailability({ agentDevicePath, commandTimeoutMs, executor, requiredCommands, requiredPlatforms, }?: AgentDeviceAvailabilityOptions): Promise<AgentDeviceAvailabilityResult>;
+/**
+ * Builds a health artifact from agent-device capture checks.
+ *
+ * @param {{runId: string, checks: Record<string, unknown>[]}} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildAgentDeviceHealth({ runId, checks }: {
+    runId: string;
+    checks: Record<string, unknown>[];
+}): Record<string, unknown>;
+/**
+ * Builds a verdict artifact for agent-device capture readiness.
+ *
+ * @param {{runId: string, health: Record<string, unknown>}} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildAgentDeviceVerdict({ runId, health }: {
+    runId: string;
+    health: Record<string, unknown>;
+}): Record<string, unknown>;
+/**
+ * Writes ASL artifacts for an agent-device command-surface availability check.
+ *
+ * @param {AgentDeviceAvailabilityArtifactOptions} options
+ * @returns {Promise<{agentSummary: string, health: Record<string, unknown>, runDir: string, verdict: Record<string, unknown>}>}
+ */
+declare function writeAgentDeviceAvailabilityArtifacts({ outputDir, result, runId, }: AgentDeviceAvailabilityArtifactOptions): Promise<{
+    agentSummary: string;
+    health: Record<string, unknown>;
+    runDir: string;
+    verdict: Record<string, unknown>;
+}>;
+/**
+ * Reads agent-device adapter metadata from a normalized scenario step.
+ *
+ * @param {ScenarioExecutionStep} step
+ * @returns {Record<string, unknown>}
+ */
+declare function readAgentDeviceStepOptions(step: ScenarioExecutionStep): Record<string, unknown>;
+/**
+ * Returns true when a normalized step has a portable selector.
+ *
+ * @param {unknown} value
+ * @returns {value is import('./agent-device-driver').AgentDeviceSelector}
+ */
+declare function isAgentDeviceSelector(value: unknown): value is import('./agent-device-driver').AgentDeviceSelector;
+/**
+ * Returns the default raw file name for one agent-device action.
+ *
+ * @param {{driverAction: AgentDeviceDriverStep['driverAction'], index: number}} options
+ * @returns {string}
+ */
+declare function defaultAgentDeviceRawFileName({ driverAction, index, }: {
+    driverAction: AgentDeviceDriverStep['driverAction'];
+    index: number;
+}): string;
+/**
+ * Returns the default capture file name for one agent-device action.
+ *
+ * @param {{driverAction: AgentDeviceDriverStep['driverAction'], index: number}} options
+ * @returns {string}
+ */
+declare function defaultAgentDeviceCaptureFileName({ driverAction, index, }: {
+    driverAction: AgentDeviceDriverStep['driverAction'];
+    index: number;
+}): string;
+/**
+ * Expands normalized scenario steps into agent-device driver actions.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {AgentDeviceDriverStep[]}
+ */
+declare function resolveAgentDeviceDriverSteps(scenario: Record<string, any>): AgentDeviceDriverStep[];
+/**
+ * Returns profile-time validation errors for agent-device driver steps.
+ *
+ * @param {AgentDeviceDriverStep[]} driverSteps
+ * @returns {string[]}
+ */
+declare function validateAgentDeviceDriverSteps(driverSteps: AgentDeviceDriverStep[]): string[];
+/**
+ * Builds scalar health metadata for one portable selector.
+ *
+ * @param {import('./agent-device-driver').AgentDeviceSelector | undefined} selector
+ * @returns {Record<string, string>}
+ */
+declare function buildAgentDeviceSelectorHealthMetadata(selector?: import('./agent-device-driver').AgentDeviceSelector): Record<string, string>;
+/**
+ * Runs one agent-device driver action.
+ *
+ * @param {{capturesDir: string, driver: import('./agent-device-driver').AgentDeviceDriver, driverStep: AgentDeviceDriverStep}} options
+ * @returns {Promise<import('./agent-device-driver').AgentDeviceCommandResult>}
+ */
+declare function runAgentDeviceDriverStep({ capturesDir, driver, driverStep, }: {
+    capturesDir: string;
+    driver: import('./agent-device-driver').AgentDeviceDriver;
+    driverStep: AgentDeviceDriverStep;
+}): Promise<import('./agent-device-driver').AgentDeviceCommandResult>;
+/**
+ * Builds a stable health code suffix for one agent-device driver action.
+ *
+ * @param {AgentDeviceDriverStep['driverAction']} driverAction
+ * @returns {string}
+ */
+declare function agentDeviceDriverActionCode(driverAction: AgentDeviceDriverStep['driverAction']): string;
+/**
+ * Runs scenario-declared portable actions through agent-device and writes artifacts.
+ *
+ * @param {AgentDeviceCaptureOptions} options
+ * @returns {Promise<AgentDeviceCaptureResult>}
+ */
+declare function runAgentDeviceCapture({ agentDevicePath, app, commandTimeoutMs, delay: wait, device, driverSteps, executor, open, outputDir, platform, runId, scenario, serial, session, sessionMode, target, udid, waitMs, }: AgentDeviceCaptureOptions): Promise<AgentDeviceCaptureResult>;
+/**
+ * Runs the agent-device capture CLI.
+ *
+ * @returns {Promise<void>}
+ */
+declare function main(): Promise<void>;
+export { agentDeviceDriverActionCode, buildAgentDeviceHealth, buildAgentDeviceVerdict, buildAgentDeviceSelectorHealthMetadata, checkAgentDeviceAvailability, defaultAgentDeviceCaptureFileName, defaultAgentDeviceRawFileName, execFileCommand, execFileCommandWithTimeout, isAgentDeviceSelector, main, parseArgs, parseAgentDeviceSessionMode, parseRequiredPlatforms, readAgentDeviceSessions, readAgentDeviceStepOptions, resolveAgentDeviceDriverSteps, runAgentDeviceCapture, runAgentDeviceDriverStep, usage, validateAgentDeviceDriverSteps, writeAgentDeviceAvailabilityArtifacts, };
+export type { AgentDeviceCaptureOptions, AgentDeviceCaptureResult, AgentDeviceDriverStep, AgentDeviceAvailabilityOptions, AgentDeviceAvailabilityResult, AgentDeviceAvailabilityCheck, AgentDeviceSessionMode, CliArgs, CommandExecutor, CommandResult, };