@e2edev/agent-device 0.1.0

package/dist/surface.js

@@ -0,0 +1,485 @@
+/**
+ * The agent-device surface: one simulator or emulator session, driven through
+ * agent-device's typed client, exposed to the runner as the contract's
+ * observe/locate/perform members. It owns the id space (one fresh generation
+ * per observation), the attempt state (artifact directory, screenshot
+ * counter), and every translation between the contract's vocabulary and
+ * agent-device's commands. The runner owns everything else.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { BackendError, } from '@e2edev/e2e/backend';
+import { staleOr, translateError } from './errors.js';
+import { resolveExpression } from './locate.js';
+import { isWithin, projectSnapshot, screenTitle } from './nodes.js';
+import { maskPng } from './png.js';
+import { invalidState, notActionable, raceAbort, readPngSize, sanitizeFilename, screenUrl, swipeWithin, unsupported, withinCleanupBudget, } from './support.js';
+/**
+ * The Apple runner defers a full snapshot after slow accessibility work and
+ * returns a sparse one-node tree. Retrying device-side costs under a second;
+ * returning the sparse tree costs the model a confused turn.
+ */
+const SPARSE_RETRY_BACKOFF_MS = [0, 1_200, 3_000];
+/** Number of parent hops from `entry` up to `ancestor`. */
+function depthBelow(entry, ancestor) {
+    let hops = 0;
+    for (let current = entry.parent; current !== undefined; current = current.parent) {
+        hops += 1;
+        if (current === ancestor)
+            return hops;
+    }
+    return hops;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', done);
+            resolve();
+        }
+        signal.addEventListener('abort', done, { once: true });
+    });
+}
+export class AgentDeviceSurface {
+    options;
+    createClient;
+    client;
+    testIdAttribute = 'data-testid';
+    attempt;
+    generation = new Map();
+    idCounter = 0;
+    appIdentity;
+    /**
+     * Commands still running on the device. agent-device takes no abort
+     * signal, so a cancelled or timed-out call is only abandoned by its
+     * caller; it keeps executing. The next attempt waits for these to settle
+     * before it opens anything, so a ghost tap can never land in a retry.
+     */
+    inflight = new Set();
+    constructor(options, createClient) {
+        this.options = options;
+        this.createClient = createClient;
+    }
+    /** Whether the manifest declares app restart and state clearing. */
+    get managesApp() {
+        return this.options.app !== undefined;
+    }
+    /** Whether an attempt is running on this surface right now. */
+    get attemptRunning() {
+        return this.attempt !== undefined;
+    }
+    /** The live client; INVALID_STATE before init or after dispose. */
+    requireClient() {
+        if (this.client === undefined)
+            throw invalidState('the agent-device backend is not initialized');
+        return this.client;
+    }
+    /**
+     * Runs one agent-device command under an operation budget and translates
+     * its failure. Contributed-fixture methods route through here too, so the
+     * device fixture never carries its own error mapping.
+     */
+    async command(label, run, signal) {
+        const client = this.requireClient();
+        try {
+            const pending = this.track(run(client));
+            return await (signal === undefined ? pending : raceAbort(pending, signal, label));
+        }
+        catch (cause) {
+            throw translateError(cause, label);
+        }
+    }
+    /** Registers one device command as in flight until it settles. */
+    track(pending) {
+        this.inflight.add(pending);
+        pending.then(() => this.inflight.delete(pending), () => this.inflight.delete(pending));
+        return pending;
+    }
+    /**
+     * Waits for every abandoned command to settle, within the caller's
+     * budget. A command that never settles fails the attempt launch instead of
+     * racing it: the launch timeout is the honest bound on a stuck device.
+     */
+    async settleInflight(signal) {
+        while (this.inflight.size > 0) {
+            await raceAbort(Promise.allSettled(this.inflight), signal, 'settling in-flight device commands');
+        }
+    }
+    async init(info) {
+        this.testIdAttribute = info.testIdAttribute;
+        this.client ??= this.createClient(this.options.session ?? `e2e-${info.targetName}`);
+        await this.command('boot', (client) => client.devices.boot({
+            platform: this.options.platform,
+            ...(this.options.device === undefined ? {} : { device: this.options.device }),
+        }), info.signal);
+    }
+    async startAttempt(context) {
+        if (this.attempt !== undefined) {
+            throw invalidState('an attempt is already running on this agent-device backend');
+        }
+        await this.settleInflight(context.signal);
+        this.attempt = { artifactsDir: context.artifactsDir, screenshots: 0 };
+        this.generation = new Map();
+        if (this.options.app === undefined)
+            return;
+        await this.openApp(this.options.app, true, context.signal);
+    }
+    async endAttempt(_context) {
+        this.attempt = undefined;
+        this.generation = new Map();
+    }
+    async dispose(context) {
+        const client = this.client;
+        this.client = undefined;
+        this.attempt = undefined;
+        this.generation = new Map();
+        this.appIdentity = undefined;
+        if (client === undefined)
+            return;
+        await withinCleanupBudget(client.sessions.close().catch(() => undefined), context);
+    }
+    /** Opens an app in the session, remembering its identity for the path anchor. */
+    async openApp(app, relaunch, signal) {
+        const result = await this.command(`open ${app}`, (client) => client.apps.open({
+            app,
+            platform: this.options.platform,
+            ...(this.options.device === undefined ? {} : { device: this.options.device }),
+            ...(relaunch ? { relaunch: true } : {}),
+        }), signal);
+        this.appIdentity = result.appBundleId ?? result.appName ?? app;
+        this.generation = new Map();
+    }
+    async snapshot(operation, interactiveOnly) {
+        let last = {};
+        for (const backoffMs of SPARSE_RETRY_BACKOFF_MS) {
+            if (backoffMs > 0)
+                await sleep(backoffMs, operation.signal);
+            if (operation.signal.aborted)
+                throw new BackendError('CANCELLED', 'snapshot cancelled', { retryable: false });
+            last = (await this.command('snapshot', (client) => client.capture.snapshot({ interactiveOnly }), operation.signal));
+            if (last.appBundleId !== undefined || last.appName !== undefined) {
+                this.appIdentity = last.appBundleId ?? last.appName;
+            }
+            if (last.snapshotQuality?.state !== 'sparse')
+                return last;
+        }
+        return last;
+    }
+    /**
+     * Snapshot for an observation. Without a pinned app, an observation before
+     * anything is open is an empty screen rather than a fault: the model's next
+     * move is the open tool, and failing the step would take that move away.
+     */
+    async snapshotOrEmpty(operation, interactiveOnly) {
+        try {
+            return await this.snapshot(operation, interactiveOnly);
+        }
+        catch (cause) {
+            if (!this.managesApp && cause instanceof BackendError && cause.code === 'INVALID_STATE')
+                return { nodes: [] };
+            throw cause;
+        }
+    }
+    project(raw) {
+        return projectSnapshot(raw.nodes ?? [], {
+            testIdAttribute: this.testIdAttribute,
+            mintId: () => {
+                this.idCounter += 1;
+                return `n${this.idCounter}`;
+            },
+        });
+    }
+    async observe(operation, options) {
+        const raw = await this.snapshotOrEmpty(operation, this.options.snapshot === 'interactive');
+        const projected = this.project(raw);
+        this.generation = new Map(projected.index.map((entry) => [entry.id, entry]));
+        const capture = options?.pixels === true ? await this.capturePixels(operation, projected) : undefined;
+        return {
+            nodes: projected.roots,
+            ...(projected.viewport === undefined ? {} : { viewport: projected.viewport }),
+            ...(capture === undefined ? {} : { pixels: capture.pixels, maskedRegionCount: capture.masked }),
+        };
+    }
+    /**
+     * The located snapshot joins the current generation instead of replacing
+     * it, so an observation's ids stay valid across a `screen` query in the
+     * same step. The whole snapshot joins, not only the matches: a later action
+     * on a match may need its descendants (`controlOf`).
+     */
+    async locate(expression, operation) {
+        const raw = await this.snapshotOrEmpty(operation, false);
+        const projected = this.project(raw);
+        const matches = resolveExpression(expression, projected.index, { testIdAttribute: this.testIdAttribute });
+        for (const entry of projected.index)
+            this.generation.set(entry.id, entry);
+        return matches.map((entry) => entry.node);
+    }
+    resolveRef(ref) {
+        const entry = this.generation.get(ref.id);
+        if (entry === undefined) {
+            throw new BackendError('NODE_STALE', `node ${ref.id} is not part of the newest observation`, { retryable: true });
+        }
+        return entry;
+    }
+    actionTarget(entry) {
+        if (entry.ref === '')
+            throw notActionable(`node ${entry.id} has no agent-device ref to act on`);
+        return { ref: `@${entry.ref}` };
+    }
+    /**
+     * The node a toggle press must land on. UIKit reports a settings row as a
+     * labelled `Switch` spanning the whole row with the real control as an
+     * unlabelled `Switch` child at its trailing edge; a press at the row's
+     * centre hits the label and changes nothing. The innermost same-role
+     * descendant with a ref is the control; a node without one is its own.
+     */
+    controlOf(entry) {
+        const role = entry.node.role;
+        if (role !== 'switch' && role !== 'checkbox')
+            return entry;
+        let control = entry;
+        let depth = 0;
+        for (const candidate of this.generation.values()) {
+            if (candidate.ref === '' || candidate.node.role !== role || !isWithin(candidate, entry))
+                continue;
+            const candidateDepth = depthBelow(candidate, entry);
+            if (candidateDepth > depth) {
+                control = candidate;
+                depth = candidateDepth;
+            }
+        }
+        return control;
+    }
+    async perform(ref, action, operation) {
+        const entry = this.resolveRef(ref);
+        const label = `perform ${action.kind}`;
+        const client = this.requireClient();
+        const run = async () => {
+            switch (action.kind) {
+                // `settle` waits for the UI to go quiet after the input lands, so the
+                // observation that follows describes the screen the action produced,
+                // not a frame of its transition. Best-effort on agent-device's side.
+                case 'tap':
+                    return client.interactions.press({ ...this.actionTarget(this.controlOf(entry)), settle: true });
+                case 'focus':
+                    // A touch surface focuses by tapping, and a tap on anything but an
+                    // editable field activates it; focus is offered for fields only.
+                    if (entry.node.role !== 'textbox') {
+                        throw unsupported(`agent-device can only focus editable fields; node ${entry.id} is ${entry.node.role ?? 'unknown'}`);
+                    }
+                    return client.interactions.press({ ...this.actionTarget(entry), settle: true });
+                case 'doubleTap':
+                    return client.interactions.press({ ...this.actionTarget(entry), doubleTap: true, settle: true });
+                case 'longPress':
+                    return client.interactions.longPress({
+                        ...this.actionTarget(entry),
+                        settle: true,
+                        ...(action.durationMs === undefined ? {} : { durationMs: action.durationMs }),
+                    });
+                case 'hover':
+                    return client.interactions.hover(this.actionTarget(entry));
+                case 'fill':
+                    // oxlint-disable-next-line unicorn/no-array-fill-with-reference-type -- agent-device fill, not Array#fill
+                    return client.interactions.fill({ ...this.actionTarget(entry), text: action.value, settle: true });
+                case 'clear':
+                    // oxlint-disable-next-line unicorn/no-array-fill-with-reference-type -- agent-device fill, not Array#fill
+                    return client.interactions.fill({ ...this.actionTarget(entry), text: '', settle: true });
+                case 'check':
+                case 'uncheck': {
+                    const wanted = action.kind === 'check';
+                    const checked = entry.node.states?.checked;
+                    // A toggle whose state the tree does not expose (Android switches)
+                    // cannot be set, only flipped; flipping blind could undo a correct state.
+                    if (checked === undefined) {
+                        throw unsupported(`agent-device cannot read whether node ${entry.id} is checked; tap it instead`);
+                    }
+                    if (checked === wanted)
+                        return undefined;
+                    return client.interactions.press({ ...this.actionTarget(this.controlOf(entry)), settle: true });
+                }
+                case 'press':
+                    return this.pressKey(client, entry, action.key);
+                case 'swipe': {
+                    const rect = entry.node.rect;
+                    if (rect === undefined)
+                        throw notActionable(`node ${entry.id} has no bounds to swipe within`);
+                    return client.interactions.swipe(swipeWithin(rect, action.direction, action.momentum));
+                }
+                case 'dragTo': {
+                    const destination = this.resolveRef(action.target);
+                    return client.interactions.drag({
+                        source: this.actionTarget(entry).ref,
+                        destination: this.actionTarget(destination).ref,
+                    });
+                }
+                case 'scrollIntoView':
+                case 'selectOption':
+                case 'setInputFiles':
+                    throw unsupported(`agent-device cannot perform "${action.kind}" on a device surface`);
+            }
+        };
+        try {
+            await raceAbort(this.track(run()), operation.signal, label);
+        }
+        catch (cause) {
+            throw staleOr(cause, label);
+        }
+    }
+    /**
+     * Keys on a touch surface: Enter submits through the soft keyboard, a
+     * single character is typed into the focused field; there is no key event
+     * bus to send `Escape` or `Tab` to.
+     */
+    async pressKey(client, entry, key) {
+        if (key === 'Enter' || key === 'Return') {
+            return client.command.keyboard({ action: 'enter' });
+        }
+        if ([...key].length === 1) {
+            if (entry.node.role === 'textbox' && entry.node.states?.focused !== true) {
+                await client.interactions.press({ ...this.actionTarget(entry), settle: true });
+            }
+            return client.interactions.type({ text: key });
+        }
+        throw unsupported(`agent-device cannot press "${key}" on a device surface; only Enter and single characters are supported`);
+    }
+    async swipe(direction, _momentum, operation) {
+        await this.command('swipe', (client) => client.interactions.scroll({ direction }), operation.signal);
+    }
+    async back(operation) {
+        await this.command('back', (client) => client.command.back({ settle: true }), operation.signal);
+    }
+    async restart(operation) {
+        if (this.options.app === undefined)
+            throw unsupported('app.restart needs the backend option `app`');
+        await this.openApp(this.options.app, true, operation.signal);
+    }
+    async clearState(operation) {
+        const app = this.options.app;
+        if (app === undefined)
+            throw unsupported('app.clearState needs the backend option `app`');
+        await this.command('clear app state', (client) => client.settings.update({ setting: 'clear-app-state', state: 'clear', app }), operation.signal);
+        await this.openApp(app, true, operation.signal);
+    }
+    /** The path anchor: `app://<app>/<screen title>`; see `screenUrl`. */
+    async url(operation) {
+        const raw = await this.snapshot(operation, false);
+        const projected = projectSnapshot(raw.nodes ?? [], { testIdAttribute: this.testIdAttribute, mintId: () => 'anchor' });
+        return screenUrl(raw.appBundleId ?? raw.appName ?? this.appIdentity, screenTitle(projected));
+    }
+    /**
+     * A redacted screenshot artifact. The device paints secure fields as dots,
+     * but the last typed character shows in clear, so every secure node's
+     * bounds are painted over before the file is kept. A secure node without
+     * bounds cannot be masked, and an image that cannot be redacted is not
+     * written at all.
+     */
+    async screenshot(label, operation) {
+        const attempt = this.attempt;
+        if (attempt === undefined)
+            throw invalidState('screenshot outside an attempt');
+        const masked = await this.maskedScreenshot(operation.signal);
+        attempt.screenshots += 1;
+        const name = `${String(attempt.screenshots).padStart(3, '0')}-${sanitizeFilename(label ?? 'screenshot')}.png`;
+        const relative = path.join('screenshots', name);
+        mkdirSync(path.join(attempt.artifactsDir, 'screenshots'), { recursive: true });
+        writeFileSync(path.join(attempt.artifactsDir, relative), masked.data);
+        return relative;
+    }
+    /** Redacted screen pixels as a PNG, for the agent's screenshot tool. */
+    async screenshotBytes(signal) {
+        return (await this.maskedScreenshot(signal)).data;
+    }
+    /** Raw device pixels; the caller owns redaction. */
+    async rawScreenshot(signal) {
+        const file = path.join(tmpdir(), `e2e-agent-device-${process.pid}-${Date.now()}.png`);
+        try {
+            const shot = await this.command('screenshot', (client) => client.capture.screenshot({ path: file }), signal);
+            return new Uint8Array(readFileSync(shot.path ?? file));
+        }
+        finally {
+            rmSync(file, { force: true });
+        }
+    }
+    /**
+     * Screenshot with every secure node on the current screen painted over.
+     * Observes first so the regions describe the screen the pixels show;
+     * throws when a secure field cannot be covered, because an image that may
+     * hold a credential must not leave the backend.
+     */
+    async maskedScreenshot(signal) {
+        const operation = {
+            signal: signal ?? new AbortController().signal,
+            timeoutMs: 30_000,
+            runId: '',
+            attemptId: '',
+        };
+        const projected = this.project(await this.snapshotOrEmpty(operation, false));
+        const data = await this.rawScreenshot(signal);
+        const masked = redactSecure(data, projected);
+        if (masked === undefined) {
+            throw new BackendError('BACKEND_FAILURE', 'a secure field on screen could not be masked; screenshot withheld', {
+                retryable: false,
+            });
+        }
+        return masked;
+    }
+    /**
+     * Viewport pixels for an observation. Best-effort: a screenshot that cannot
+     * be produced or redacted costs the observation its image, not the step.
+     */
+    async capturePixels(operation, projected) {
+        let raw;
+        try {
+            raw = await this.rawScreenshot(operation.signal);
+        }
+        catch {
+            return undefined;
+        }
+        const redacted = redactSecure(raw, projected);
+        if (redacted === undefined)
+            return undefined;
+        const size = readPngSize(redacted.data);
+        if (size === undefined)
+            return undefined;
+        const viewport = projected.viewport;
+        const scale = viewport !== undefined && viewport.width > 0 ? size.width / viewport.width : 1;
+        return {
+            pixels: { data: redacted.data, mediaType: 'image/png', width: size.width, height: size.height, scale },
+            masked: redacted.masked,
+        };
+    }
+}
+/**
+ * Paints every secure node's bounds black on a screenshot of the same
+ * screen. Returns the masked bytes and how many regions were covered, or
+ * undefined when a secure node has no bounds or the image format cannot be
+ * edited: the caller then withholds the image rather than ship one it could
+ * not prove redacted. Bounds are in logical points; the image may be at
+ * device scale, so they are scaled by the image-to-viewport ratio.
+ */
+function redactSecure(data, projected) {
+    const secure = projected.index.filter((entry) => entry.node.states?.secure === true);
+    if (secure.length === 0)
+        return { data, masked: 0 };
+    const size = readPngSize(data);
+    if (size === undefined)
+        return undefined;
+    const viewport = projected.viewport;
+    const scale = viewport !== undefined && viewport.width > 0 ? size.width / viewport.width : 1;
+    const rects = [];
+    for (const entry of secure) {
+        const rect = entry.node.rect;
+        if (rect === undefined)
+            return undefined;
+        rects.push({ x: rect.x * scale, y: rect.y * scale, width: rect.width * scale, height: rect.height * scale });
+    }
+    try {
+        return { data: maskPng(data, rects), masked: rects.length };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=surface.js.map

package/dist/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Agent-side tools for device targets. Everything a model plans through
+ * beyond the grammar verbs the backend already unlocks (tap, type, scroll)
+ * lives here: opening another app, a free-form swipe, typing into the focused
+ * field, system alerts, and a look at the pixels when the accessibility tree
+ * is not enough. Each tool is scoped to the platforms of the backends it was
+ * built from, so a mixed suite never offers it on a browser.
+ */
+import { type DefinedTool } from '@e2edev/e2e/agent';
+import { type BackendHandle } from '@e2edev/e2e/backend';
+/**
+ * Builds the tool pack for one or more agent-device backends, keyed the way
+ * `createAgent({ tools })` expects. Pass every device backend a config
+ * declares: tool names are fixed, so two packs cannot be merged, and each
+ * tool is offered only on the platforms those backends drive. A worker runs
+ * one attempt at a time, so at execution the pack dispatches to the surface
+ * whose attempt is running.
+ *
+ * Mutating tools are recorded as replay gaps by the trace cache; a step that
+ * stays within the grammar verbs replays zero-turn, so prefer the backend's
+ * `app` option over `open_app` when a test always starts in the same app.
+ */
+export declare function agentDeviceTools(...backends: readonly [BackendHandle, ...BackendHandle[]]): Readonly<Record<string, DefinedTool>>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAc,KAAK,WAAW,EAAwB,MAAM,mBAAmB,CAAC;AACvF,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAkBvE;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,QAAQ,EAAE,SAAS,CAAC,aAAa,EAAE,GAAG,aAAa,EAAE,CAAC,GACxD,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAkGvC"}

package/dist/tools.js

@@ -0,0 +1,110 @@
+/**
+ * Agent-side tools for device targets. Everything a model plans through
+ * beyond the grammar verbs the backend already unlocks (tap, type, scroll)
+ * lives here: opening another app, a free-form swipe, typing into the focused
+ * field, system alerts, and a look at the pixels when the accessibility tree
+ * is not enough. Each tool is scoped to the platforms of the backends it was
+ * built from, so a mixed suite never offers it on a browser.
+ */
+import { tool } from 'ai';
+import { z } from 'zod';
+import { defineTool } from '@e2edev/e2e/agent';
+import { BackendError } from '@e2edev/e2e/backend';
+import { surfaceOf } from './backend.js';
+function requireSurface(backend) {
+    const surface = surfaceOf(backend);
+    if (surface === undefined) {
+        throw new BackendError('INVALID_STATE', 'agentDeviceTools needs handles returned by agentDevice()', {
+            retryable: false,
+        });
+    }
+    return surface;
+}
+/**
+ * Builds the tool pack for one or more agent-device backends, keyed the way
+ * `createAgent({ tools })` expects. Pass every device backend a config
+ * declares: tool names are fixed, so two packs cannot be merged, and each
+ * tool is offered only on the platforms those backends drive. A worker runs
+ * one attempt at a time, so at execution the pack dispatches to the surface
+ * whose attempt is running.
+ *
+ * Mutating tools are recorded as replay gaps by the trace cache; a step that
+ * stays within the grammar verbs replays zero-turn, so prefer the backend's
+ * `app` option over `open_app` when a test always starts in the same app.
+ */
+export function agentDeviceTools(...backends) {
+    const surfaces = backends.map(requireSurface);
+    const platforms = [...new Set(surfaces.map((surface) => surface.options.platform))];
+    const active = () => {
+        const running = surfaces.filter((surface) => surface.attemptRunning);
+        const [surface] = running;
+        if (surface === undefined || running.length > 1) {
+            throw new BackendError('INVALID_STATE', running.length === 0
+                ? 'no agent-device attempt is running; device tools act inside a test attempt only'
+                : 'several agent-device attempts are running in one worker; tools cannot pick a device', { retryable: false });
+        }
+        return surface;
+    };
+    const annotate = (replay, mutates) => ({
+        replay,
+        mutates,
+        secrets: false,
+        platforms,
+    });
+    const abort = (options) => options.abortSignal;
+    return {
+        open_app: defineTool(tool({
+            description: 'Open an app by bundle id, package, or display name (e.g. "Settings"), bringing it to the foreground. Set relaunch to restart it fresh.',
+            inputSchema: z.object({ app: z.string().min(1), relaunch: z.boolean().optional() }),
+            execute: async ({ app, relaunch }, options) => {
+                await active().openApp(app, relaunch === true, abort(options) ?? new AbortController().signal);
+                return `Opened ${app}.`;
+            },
+        }), annotate('deterministic', true)),
+        swipe: defineTool(tool({
+            description: 'Swipe from one screen point to another in logical pixels, e.g. to reveal a row action (swipe the row far left) or to dismiss a sheet.',
+            inputSchema: z.object({
+                from: z.object({ x: z.number(), y: z.number() }),
+                to: z.object({ x: z.number(), y: z.number() }),
+            }),
+            execute: async ({ from, to }, options) => {
+                await active().command('swipe', (client) => client.interactions.swipe({ from, to }), abort(options));
+                return `Swiped from (${from.x}, ${from.y}) to (${to.x}, ${to.y}).`;
+            },
+        }), annotate('none', true)),
+        type_text: defineTool(tool({
+            description: 'Type text into whatever field currently has keyboard focus, then optionally press Return. Use only when the focused field is missing from the observation (some editors hide it); otherwise use the type verb on a node.',
+            inputSchema: z.object({ text: z.string().min(1), submit: z.boolean().optional() }),
+            execute: async ({ text, submit }, options) => {
+                const surface = active();
+                await surface.command('type', (client) => client.interactions.type({ text }), abort(options));
+                if (submit === true) {
+                    await surface.command('keyboard', (client) => client.command.keyboard({ action: 'enter' }), abort(options));
+                }
+                return submit === true ? `Typed ${JSON.stringify(text)} and pressed Return.` : `Typed ${JSON.stringify(text)}.`;
+            },
+        }), annotate('none', true)),
+        alert: defineTool(tool({
+            description: 'Accept or dismiss a visible system alert or permission prompt.',
+            inputSchema: z.object({ action: z.enum(['accept', 'dismiss']) }),
+            execute: async ({ action }, options) => {
+                await active().command('alert', (client) => client.command.alert({ action }), abort(options));
+                return `Alert ${action}ed.`;
+            },
+        }), annotate('deterministic', true)),
+        screenshot: defineTool(tool({
+            description: 'Look at the actual screen pixels. Use when the observation tree is sparse or contradicts what you expect.',
+            inputSchema: z.object({}),
+            execute: async (_input, options) => {
+                const bytes = await active().screenshotBytes(abort(options));
+                return { png: Buffer.from(bytes).toString('base64') };
+            },
+            // The model gets the image itself, not a file path it cannot open.
+            toModelOutput: ({ output }) => ({
+                type: 'content',
+                value: [{ type: 'file', data: { type: 'data', data: output.png }, mediaType: 'image/png' }],
+            }),
+        }), annotate('none', false)),
+    };
+}
+//# sourceMappingURL=tools.js.map