tapline-host 1.0.0 → 1.1.0

package/dist/tools.js

@@ -6,19 +6,26 @@ import { annotateScreenshot } from "./annotate.js";
 import { agentKind, captionFor, personKind, reasonOf } from "./captions.js";
 import { composeFilmstrip, diffImages } from "./images.js";
 import { alertNotes, describeElement, formatChanges, formatElement, formatLogs, formatOffScreenAfterList, formatTree } from "./format.js";
+import { formatInspect, inspectResultSchema } from "./inspect.js";
+import { AUDIT_TYPES, auditResultSchema, auditTitle, formatAudit } from "./audit.js";
+import { ActionLog, loggedTarget } from "./actionlog.js";
+import { Confirmations } from "./confirm.js";
+import { DEFAULT_POLICY, elementKey, listsFor, matchWord } from "./policy.js";
+import { readScript, refStep, scriptSteps } from "./script.js";
+import { EXPECT_TIMEOUT_S, MAX_STEPS, RUN_TIMEOUT_MS, RUN_TOOLS, describeRunStep, expectFailure, parseError, stepNotes, stepSchema, } from "./run.js";
 import { PAIR_CODE_TTL_MS, forgetLink, pairingLink } from "./pairing.js";
 import { elementSchema, logEntrySchema, screenshotResultSchema, treeResultSchema, } from "./protocol.js";
 import { TaplineError } from "./server.js";
 // ---- input schemas ----------------------------------------------------------
 export const targetSchema = z
     .object({
-    ref: z.string().optional().describe('Element ref from your latest list, e.g. "e12"'),
-    id: z.string().optional().describe("Exact identifier (React Native testID, the iOS accessibility identifier)"),
-    label: z.string().optional().describe("Accessibility label, exact, ignoring case"),
-    text: z.string().optional().describe("Visible text: an exact match first (ignoring case), then a substring"),
-    index: z.number().int().min(0).optional().describe("With id, label or text: pick the Nth match (0-based, reading order)"),
-    x: z.number().optional().describe("X in points; use together with y"),
-    y: z.number().optional().describe("Y in points; use together with x"),
+    ref: z.string().optional().describe('From your latest list, e.g. "e12"'),
+    id: z.string().optional().describe("The testID, exact"),
+    label: z.string().optional().describe("Accessibility label, exact"),
+    text: z.string().optional().describe("Visible text: exact first, then part"),
+    index: z.number().int().min(0).optional().describe("The Nth match of id, label or text (0-based)"),
+    x: z.number().optional().describe("Points, with y"),
+    y: z.number().optional().describe("Points, with x"),
 })
     .strict()
     .superRefine((value, ctx) => {
@@ -40,22 +47,29 @@ export const targetSchema = z
         ctx.addIssue({ code: "custom", message: "index works with id, label or text." });
     }
 });
-const targetField = targetSchema.describe("Which element: exactly one of {ref}, {id}, {label}, {text} or {x, y}; add index to pick among several id, label or text matches. Prefer ref or id from your latest list.");
+const targetField = targetSchema.describe("Exactly one of ref, id, label, text or x and y");
 const lookField = z
     .boolean()
     .optional()
-    .describe("Set false to answer only the first line, with no change list. Call look when you need the screen.");
-const screenshotField = z.boolean().optional().describe("Add a screenshot to the answer (default false)");
+    .describe("false: only the first line; the next answer's changes then cover this action too");
+const screenshotField = z.boolean().optional().describe("Add a screenshot (default false)");
+const dryRunField = z
+    .boolean()
+    .optional()
+    .describe("true: run every check and say what would happen; touch nothing");
+/** `index` written beside `target` rather than in it: agents do that, and it means the same. */
+const indexField = z.number().int().min(0).optional().describe("Same as target.index");
 const forceField = z
     .boolean()
     .optional()
-    .describe("Skip the off-screen, covered, under-the-tab-bar and behind-an-alert checks (never disabled). Default false; prefer scrolling or dismissing what covers it, since a person would have to.");
+    .describe("Skip the reach checks (never disabled), only when you've decided a refusal is wrong");
 export const toolShapes = {
     apps: {},
     open_app: { app: z.string().describe("The app's session id, app id or name, as apps lists them") },
     pair: {
         scheme: z
             .string()
+            .optional()
             .describe('The app\'s URL scheme ("scheme" in app.json or app.config), e.g. "myapp"; for an app running in Expo Go, the address Expo prints, e.g. "exp://192.168.1.20:8081"'),
     },
     look: {
@@ -73,9 +87,17 @@ export const toolShapes = {
             .describe("Draw each actionable element's box and ref (e12) on the screenshot, so whoever views it can name elements by ref"),
     },
     check_layout: {},
-    tap: { target: targetField, force: forceField, look: lookField, screenshot: screenshotField },
+    audit: {
+        types: z
+            .array(z.enum(AUDIT_TYPES))
+            .optional()
+            .describe("Which checks to run (default all): contrast, hit_region, description, dynamic_type, clipped_text, trait, element_detection, overlap, duplicate_id"),
+    },
+    inspect: { target: targetField },
+    tap: { target: targetField, index: indexField, force: forceField, dry_run: dryRunField, look: lookField, screenshot: screenshotField },
     long_press: {
         target: targetField,
+        index: indexField,
         seconds: z
             .number()
             .min(0.1)
@@ -83,15 +105,18 @@ export const toolShapes = {
             .optional()
             .describe("How long to hold (default 1.0). Tapline calls the handler, so it doesn't wait"),
         force: forceField,
+        dry_run: dryRunField,
         look: lookField,
         screenshot: screenshotField,
     },
     type_text: {
         text: z.string().describe("Text to enter"),
         target: targetField.optional().describe("Input to type into; default: the focused input, else the only input on screen (else ambiguous; none at all is not_found)"),
+        index: indexField,
         replace: z.boolean().optional().describe("Replace the current text (default true); false appends"),
         submit: z.boolean().optional().describe("Also submit (like pressing return) after typing (default false)"),
         force: forceField,
+        dry_run: dryRunField,
         look: lookField,
         screenshot: screenshotField,
     },
@@ -105,13 +130,16 @@ export const toolShapes = {
         target: targetField
             .optional()
             .describe('Scroll view to scroll, or an element inside it; default: the largest one on screen. With to: "target", the element to bring onto the screen'),
+        dry_run: dryRunField,
         look: lookField,
         screenshot: screenshotField,
     },
     toggle: {
         target: targetField,
+        index: indexField,
         value: z.boolean().optional().describe("Desired state; omit to flip"),
         force: forceField,
+        dry_run: dryRunField,
         look: lookField,
         screenshot: screenshotField,
     },
@@ -120,13 +148,14 @@ export const toolShapes = {
         look: lookField,
         screenshot: screenshotField,
     },
-    back: { look: lookField, screenshot: screenshotField },
+    back: { dry_run: dryRunField, look: lookField, screenshot: screenshotField },
     swipe: {
         x0: z.number().describe("Where the finger starts, in points from the left"),
         y0: z.number().describe("Where the finger starts, in points from the top"),
         x1: z.number().describe("Where it lifts, in points from the left"),
         y1: z.number().describe("Where it lifts, in points from the top"),
         seconds: z.number().min(0.05).max(5).optional().describe("How long the drag takes (default 0.35)"),
+        dry_run: dryRunField,
         look: lookField,
         screenshot: screenshotField,
     },
@@ -155,13 +184,20 @@ export const toolShapes = {
     },
     viewer: {},
     record: {
+        start: z.boolean().optional().describe("Start recording: every action that succeeds from now on becomes a step"),
+        stop: z.boolean().optional().describe("Stop and save the script (to path, else to the scripts folder under name)"),
+        name: z.string().optional().describe("The script's name: letters, digits, '.', '_' and '-'"),
+        path: z.string().optional().describe("Where stop saves the script file (optional)"),
         action: z
             .enum(["start", "stop", "status", "discard"])
-            .describe("start a recording (needs name), stop and save it, see the status, or discard it"),
-        name: z.string().optional().describe("Script name for start: letters, digits, '.', '_' and '-'"),
+            .optional()
+            .describe("Older form: start, stop, status or discard"),
     },
     replay: {
-        name: z.string().optional().describe("The script to replay; omit to list saved scripts"),
+        name: z.string().optional().describe("A saved script's name; omit name and path to list saved scripts"),
+        path: z.string().optional().describe("A script file to replay (the shared agent-tools-script format)"),
+        look: lookField,
+        screenshot: screenshotField,
     },
     wait_for: {
         text: z.string().optional().describe("Wait until this visible text is on screen (or gone)"),
@@ -178,6 +214,20 @@ export const toolShapes = {
     },
     reload: { look: lookField },
     wait: { seconds: z.number().min(0.1).max(30).describe("How long to wait, 0.1 to 30 seconds"), screenshot: screenshotField },
+    run: {
+        steps: z
+            .array(stepSchema)
+            .min(1)
+            .max(MAX_STEPS)
+            .describe('The steps, in order: each is a tool call as an object, {"tool": "tap", "target": {...}, "expect": {...}}. Tools: tap, long_press, type_text, scroll, toggle, back, swipe, open_url, wait, wait_for, app_command. expect (optional): one of text, id or label, with gone, value and timeout (seconds, default 2).'),
+        trace: z.boolean().optional().describe("Also list each step that ran, one line each"),
+        dry_run: z
+            .boolean()
+            .optional()
+            .describe("Check every step's parameters and resolve step 1 (later steps depend on what it does), then touch nothing"),
+        look: lookField,
+        screenshot: screenshotField,
+    },
 };
 /**
  * Under this many points from its first point, a pointer path is a tap or a hold, not a drag.
@@ -341,6 +391,10 @@ function text(message) {
 function fail(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
+/** The target with an `index` that was written beside it moved inside (its own index wins). */
+function withIndex(target, index) {
+    return index !== undefined && target.index === undefined ? { ...target, index } : target;
+}
 function toWireTarget(target) {
     const withIndex = (t) => target.index !== undefined ? { ...t, index: target.index } : t;
     if (target.ref !== undefined)
@@ -421,12 +475,75 @@ export function describeError(error) {
     }
     return `Error internal: ${error instanceof Error ? error.message : String(error)}`;
 }
+/** Ends a guarded call inside the agent's turn with the policy's answer (nothing was touched). */
+class PolicyStop extends Error {
+    answer;
+    constructor(answer) {
+        super("stopped by the policy");
+        this.answer = answer;
+    }
+}
+/** Adds a note line to the end of an answer's first text block. */
+function appendNote(answer, note) {
+    const [top, ...rest] = answer.content;
+    if (top === undefined || top.type !== "text")
+        return answer;
+    return { ...answer, content: [{ type: "text", text: [top.text.trimEnd(), note].join("\n") }, ...rest] };
+}
+/** An app's dry-run answer (AGENT-TOOLS 1.8 §11.4). */
+const dryRunResultSchema = z.object({
+    element: elementSchema.nullish(),
+    dryRun: z.literal(true),
+    point: z.object({ x: z.number(), y: z.number() }).optional(),
+    value: z.unknown().optional(),
+});
+/** For an app without dry runs: every element on its list the target could mean. */
+function candidatesFor(target, elements) {
+    if (typeof target !== "object" || target === null)
+        return [];
+    const t = target;
+    const lower = (value) => (typeof value === "string" ? value.toLowerCase() : "");
+    const x = t["x"];
+    const y = t["y"];
+    let found;
+    if (typeof t["ref"] === "string")
+        found = elements.filter((e) => e.ref === t["ref"]);
+    else if (typeof t["testID"] === "string")
+        found = elements.filter((e) => e.testID === t["testID"]);
+    else if (typeof t["label"] === "string")
+        found = elements.filter((e) => lower(e.label) === lower(t["label"]));
+    else if (typeof t["text"] === "string") {
+        const want = lower(t["text"]);
+        found = elements.filter((e) => lower(e.text).includes(want) || lower(e.label).includes(want));
+    }
+    else if (typeof x === "number" && typeof y === "number") {
+        found = elements.filter((e) => {
+            const f = e.frame;
+            return f !== null && f !== undefined && x >= f.x && x <= f.x + f.width && y >= f.y && y <= f.y + f.height;
+        });
+    }
+    else
+        found = [];
+    const index = t["index"];
+    const picked = typeof index === "number" ? found[index] : undefined;
+    return picked !== undefined ? [picked] : found;
+}
 // ---- tool handlers ----------------------------------------------------------
 /** The tool handlers behind the MCP server. They only talk to a TaplineHost, so they are easy to test. */
 export class TaplineTools {
     host;
     options;
     reloadWaitMs;
+    /** The action log (§12), when one is configured. */
+    actionLog;
+    /** When the action in flight started, for the log's `ms`. */
+    actionStartedAt;
+    /** Set while `run` runs a step: the log ties the action to its batch. */
+    batch;
+    /** Extra fields for the next log line (a dry run, a confirmed touch). */
+    logExtra;
+    confirmations;
+    policy;
     reloadSettleMs;
     noScreenshot = new Set();
     shotFiles = [];
@@ -452,6 +569,10 @@ export class TaplineTools {
         this.host = host;
         this.options = options;
         this.reloadWaitMs = options.reloadWaitMs ?? 20_000;
+        this.confirmations = options.confirmations ?? new Confirmations();
+        this.policy = options.policy ?? DEFAULT_POLICY;
+        this.actionLog = options.logDir !== undefined ? new ActionLog(options.logDir) : null;
+        this.actionLog?.open();
         this.reloadSettleMs = options.reloadSettleMs ?? 1500;
         // A finger on the phone itself: the app saw a real touch. It can't be queued like viewer input
         // (it has already happened), so it only leaves the note and makes `{ref}` targets stale.
@@ -490,15 +611,17 @@ export class TaplineTools {
             const silent = this.silentDropMessage();
             lines.push(silent !== undefined
                 ? silent
-                : state === "background" || state === "inactive"
-                    ? `${last.session.app.name} disconnected at ${when} after it went to the background (the user switched apps or locked the phone, and iOS paused it). Ask the user to open the app again: it reconnects by itself.`
-                    : `${last.session.app.name} disconnected at ${when} (${last.reason}). If the app is still open, it reconnects by itself.`);
+                : state === "inactive"
+                    ? `${last.session.app.name} disconnected at ${when} after iOS put something in front of it (a system prompt such as a password request, a call, or Control Center). Tapline can't see or answer it: ask the user to deal with it on the phone. The app reconnects by itself.`
+                    : state === "background"
+                        ? `${last.session.app.name} disconnected at ${when} after it went to the background (the user switched apps or locked the phone, and iOS paused it). Ask the user to open the app again: it reconnects by itself.`
+                        : `${last.session.app.name} disconnected at ${when} (${last.reason}). If the app is still open, it reconnects by itself.`);
         }
         return [
             "No app is connected to Tapline.",
             ...lines,
             `This host listens at ${url} on ${name}.`,
-            'To connect a phone, call `pair` with the app\'s URL scheme ("scheme" in app.json, e.g. "myapp") and show the user the QR code. They scan it with the phone\'s camera and tap Connect in the app.',
+            'To connect a phone, call `pair`. A development build loading its code from this computer then asks by itself: the user taps Connect. Other builds: pass the app\'s URL scheme ("scheme" in app.json, e.g. "myapp") and show the user the QR code to scan.',
             "The phone needs to be on the same Wi-Fi as this computer, and the app must be a build with Tapline turned on, open in the foreground.",
             "A phone that paired with this host before reconnects by itself while the app is open; one paired with a host on another port (e.g. before a restart) needs `pair` again. Once it connects, retry.",
         ].join("\n");
@@ -506,6 +629,19 @@ export class TaplineTools {
     // -- pair
     async pair(args) {
         const { url, name } = this.options.connect;
+        // Zero-QR pairing (Tapline 1.1): a development build whose JavaScript comes from this computer finds the
+        // offer itself and asks its person to connect. Open for 10 minutes, one use, local network only.
+        const offer = this.host.openDevOffer(name);
+        this.writeOffer(offer);
+        const devLine = "A development build that loads its JavaScript from this computer (Metro) on the same Wi-Fi asks by itself within a few seconds: the user only taps Connect, no QR code (open for 10 minutes, once).";
+        if (args.scheme === undefined || args.scheme.trim() === "") {
+            return text([
+                `Pairing is open for development builds for 10 minutes (${name}).`,
+                devLine,
+                "Ask the user to open the app on the phone and tap Connect, then call `apps`.",
+                "For a TestFlight or release build, call pair again with the app's URL scheme to get a QR code.",
+            ].join("\n"));
+        }
         let link;
         let forget;
         try {
@@ -540,6 +676,7 @@ export class TaplineTools {
             "",
             `Show the user the QR code (attached).${saved} They scan it with the phone's camera, open the app and tap Connect.`,
             "The phone needs to be on the same Wi-Fi as this computer, and the app must be a build with Tapline turned on.",
+            devLine,
             "Once paired, the app reconnects to this host (this address and port) by itself whenever it is open; call `apps` to check.",
             `To unpair the phone, open ${forget} on it.`,
         ];
@@ -550,6 +687,51 @@ export class TaplineTools {
             ],
         };
     }
+    /** `<offerDir>/<port>.json` (0600): the open offer for the Metro helper. Never fails the pair call. */
+    writeOffer(offer) {
+        const dir = this.options.offerDir;
+        const port = this.host.boundPort();
+        if (dir === undefined || port === undefined)
+            return;
+        try {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            const file = join(dir, `${port}.json`);
+            writeFileSync(file, JSON.stringify({ code: offer.code, name: offer.name, port, until: offer.until }), { mode: 0o600 });
+            this.host.setDevOfferFile(file);
+            const remove = () => {
+                try {
+                    // only our own offer: a newer pair call has written its own
+                    if (existsSync(file) && readFileSync(file, "utf8").includes(offer.code))
+                        rmSync(file, { force: true });
+                }
+                catch {
+                    // gone already
+                }
+            };
+            // Used: the code works once, so Metro stops handing it out at once.
+            const onConnect = () => {
+                if (this.host.currentDevOffer()?.code === offer.code)
+                    return;
+                this.host.off("connect", onConnect);
+                remove();
+            };
+            this.host.on("connect", onConnect);
+            setTimeout(() => {
+                this.host.off("connect", onConnect);
+                try {
+                    // only our own offer: a newer pair call has written its own
+                    if (existsSync(file) && readFileSync(file, "utf8").includes(offer.code))
+                        rmSync(file, { force: true });
+                }
+                catch {
+                    // gone already
+                }
+            }, Math.max(0, offer.until - Date.now())).unref();
+        }
+        catch {
+            // the host's own endpoint still has it
+        }
+    }
     // -- apps
     apps() {
         const sessions = this.host.sessions();
@@ -602,6 +784,218 @@ export class TaplineTools {
         const parts = await this.lookParts(session, args.screenshot ?? true, args.width ?? DEFAULT_SCREENSHOT_WIDTH, false, args.labels === true);
         return { content: parts.content, ...(parts.isError ? { isError: true } : {}) };
     }
+    // -- run (AGENT-TOOLS 1.8 §9): a batch of steps, answered once
+    async run(args) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        const steps = args.steps;
+        for (const [i, step] of steps.entries()) {
+            if (!RUN_TOOLS.includes(step.tool)) {
+                return fail(`Error bad_params: step ${i + 1}: "${step.tool}" can't be a step (steps act; use it on its own call). Steps can be: ${RUN_TOOLS.join(", ")}.`);
+            }
+            const shape = toolShapes[step.tool];
+            const { tool: _tool, expect: _expect, route: _route, ...params } = step;
+            const parsed = z.object(shape).strict().safeParse(params);
+            if (!parsed.success) {
+                return fail(`Error bad_params: step ${i + 1} (${describeRunStep(step)}): ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "params"}: ${issue.message}`).join("; ")}`);
+            }
+        }
+        if (args.dry_run === true)
+            return this.dryRunBatch(steps);
+        const before = this.unlistedActions.get(session.id) ?? 0;
+        const started = Date.now();
+        const batchId = `b${started.toString(36)}`;
+        const notes = [];
+        const trace = [];
+        let ran = 0;
+        let stop = null;
+        for (const [i, step] of steps.entries()) {
+            if (Date.now() - started > RUN_TIMEOUT_MS) {
+                stop = { index: i, code: "timeout", message: `the batch ran longer than ${RUN_TIMEOUT_MS / 1000} s`, rest: [] };
+                break;
+            }
+            const at = Date.now();
+            this.batch = { id: batchId, step: i + 1 };
+            const answer = await this.runStep(step).finally(() => {
+                this.batch = undefined;
+            });
+            const said = answer.content.map((block) => (block.type === "text" ? block.text : "")).join("\n").trim();
+            if (answer.isError === true) {
+                stop = { index: i, ...parseError(said) };
+                break;
+            }
+            notes.push(...stepNotes(said, i + 1));
+            if (step.expect !== undefined) {
+                const missed = await this.expectMissed(step.expect);
+                if (missed !== null) {
+                    stop = { index: i, code: "expect_failed", message: `its action ran, but ${missed}`, rest: [] };
+                    break;
+                }
+            }
+            const route = step.route;
+            if (Array.isArray(route) && route.every((part) => typeof part === "string")) {
+                const now = await this.currentRoute();
+                if (now !== null && now.join(" \u203a ") !== route.join(" \u203a ")) {
+                    stop = { index: i, code: "expect_failed", message: `its action ran, but it ended on ${now.join(" \u203a ")}; the recording ended on ${route.join(" \u203a ")}`, rest: [] };
+                    break;
+                }
+            }
+            ran++;
+            if (args.trace === true)
+                trace.push(`  ${i + 1}. ${said.split("\n")[0] ?? ""} (${((Date.now() - at) / 1000).toFixed(1)} s)`);
+        }
+        // The batch is one call: the changes below are measured from the list the agent had before it.
+        if (before > 0)
+            this.unlistedActions.set(session.id, before);
+        else
+            this.unlistedActions.delete(session.id);
+        const total = steps.length;
+        const failed = stop !== null;
+        const head = stop === null
+            ? `Ran ${total} of ${total} steps in ${((Date.now() - started) / 1000).toFixed(1)} s.`
+            : `Error ${stop.code}: Ran ${ran} of ${total} steps; stopped at step ${stop.index + 1} (${describeRunStep(steps[stop.index])}): ${stop.message}`;
+        const first = [head, ...trace, ...(stop?.rest ?? [])].join("\n");
+        let response;
+        const live = this.host.current();
+        if (args.look === false || live === undefined) {
+            response = text([first, ...notes].join("\n"));
+        }
+        else {
+            response = await this.withLook(live, first, args.screenshot === true);
+            if (notes.length > 0) {
+                const [top, ...rest] = response.content;
+                if (top !== undefined && top.type === "text")
+                    response = { ...response, content: [{ type: "text", text: [top.text.trimEnd(), ...notes].join("\n") }, ...rest] };
+            }
+        }
+        return failed ? { ...response, isError: true } : response;
+    }
+    /** `run` with dry_run (§11.4): the steps are checked already; step 1 is resolved, nothing is touched. */
+    async dryRunBatch(steps) {
+        const total = steps.length;
+        const first = steps[0];
+        const head = `Would run ${total} step${total === 1 ? "" : "s"}`;
+        if (["tap", "long_press", "toggle", "type_text", "scroll", "back", "swipe"].includes(first.tool)) {
+            const answer = await this.runStep({ ...first, dry_run: true });
+            const said = answer.content.map((block) => (block.type === "text" ? block.text : "")).join("\n").trim();
+            const [line, ...rest] = said.split("\n");
+            if (answer.isError === true) {
+                const { code, message } = parseError(said);
+                return fail(`Error ${code}: ${head}; step 1 (${describeRunStep(first)}) would fail: ${message}`);
+            }
+            const would = (line ?? "").replace(/^Would /, "would ");
+            return text([`${head}; step 1 ${would}`, ...rest].join("\n"));
+        }
+        return text(`${head}; step 1 would ${describeRunStep(first)}.`);
+    }
+    /** One step of `run`, as its own tool call without a list. */
+    runStep(step) {
+        const { tool, expect: _expect, route: _route, ...rest } = step;
+        const quiet = { ...rest, look: false, screenshot: false };
+        switch (tool) {
+            case "tap":
+                return this.tap(quiet);
+            case "long_press":
+                return this.longPress(quiet);
+            case "type_text":
+                return this.typeText(quiet);
+            case "scroll":
+                return this.scroll(quiet);
+            case "toggle":
+                return this.toggle(quiet);
+            case "back":
+                return this.back(quiet);
+            case "swipe":
+                return this.swipe(quiet);
+            case "open_url":
+                return this.openUrl(quiet);
+            case "wait":
+                return this.wait({ seconds: Number(rest.seconds ?? 0) });
+            case "wait_for":
+                return this.waitFor(quiet);
+            case "app_command":
+                return this.appCommand(quiet);
+        }
+    }
+    /** The screen's route names now (one cheap read), or null when the app has no router or didn't answer. */
+    async currentRoute() {
+        const session = this.host.current();
+        if (session === undefined)
+            return null;
+        const tree = treeResultSchema.safeParse(await this.host.request("tree", { peek: true }, { sessionId: session.id }).catch(() => null));
+        return tree.success && tree.data.route !== undefined ? tree.data.route.names : null;
+    }
+    /** Null when the expectation holds within its time; else how it failed. */
+    async expectMissed(e) {
+        const seconds = e.timeout ?? EXPECT_TIMEOUT_S;
+        const which = e.text !== undefined ? { text: e.text } : e.id !== undefined ? { id: e.id } : { label: e.label };
+        const seen = await this.waitFor({ ...which, ...(e.gone === true ? { gone: true } : {}), timeout: Math.max(0.5, seconds), look: false });
+        if (seen.isError === true)
+            return expectFailure(e, seconds);
+        if (e.value === undefined || e.gone === true)
+            return null;
+        // The element is there: wait for its value (a switch reads "on" or "off").
+        const session = this.host.current();
+        if (session === undefined)
+            return expectFailure(e, seconds);
+        const until = Date.now() + seconds * 1000;
+        let actual;
+        for (;;) {
+            const tree = treeResultSchema.safeParse(await this.host.request("tree", { peek: true }, { sessionId: session.id }).catch(() => null));
+            const element = tree.success
+                ? tree.data.elements.find((el) => (e.id !== undefined ? el.testID === e.id : (el.label ?? "").toLowerCase() === (e.label ?? "").toLowerCase()))
+                : undefined;
+            if (element !== undefined) {
+                actual = typeof element.checked === "boolean" ? (element.checked ? "on" : "off") : typeof element.value === "string" ? element.value : undefined;
+                // A switch takes "true" and "false" too (it reads checked=true in the list).
+                const wanted = typeof element.checked === "boolean" && (e.value === "true" || e.value === "false") ? (e.value === "true" ? "on" : "off") : e.value;
+                if (actual === wanted)
+                    return null;
+            }
+            if (Date.now() >= until)
+                return expectFailure(e, seconds, actual);
+            await sleep(100);
+        }
+    }
+    // -- inspect (Tapline 1.1): from the screen to the code
+    async inspect(args) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        let raw;
+        try {
+            raw = await this.host.request("inspect", { target: toWireTarget(args.target) }, { sessionId: session.id });
+        }
+        catch (error) {
+            return fail(describeError(error));
+        }
+        const parsed = inspectResultSchema.safeParse(raw);
+        if (!parsed.success)
+            return fail("Error internal: the app returned an inspect answer the host could not read.");
+        return text(formatInspect(parsed.data));
+    }
+    // -- audit (AGENT-TOOLS 1.8 §10)
+    async audit(args = {}) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        if (!session.capabilities.includes("audit")) {
+            return fail("Error unsupported: this app's Tapline is too old for audit; update react-native-tapline (check_layout works meanwhile).");
+        }
+        let raw;
+        try {
+            raw = await this.host.request("audit", args.types !== undefined ? { types: args.types } : {}, { sessionId: session.id });
+        }
+        catch (error) {
+            return fail(describeError(error));
+        }
+        const parsed = auditResultSchema.safeParse(raw);
+        if (!parsed.success)
+            return fail("Error internal: the app returned an audit the host could not read.");
+        const title = auditTitle(await this.currentRoute(), session.app.name);
+        return text([formatAudit(title, parsed.data, args.types), ...this.takePersonNote()].join("\n"));
+    }
     // -- check_layout
     async checkLayout(_args = {}) {
         const session = this.host.current();
@@ -754,32 +1148,42 @@ export class TaplineTools {
     /** Runs a request, then (unless disabled) appends the fresh element list and how long the app took to settle. */
     async act(method, params, describe, withLook, screenshot, extraNotes, 
     /** True when the result means nothing was done: the first line is then the whole answer. */
-    nothingDone) {
+    nothingDone, 
+    /** Runs inside the agent's turn, right before the request: an answer stops the call there (the policy). */
+    preflight) {
         const session = this.host.current();
         if (session === undefined)
             return this.notConnected();
-        if (this.personActed) {
-            const target = typeof params === "object" && params !== null ? params.target : undefined;
-            if (typeof target === "object" && target !== null && "ref" in target) {
-                // The error says it already, so the note isn't repeated.
-                this.personNotePending = false;
-                return fail("Error stale: a person used the app since your last look, so refs from that list may point elsewhere. Look again, or target by id, label or text.");
-            }
-        }
+        const stale = this.staleRef(params);
+        if (stale !== null)
+            return stale;
         let result;
+        this.actionStartedAt = Date.now();
         try {
             const timeoutMs = answerTimeoutMs(method, params);
-            const run = () => this.host.request(method, params, { sessionId: session.id, ...(timeoutMs !== undefined ? { timeoutMs } : {}) });
+            const run = async () => {
+                if (preflight !== undefined) {
+                    const stop = await preflight();
+                    if (stop !== null)
+                        throw new PolicyStop(stop);
+                }
+                return this.host.request(method, params, { sessionId: session.id, ...(timeoutMs !== undefined ? { timeoutMs } : {}) });
+            };
             // With the live viewer, a person watching goes first.
             result = this.options.control ? await this.options.control.runAgent(run) : await run();
         }
         catch (error) {
+            if (error instanceof PolicyStop)
+                return error.answer;
+            this.logExtra = undefined;
             this.showAction("agent", method, undefined, params, error instanceof TaplineError ? error.code : "internal", error instanceof TaplineError ? reasonOf(error.code, error.message) : undefined);
             return fail(describeError(error));
         }
         const line = describe(result);
-        if (nothingDone?.(result) === true)
+        if (nothingDone?.(result) === true) {
+            this.logExtra = undefined;
             return text([line, ...this.takePersonNote()].join("\n"));
+        }
         this.showAction("agent", method, result, params);
         let response;
         this.lastLookRoute = undefined;
@@ -826,8 +1230,14 @@ export class TaplineTools {
             }
         }
         if (this.recording !== null && !this.replaying) {
-            const { params: stable, fragile } = stableParams(params, result);
-            const step = { method, params: stable };
+            const { params: chosen, fragile } = stableParams(params, result);
+            // A ref saved as a label or text that several elements share needs its index (AGENT-TOOLS 1.8 §9.4).
+            const stable = await this.withIndexIfShared(params, chosen, result, session.id);
+            // A password field's text is never saved in a script (Tapwright's review, M4).
+            const secret = method === "type" && typeof result === "object" && result !== null && "secure" in result && result.secure === true;
+            const step = { method, params: secret ? { ...stable, text: "" } : stable };
+            if (secret)
+                step.secret = true;
             if (this.lastLookRoute !== undefined)
                 step.route = this.lastLookRoute;
             if (fragile)
@@ -836,6 +1246,39 @@ export class TaplineTools {
         }
         return response;
     }
+    /**
+     * When the agent's ref was saved as a testID, label or text that more than one element on screen has, add
+     * the element's `index` among them (reading order), so the replay picks the same one instead of
+     * answering `ambiguous`. One extra read, only while recording and only for ref targets.
+     */
+    async withIndexIfShared(original, chosen, result, sessionId) {
+        const before = typeof original === "object" && original !== null ? original.target : undefined;
+        const target = chosen["target"];
+        if (typeof before !== "object" || before === null || !("ref" in before))
+            return chosen;
+        if (typeof target !== "object" || target === null || "ref" in target || "index" in target)
+            return chosen;
+        const element = typeof result === "object" && result !== null && "element" in result
+            ? elementSchema.safeParse(result.element)
+            : null;
+        if (!element?.success)
+            return chosen;
+        const tree = treeResultSchema.safeParse(await this.host.request("tree", { peek: true }, { sessionId }).catch(() => null));
+        if (!tree.success)
+            return chosen;
+        const t = target;
+        const same = tree.data.elements.filter((el) => typeof t.testID === "string"
+            ? el.testID === t.testID
+            : typeof t.label === "string"
+                ? (el.label ?? "").toLowerCase() === t.label.toLowerCase()
+                : typeof t.text === "string"
+                    ? el.text === t.text
+                    : false);
+        if (same.length < 2)
+            return chosen;
+        const at = same.findIndex((el) => el.ref === element.data.ref);
+        return at < 0 ? chosen : { ...chosen, target: { ...target, index: at } };
+    }
     // -- the live viewer
     /** An element's frame (points) as 0..1 of the screen. */
     normalized(frame) {
@@ -859,15 +1302,43 @@ export class TaplineTools {
             ...(point ? { point } : {}),
         };
     }
+    /** One line in the action log (§12). Never fails the action. */
+    logAction(by, tool, params, result, code, reason) {
+        if (this.actionLog === null)
+            return;
+        const element = typeof result === "object" && result !== null && "element" in result
+            ? elementSchema.safeParse(result.element)
+            : null;
+        const session = this.host.current();
+        this.actionLog.write({
+            by,
+            tool,
+            ...loggedTarget(params),
+            // typed text never reaches the log, not even as the field's value (§12)
+            ...(element?.success ? { element: formatElement({ ...element.data, ref: "", value: null, placeholder: null }, { actions: false }) } : {}),
+            ok: code === undefined,
+            ...(code !== undefined ? { code } : {}),
+            ...(reason !== undefined ? { reason } : {}),
+            ...(by === "agent" && this.actionStartedAt !== undefined ? { ms: Date.now() - this.actionStartedAt } : {}),
+            ...(session !== undefined ? { app: session.app.id ?? session.app.name } : {}),
+            ...(by === "agent" && this.batch !== undefined ? { batch: this.batch } : {}),
+            ...(by === "agent" ? (this.logExtra ?? {}) : {}),
+        });
+        if (by === "agent")
+            this.logExtra = undefined;
+    }
     showAction(by, method, result, params, code, reason) {
         const onAction = this.options.onAction;
-        if (onAction === undefined)
+        if (onAction === undefined) {
+            this.logAction(by, by === "agent" ? agentKind(method) : method, params, result, code, reason);
             return;
+        }
         const target = typeof params === "object" && params !== null ? params.target : undefined;
         const t = typeof target === "object" && target !== null ? target : undefined;
         const screen = this.lastScreen;
         const point = t && typeof t.x === "number" && typeof t.y === "number" && screen ? { x: t.x / screen.w, y: t.y / screen.h } : undefined;
         const kind = by === "agent" ? agentKind(method) : method;
+        this.logAction(by, kind, params, result, code, reason);
         const described = this.describeAction(kind, result, point);
         // A failed step has no element in its answer: name it from the target the agent gave, if it's words.
         const named = described.label ??
@@ -968,7 +1439,10 @@ export class TaplineTools {
             }
         };
         try {
-            return this.options.control ? await this.options.control.runPerson(run) : await run();
+            const outcome = this.options.control ? await this.options.control.runPerson(run) : await run();
+            // The log (§12): a person's input too, its typed text only as a length.
+            this.logAction("person", outcome.action?.kind ?? input.type, input.type === "text" ? { text: input.text } : {}, undefined, outcome.ok ? undefined : outcome.code, outcome.reason);
+            return outcome;
         }
         catch (error) {
             return { ok: false, code: "internal", message: error instanceof Error ? error.message : String(error) };
@@ -1015,11 +1489,28 @@ export class TaplineTools {
         const links = this.options.viewerLinks?.() ?? [];
         if (links.length === 0)
             return fail("Error unsupported: this host has no live viewer.");
-        const lines = [
-            "Live viewer (watch the app, see what you do, and let the user tap and type too):",
-            ...links.map((link) => `- ${link}`),
-            "The link carries a key: give it to the user only. While they use the viewer, their touches go first and your actions wait.",
-        ];
+        const open = this.options.openViewer;
+        const local = links[0];
+        let lines;
+        if (open !== undefined && this.options.viewerLinkToAgent !== true && local !== undefined) {
+            // The key in the link can approve a held-back touch: it goes to the browser, never to the agent.
+            const opened = open(local);
+            lines = [
+                opened
+                    ? "Opened the live view in a browser on this computer: the user watches the app and what you do there, and can tap and type too."
+                    : "Couldn't open a browser on this computer. Ask the user to start the MCP server with --viewer-link if they want the link.",
+                "The link isn't shown to you: its key can approve touches that need a person's OK.",
+                ...(links.length > 1 ? ["For their own devices on Tailscale, the user finds that link in this server's log."] : []),
+                "While the user acts in the live view, their touches go first and your actions wait.",
+            ];
+        }
+        else {
+            lines = [
+                "Live viewer (watch the app, see what you do, and let the user tap and type too):",
+                ...links.map((link) => `- ${link}`),
+                "The link carries a key: give it to the user only. While they use the viewer, their touches go first and your actions wait.",
+            ];
+        }
         const feed = this.options.viewerFeed?.();
         const session = this.host.current();
         if (feed?.on === true && session !== undefined) {
@@ -1151,8 +1642,13 @@ export class TaplineTools {
             const started = Date.now();
             if (args.tap !== undefined) {
                 // A screenshot takes a few hundred ms on a phone, so frame 1 is the "before".
+                // The tap is a touch like any other: the safety policy decides first.
+                const pressParams = { target: toWireTarget(args.tap) };
+                const gate = await this.policyGate(session, "tap", "press", pressParams, listsFor(this.policy, session.app));
+                if ("stop" in gate)
+                    return gate.stop;
                 frames.push(await this.takeShot(session.id, frameWidth, 0.8));
-                await this.host.request("press", { target: toWireTarget(args.tap) }, { sessionId: session.id });
+                await this.host.request("press", pressParams, { sessionId: session.id });
             }
             for (let i = frames.length; i < count; i++) {
                 const at = Date.now();
@@ -1178,9 +1674,10 @@ export class TaplineTools {
         return dir === undefined || !SCRIPT_NAME.test(name) ? null : join(dir, `${name}.json`);
     }
     async record(args) {
-        switch (args.action) {
+        const op = args.action ?? (args.start === true ? "start" : args.stop === true ? "stop" : "status");
+        switch (op) {
             case "start": {
-                const name = (args.name ?? "").trim();
+                const name = (args.name ?? "").trim() || `session-${new Date().toISOString().slice(0, 19).replace(/[-:T]/g, "")}`;
                 if (this.scriptPath(name) === null) {
                     return fail("Error bad_params: give the script a name of letters, digits, '.', '_' and '-' (e.g. \"checkout\").");
                 }
@@ -1190,7 +1687,7 @@ export class TaplineTools {
                 if (session === undefined)
                     return this.notConnected();
                 this.recording = { name, app: { name: session.app.name, ...(session.app.id ? { id: session.app.id } : {}) }, steps: [] };
-                return text(`Recording "${name}" on ${session.app.name}. Every action from now on is a step; wait_for steps check the app is where it should be. Prefer testIDs: they replay best. Stop with record { action: "stop" }.`);
+                return text(`Recording "${name}" on ${session.app.name}. Every action from now on is a step; wait_for steps check the app is where it should be. Prefer testIDs: they replay best. Stop with record { stop: true }.`);
             }
             case "status":
                 return text(this.recording === null
@@ -1204,16 +1701,17 @@ export class TaplineTools {
             case "stop": {
                 const recording = this.recording;
                 if (recording === null)
-                    return fail("Error bad_params: not recording; start with record { action: \"start\", name }.");
-                const path = this.scriptPath(recording.name);
+                    return fail("Error bad_params: not recording; start with record { start: true, name }.");
+                const path = args.path !== undefined && args.path.trim() !== "" ? args.path.trim() : this.scriptPath(recording.name);
                 if (path === null)
-                    return fail("Error internal: no scripts folder is configured.");
+                    return fail("Error internal: no scripts folder is configured; give a path.");
                 const script = {
+                    format: "agent-tools-script",
                     version: 1,
                     name: recording.name,
-                    app: recording.app,
-                    recordedAt: new Date().toISOString(),
-                    steps: recording.steps,
+                    app: recording.app.id ?? recording.app.name,
+                    fresh: true,
+                    steps: scriptSteps(recording.steps),
                 };
                 try {
                     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
@@ -1224,15 +1722,17 @@ export class TaplineTools {
                 }
                 this.recording = null;
                 const count = script.steps.length;
-                const lines = [`Saved "${script.name}": ${count} step${count === 1 ? "" : "s"} in ${path}. Replay it with replay { name: "${script.name}" }.`];
-                script.steps.forEach((step, i) => {
-                    if (step.fragile) {
-                        const target = step.params["target"];
-                        lines.push(`Note: step ${i + 1} targets ref ${String(target.ref)}, which won't exist on a new run. Give that element a testID, or record it again by its text or label.`);
-                    }
-                });
-                if (script.steps.some((step) => step.method === "type")) {
-                    lines.push("The script keeps the text typed in it (test passwords too): keep it private.");
+                const lines = [`Saved ${count} step${count === 1 ? "" : "s"} to ${path}.`];
+                const ref = refStep(script.steps);
+                if (ref !== null) {
+                    lines.push(`Note: step ${ref + 1} targets a ref, which won't exist on a new run, so replay refuses the script. Give that element a testID, or record it again by its text or label.`);
+                }
+                const secrets = recording.steps.filter((step) => step.secret === true).length;
+                if (secrets > 0) {
+                    lines.push(`${secrets} step${secrets === 1 ? " types" : "s type"} into a password field: that text isn't saved. Put a test password into the script before you replay it.`);
+                }
+                if (recording.steps.some((step) => step.method === "type" && step.secret !== true)) {
+                    lines.push("The script keeps the other text typed in it: keep it private.");
                 }
                 return text(lines.join("\n"));
             }
@@ -1245,11 +1745,10 @@ export class TaplineTools {
         const lines = [];
         for (const file of readdirSync(dir).filter((f) => f.endsWith(".json")).sort()) {
             try {
-                const parsed = scriptSchema.safeParse(JSON.parse(readFileSync(join(dir, file), "utf8")));
-                if (!parsed.success)
+                const s = readScript(readFileSync(join(dir, file), "utf8"));
+                if (s === null)
                     continue;
-                const s = parsed.data;
-                lines.push(`- ${s.name} (${s.steps.length} step${s.steps.length === 1 ? "" : "s"}, recorded ${s.recordedAt.slice(0, 10)} on ${s.app.name})`);
+                lines.push(`- ${s.name} (${s.steps.length} step${s.steps.length === 1 ? "" : "s"}${s.app ? `, ${s.app}` : ""})`);
             }
             catch {
                 // skip unreadable files
@@ -1259,64 +1758,60 @@ export class TaplineTools {
     }
     async replay(args) {
         const name = (args.name ?? "").trim();
-        if (name === "")
+        const given = (args.path ?? "").trim();
+        if (name === "" && given === "")
             return text(this.scriptList());
         if (this.recording !== null)
             return fail(`Error bad_params: stop recording "${this.recording.name}" before replaying.`);
-        const path = this.scriptPath(name);
+        const path = given !== "" ? given : this.scriptPath(name);
         if (path === null || !existsSync(path))
-            return fail(`Error not_found: no script "${name}".\n${this.scriptList()}`);
+            return fail(`Error not_found: no script "${given || name}".\n${this.scriptList()}`);
         let script;
         try {
-            const parsed = scriptSchema.safeParse(JSON.parse(readFileSync(path, "utf8")));
-            if (!parsed.success)
-                return fail(`Error bad_params: ${path} isn't a Tapline script.`);
-            script = parsed.data;
+            script = readScript(readFileSync(path, "utf8"));
         }
         catch (error) {
             return fail(`Error internal: couldn't read ${path}: ${error instanceof Error ? error.message : String(error)}`);
         }
+        if (script === null)
+            return fail(`Error bad_params: ${path} isn't a script (format agent-tools-script, version 1).`);
+        const ref = refStep(script.steps);
+        if (ref !== null)
+            return fail(`Error bad_params: step ${ref + 1} targets a ref; a script needs an id, label, text or point.`);
+        if (script.steps.length === 0)
+            return text(`Ran 0 of 0 steps in 0.0 s.`);
         const session = this.host.current();
         if (session === undefined)
             return this.notConnected();
-        const started = Date.now();
-        const total = script.steps.length;
-        const lines = [];
-        const seconds = (ms) => (Math.round(ms / 100) / 10).toFixed(1);
+        const notes = [];
+        script.steps.forEach((step, i) => {
+            const target = step["target"];
+            if (typeof target === "object" && target !== null && "x" in target) {
+                notes.push(`Note (step ${i + 1}): a point target; it breaks when the layout changes.`);
+            }
+        });
+        if (script.fresh !== false) {
+            // Tapline can't close and open the app: it starts its JavaScript again (a development build).
+            const fresh = await this.reload({});
+            const said = fresh.content.map((block) => (block.type === "text" ? block.text : "")).join("\n");
+            if (fresh.isError === true)
+                notes.push("Note: couldn't start the app fresh (a release build has no reload); the script ran on the screen as it was.");
+            else if (said.startsWith("Reload requested, but"))
+                notes.push("Note: the app hadn't reconnected after starting fresh when the steps began.");
+        }
         this.replaying = true;
         try {
-            for (const [i, step] of script.steps.entries()) {
-                const at = Date.now();
-                const label = `${i + 1} ${describeStep(step)}`;
-                if (step.method === "sleep") {
-                    const s = typeof step.params["seconds"] === "number" ? step.params["seconds"] : 0;
-                    await sleep(Math.min(30, Math.max(0, s)) * 1000);
-                    lines.push(`${i + 1} ✓ ${describeStep(step)} (${seconds(Date.now() - at)} s)`);
-                    continue;
-                }
-                const result = await this.act(step.method, step.params, () => "", true);
-                const problem = result.isError
-                    ? result.content.map((block) => (block.type === "text" ? block.text : "")).join("\n").trim()
-                    : step.route !== undefined &&
-                        this.lastLookRoute !== undefined &&
-                        step.route.join(" › ") !== this.lastLookRoute.join(" › ")
-                        ? `It ended on ${this.lastLookRoute.join(" › ")}; the recording ended on ${step.route.join(" › ")}.`
-                        : null;
-                if (problem !== null) {
-                    return fail([
-                        `Replay "${script.name}" failed at step ${i + 1} of ${total}: ${describeStep(step)}`,
-                        problem,
-                        ...(lines.length > 0 ? ["Steps before it passed:", ...lines] : []),
-                        ...(step.fragile ? ["Note: this step targets a ref from the recording run; give the element a testID."] : []),
-                    ].join("\n"));
-                }
-                lines.push(`${label.replace(/^(\d+) /, "$1 ✓ ")} (${seconds(Date.now() - at)} s)`);
-            }
+            const answer = await this.run({ steps: script.steps, look: args.look, screenshot: args.screenshot });
+            if (notes.length === 0)
+                return answer;
+            const [top, ...rest] = answer.content;
+            return top !== undefined && top.type === "text"
+                ? { ...answer, content: [{ type: "text", text: [top.text.trimEnd(), ...notes].join("\n") }, ...rest] }
+                : answer;
         }
         finally {
             this.replaying = false;
         }
-        return text([`Replayed "${script.name}" on ${session.app.name}: ${total} of ${total} steps passed in ${seconds(Date.now() - started)} s.`, ...lines].join("\n"));
     }
     async withLook(session, line, screenshot = false) {
         // The session may have been replaced (app restarted) in the meantime.
@@ -1329,21 +1824,275 @@ export class TaplineTools {
         const head = first !== undefined && first.type === "text" ? first.text : "";
         return { content: [{ type: "text", text: `${line}\n${head}` }, ...rest] };
     }
-    /** The line (without its actions) of the element a result carries under `key`. */
-    elementName(result, key = "element") {
+    /**
+     * The element a result carries under `key`, for an answer's first line: without its actions, position or
+     * size (AGENT-TOOLS 1.8 §13 rule 1; the change block or list has them). `withoutValue` for type_text,
+     * whose sentence says the value (rule 5).
+     */
+    elementName(result, key = "element", withoutValue = false) {
         if (typeof result === "object" && result !== null && key in result) {
             const element = elementSchema.safeParse(result[key]);
-            if (element.success)
-                return formatElement(element.data, { actions: false });
+            if (element.success) {
+                const shown = withoutValue ? { ...element.data, value: null, placeholder: null } : element.data;
+                return formatElement(shown, { actions: false, frame: false });
+            }
         }
         return "element";
     }
+    // -- the safety policy (AGENT-TOOLS 1.8 §11)
+    /**
+     * A guarded touch: the app resolves the target in a dry run, the policy's words are matched against the
+     * element's own label and text, and a confirm word waits for a person's OK in the live view. The check runs
+     * inside the agent's turn, right before the touch, so nothing a person does in between can change what is
+     * touched; when the check can't be made, nothing is touched (fail closed).
+     */
+    async guarded(tool, method, params, dryRun, perform) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        this.logExtra = undefined;
+        this.actionStartedAt = Date.now();
+        const lists = listsFor(this.policy, session.app);
+        if (!dryRun && lists.confirm.length === 0 && lists.block.length === 0)
+            return perform();
+        const stale = this.staleRef(params);
+        if (stale !== null)
+            return stale;
+        if (dryRun) {
+            const resolved = await this.resolveForPolicy(session, method, params);
+            this.logExtra = { dry_run: true };
+            if (resolved.kind === "error") {
+                this.showAction("agent", method, undefined, params, resolved.code, resolved.reason);
+                return fail(resolved.text);
+            }
+            const verdict = this.policyWords(lists, resolved.elements);
+            const shown = resolved.elements[0];
+            if (verdict.kind === "blocked") {
+                this.showAction("agent", method, { element: verdict.element }, params, "not_allowed", "blocked");
+                return fail(this.blockedLine(verdict.element, verdict.word));
+            }
+            const would = this.wouldLine(tool, shown, resolved.point, resolved.value);
+            const needs = verdict.kind === "confirm" ? ` It needs a person's OK (policy word ${JSON.stringify(verdict.word)}).` : "";
+            this.showAction("agent", method, shown !== undefined ? { element: shown } : undefined, params);
+            return text([`${would}${needs}`, ...this.takePersonNote()].join("\n"));
+        }
+        let granted = false;
+        const answer = await perform(async () => {
+            const gate = await this.policyGate(session, tool, method, params, lists);
+            if ("stop" in gate)
+                return gate.stop;
+            granted = gate.granted;
+            if (granted)
+                this.logExtra = { confirmed: true };
+            return null;
+        });
+        return granted && answer.isError !== true ? appendNote(answer, "Note: a person allowed this.") : answer;
+    }
+    /**
+     * The policy's verdict on a touch about to happen: stop with an answer (blocked, needs a person's OK, or
+     * the check couldn't be made: fail closed), or go on (`granted` when a person's OK is being used up).
+     */
+    async policyGate(session, tool, method, params, lists) {
+        if (lists.confirm.length === 0 && lists.block.length === 0)
+            return { granted: false };
+        const resolved = await this.resolveForPolicy(session, method, params);
+        if (resolved.kind === "error") {
+            // Fail closed: what can't be checked isn't touched. The answer is the one the touch would give.
+            this.showAction("agent", method, undefined, params, resolved.code, resolved.reason);
+            return { stop: fail(resolved.text) };
+        }
+        const verdict = this.policyWords(lists, resolved.elements);
+        if (verdict.kind === "blocked") {
+            this.showAction("agent", method, { element: verdict.element }, params, "not_allowed", "blocked");
+            return { stop: fail(this.blockedLine(verdict.element, verdict.word)) };
+        }
+        if (verdict.kind === "none")
+            return { granted: false };
+        const label = verdict.element.label ?? verdict.element.text ?? undefined;
+        const caption = captionFor(tool, label ?? undefined, params) ?? tool;
+        // An OK is for this app, this tool and this element only (Tapwright's review, M1).
+        const check = this.confirmations.check(`${session.app.id}|${tool}|${elementKey(verdict.element)}`, { kind: tool, caption, word: verdict.word });
+        if (check.granted)
+            return { granted: true };
+        const name = this.shortName(verdict.element, false);
+        if ("held" in check) {
+            this.showAction("agent", method, { element: verdict.element }, params, "not_allowed", "needs_confirmation");
+            return {
+                stop: fail(`Error not_allowed: needs_confirmation: ${name} needs a person's OK (policy word ${JSON.stringify(verdict.word)}), and they declined it just now. Don't ask again by repeating the call: ask your user what they want.`),
+            };
+        }
+        const where = this.options.canConfirm === false
+            ? "The live view is off, so nobody can allow it here; ask your user."
+            : "The live view asks them now; when they allow it, make the same call again. If nobody is watching, ask your user.";
+        this.showAction("agent", method, { element: verdict.element }, params, "not_allowed", "needs_confirmation");
+        return {
+            stop: fail(`Error not_allowed: needs_confirmation: ${this.shortName(verdict.element, false)} needs a person's OK (policy word ${JSON.stringify(verdict.word)}). ${where}${check.suffix}`),
+        };
+    }
+    /** Which policy word, if any, the elements the target could mean carry: a block word first, then a confirm word. */
+    policyWords(lists, elements) {
+        for (const element of elements) {
+            const word = matchWord(lists.block, element);
+            if (word !== null)
+                return { kind: "blocked", element, word };
+        }
+        for (const element of elements) {
+            const word = matchWord(lists.confirm, element);
+            if (word !== null)
+                return { kind: "confirm", element, word };
+        }
+        return { kind: "none" };
+    }
+    blockedLine(element, word) {
+        return `Error not_allowed: blocked: ${this.shortName(element, false)} is blocked by the policy (${JSON.stringify(word)}); don't try another way.`;
+    }
+    /** A dry run the app answers itself (scroll, back, swipe): its checks, nothing touched, one line. */
+    async dryCall(method, params, line) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        if (!session.capabilities.includes("dryRun")) {
+            return fail("Error unsupported: this app's Tapline is too old for dry runs; update react-native-tapline.");
+        }
+        const stale = this.staleRef(params);
+        if (stale !== null)
+            return stale;
+        this.actionStartedAt = Date.now();
+        let result;
+        try {
+            result = await this.host.request(method, { ...params, dryRun: true }, { sessionId: session.id });
+        }
+        catch (error) {
+            this.logExtra = { dry_run: true };
+            this.showAction("agent", method, undefined, params, error instanceof TaplineError ? error.code : "internal", error instanceof TaplineError ? reasonOf(error.code, error.message) : undefined);
+            return fail(describeError(error));
+        }
+        if (typeof result !== "object" || result === null || result.dryRun !== true) {
+            return fail("Error internal: the app didn't answer the dry run.");
+        }
+        this.logExtra = { dry_run: true };
+        this.showAction("agent", method, result, params);
+        return text([line(result), ...this.takePersonNote()].join("\n"));
+    }
+    /** A dry run of a tool the policy doesn't guard (type_text): the app's checks, nothing touched. */
+    async dryRun(tool, method, params) {
+        const session = this.host.current();
+        if (session === undefined)
+            return this.notConnected();
+        const stale = this.staleRef(params);
+        if (stale !== null)
+            return stale;
+        const resolved = await this.resolveForPolicy(session, method, params);
+        this.logExtra = { dry_run: true };
+        if (resolved.kind === "error") {
+            this.showAction("agent", method, undefined, params, resolved.code, resolved.reason);
+            return fail(resolved.text);
+        }
+        this.showAction("agent", method, resolved.elements[0] !== undefined ? { element: resolved.elements[0] } : undefined, params);
+        return text([this.wouldLine(tool, resolved.elements[0], resolved.point, resolved.value), ...this.takePersonNote()].join("\n"));
+    }
+    /**
+     * What a touch would act on. Apps that know dry runs resolve it themselves, with every check; older
+     * apps only give their element list, and every element the target could mean is checked.
+     */
+    async resolveForPolicy(session, method, params) {
+        if (session.capabilities.includes("dryRun")) {
+            let raw;
+            try {
+                raw = await this.host.request(method, { ...params, dryRun: true }, { sessionId: session.id });
+            }
+            catch (error) {
+                const reason = error instanceof TaplineError ? reasonOf(error.code, error.message) : undefined;
+                return {
+                    kind: "error",
+                    text: describeError(error),
+                    code: error instanceof TaplineError ? error.code : "internal",
+                    ...(reason !== undefined ? { reason } : {}),
+                };
+            }
+            const parsed = dryRunResultSchema.safeParse(raw);
+            if (!parsed.success)
+                return { kind: "error", text: "Error internal: the app didn't answer the dry run.", code: "internal" };
+            return {
+                kind: "ok",
+                elements: parsed.data.element ? [parsed.data.element] : [],
+                ...(parsed.data.point !== undefined ? { point: parsed.data.point } : {}),
+                ...(parsed.data.value !== undefined ? { value: parsed.data.value } : {}),
+            };
+        }
+        // An app without dry runs: a swipe is checked by what lies under its start.
+        const target = method === "swipe" ? { x: params["x0"], y: params["y0"] } : params["target"];
+        if (method === "type" || target === undefined) {
+            return { kind: "error", text: "Error unsupported: this app's Tapline is too old for dry runs; update react-native-tapline.", code: "unsupported" };
+        }
+        let raw;
+        try {
+            raw = await this.host.request("tree", {}, { sessionId: session.id });
+        }
+        catch (error) {
+            return { kind: "error", text: describeError(error), code: error instanceof TaplineError ? error.code : "internal" };
+        }
+        const tree = treeResultSchema.safeParse(raw);
+        if (!tree.success)
+            return { kind: "error", text: "Error internal: the app returned an element list the host could not read.", code: "internal" };
+        const elements = candidatesFor(target, tree.data.elements);
+        if (elements.length === 0 && method !== "swipe") {
+            return { kind: "error", text: "Error not_found: nothing on screen matches that target.", code: "not_found" };
+        }
+        const first = elements[0];
+        const frame = elements.length === 1 && first !== undefined ? first.frame : null;
+        return {
+            kind: "ok",
+            elements,
+            ...(frame ? { point: { x: Math.round(frame.x + frame.width / 2), y: Math.round(frame.y + frame.height / 2) } } : {}),
+        };
+    }
+    /** `Would tap e12 button "Delete trip" at 215,640.` */
+    wouldLine(tool, element, point, value) {
+        const name = element !== undefined ? this.shortName(element, true) : "the element";
+        const at = point !== undefined ? ` at ${point.x},${point.y}` : "";
+        switch (tool) {
+            case "long_press":
+                return `Would long-press ${name}${at}.`;
+            case "toggle":
+                return `Would toggle ${name}${typeof value === "boolean" ? ` to ${String(value)}` : ""}${at}.`;
+            case "type_text":
+                return `Would type into ${name}.`;
+            default:
+                return `Would tap ${name}${at}.`;
+        }
+    }
+    /** `e12 button "Delete trip"`: ref (when asked), role and name, nothing else. */
+    shortName(element, withRef) {
+        return formatElement({
+            ref: withRef ? element.ref : "",
+            role: element.role ?? null,
+            type: element.type ?? null,
+            label: element.label ?? null,
+            text: element.text ?? null,
+            textMore: element.textMore ?? null,
+        }, { actions: false });
+    }
+    /** A `{ref}` target after a person used the app: refs may point elsewhere. */
+    staleRef(params) {
+        if (!this.personActed)
+            return null;
+        const target = typeof params === "object" && params !== null ? params.target : undefined;
+        if (typeof target === "object" && target !== null && "ref" in target) {
+            // The error says it already, so the note isn't repeated.
+            this.personNotePending = false;
+            return fail("Error stale: a person used the app since your last look, so refs from that list may point elsewhere. Look again, or target by id, label or text.");
+        }
+        return null;
+    }
     tap(args) {
-        return this.act("press", { target: toWireTarget(args.target), ...(args.force === true ? { force: true } : {}) }, (r) => `Tapped ${this.elementName(r)}.`, args.look, args.screenshot);
+        const params = { target: toWireTarget(withIndex(args.target, args.index)), ...(args.force === true ? { force: true } : {}) };
+        return this.guarded("tap", "press", params, args.dry_run === true, (preflight) => this.act("press", params, (r) => `Tapped ${this.elementName(r)}.`, args.look, args.screenshot, undefined, undefined, preflight));
     }
     /** `seconds` is accepted for the shared interface; Tapline calls the handler, so it doesn't hold. */
     longPress(args) {
-        return this.act("longPress", { target: toWireTarget(args.target), ...(args.force === true ? { force: true } : {}) }, (r) => `Long-pressed ${this.elementName(r)}.`, args.look, args.screenshot);
+        const params = { target: toWireTarget(withIndex(args.target, args.index)), ...(args.force === true ? { force: true } : {}) };
+        return this.guarded("long_press", "longPress", params, args.dry_run === true, (preflight) => this.act("longPress", params, (r) => `Long-pressed ${this.elementName(r)}.`, args.look, args.screenshot, undefined, undefined, preflight));
     }
     typeText(args) {
         const params = {
@@ -1352,13 +2101,18 @@ export class TaplineTools {
             submit: args.submit ?? false,
         };
         if (args.target !== undefined)
-            params["target"] = toWireTarget(args.target);
+            params["target"] = toWireTarget(withIndex(args.target, args.index));
         if (args.force === true)
             params["force"] = true;
+        // Typing isn't guarded by the policy (§11.1: the form's button is); a dry run still checks the field.
+        if (args.dry_run === true)
+            return this.dryRun("type_text", "type", params);
         return this.act("type", params, (r) => {
             const value = typeof r === "object" && r !== null && "value" in r ? r.value : undefined;
-            const shown = typeof value === "string" ? ` Value is now ${JSON.stringify(value)}.` : "";
-            return `Typed into ${this.elementName(r)}${args.submit ? " and submitted" : ""}.${shown}`;
+            // AGENT-TOOLS 1.8 §3.3: a secure field's value is never shown, not even as bullets in this line
+            const secure = typeof r === "object" && r !== null && "secure" in r && r.secure === true;
+            const shown = secure ? " The value is hidden (secure field)." : typeof value === "string" ? ` Value is now ${JSON.stringify(value)}.` : "";
+            return `Typed into ${this.elementName(r, "element", shown !== "")}${args.submit ? " and submitted" : ""}.${shown}`;
         }, args.look, args.screenshot);
     }
     scroll(args) {
@@ -1375,6 +2129,13 @@ export class TaplineTools {
         const flag = (r, key) => typeof r === "object" && r !== null && key in r ? r[key] : undefined;
         // The element was on screen and clear already: nothing was scrolled, and the first line says so.
         const alreadyThere = (r) => toTarget && flag(r, "unchanged") === true;
+        if (args.dry_run === true) {
+            return this.dryCall("scroll", params, (r) => {
+                if (toTarget)
+                    return `Would scroll ${this.elementName(r)} to ${this.elementName(r, "target")}.`;
+                return `Would scroll ${this.elementName(r)} ${args.to !== undefined ? `to ${args.to}` : (args.direction ?? "down")}.`;
+            });
+        }
         const atEndAlready = (r) => (args.to === "start" || args.to === "end") && flag(r, "moved") === false;
         return this.act("scroll", params, (r) => {
             if (alreadyThere(r))
@@ -1410,19 +2171,19 @@ export class TaplineTools {
         });
     }
     toggle(args) {
-        const params = { target: toWireTarget(args.target) };
+        const params = { target: toWireTarget(withIndex(args.target, args.index)) };
         if (args.value !== undefined)
             params["value"] = args.value;
         if (args.force === true)
             params["force"] = true;
         // The switch already had the asked value: the app touched nothing, and that line is the whole answer.
         const unchanged = (r) => typeof r === "object" && r !== null && "unchanged" in r && r.unchanged === true;
-        return this.act("toggle", params, (r) => {
+        return this.guarded("toggle", "toggle", params, args.dry_run === true, (preflight) => this.act("toggle", params, (r) => {
             const value = typeof r === "object" && r !== null && "value" in r ? r.value : undefined;
             if (unchanged(r))
                 return `${this.elementName(r)} is already ${JSON.stringify(value)}.`;
             return `Toggled ${this.elementName(r)}${value !== undefined ? ` to ${JSON.stringify(value)}` : ""}.`;
-        }, args.look, args.screenshot, undefined, unchanged);
+        }, args.look, args.screenshot, undefined, unchanged, preflight));
     }
     async appCommand(args) {
         if (args.name === undefined || args.name.trim() === "") {
@@ -1474,12 +2235,30 @@ export class TaplineTools {
         const params = { x0: args.x0, y0: args.y0, x1: args.x1, y1: args.y1 };
         if (args.seconds !== undefined)
             params["seconds"] = args.seconds;
-        return this.act("swipe", params, (r) => {
+        if (args.dry_run === true) {
+            return this.dryCall("swipe", params, (r) => {
+                const on = this.elementName(r);
+                return `Would swipe from (${args.x0}, ${args.y0}) to (${args.x1}, ${args.y1})${on === "element" ? "" : ` starting on ${on}`}.`;
+            });
+        }
+        // A swipe that moves less than 10 pt is a touch where it starts: the policy checks it (AGENT-TOOLS 1.8 §11.1).
+        const short = Math.hypot(args.x1 - args.x0, args.y1 - args.y0) < 10;
+        const perform = (preflight) => this.act("swipe", params, (r) => {
             const on = this.elementName(r);
             return `Swiped from (${args.x0}, ${args.y0}) to (${args.x1}, ${args.y1})${on === "element" ? "" : ` on ${on}`}.`;
-        }, args.look, args.screenshot);
+        }, args.look, args.screenshot, undefined, undefined, preflight);
+        return short ? this.guarded("swipe", "swipe", params, false, perform) : perform();
     }
     back(args) {
+        if (args.dry_run === true) {
+            return this.dryCall("back", {}, (r) => {
+                if (typeof r === "object" && r !== null && "closed" in r && r.closed === "sheet")
+                    return "Would close the sheet.";
+                const route = typeof r === "object" && r !== null && "route" in r ? r.route : undefined;
+                const from = Array.isArray(route) && route.every((name) => typeof name === "string") ? ` from ${route.join(" › ")}` : "";
+                return `Would go back${from}.`;
+            });
+        }
         return this.act("back", {}, (r) => {
             if (typeof r === "object" && r !== null && "closed" in r && r.closed === "sheet")
                 return "Closed the sheet.";
@@ -1488,8 +2267,16 @@ export class TaplineTools {
             return `Went back${from}.`;
         }, args.look, args.screenshot);
     }
-    openUrl(args) {
-        return this.act("openURL", { url: args.url }, () => `Opened ${args.url}.`, args.look, args.screenshot);
+    async openUrl(args) {
+        const answer = await this.act("openURL", { url: args.url }, () => `Opened ${args.url}.`, args.look, args.screenshot);
+        // The app's own forget link unpairs it, so it drops the connection before answering: that is the link working.
+        if (answer.isError === true && /(^|\/)tapline\/forget\/?$/.test(args.url.replace(/[?#].*$/, ""))) {
+            const said = answer.content.map((c) => (c.type === "text" ? c.text : "")).join("\n");
+            if (/^Error (reconnecting|not_connected)\b/.test(said)) {
+                return text("Unpaired: the app forgot this computer and disconnected. To connect it again, call `pair`.");
+            }
+        }
+        return answer;
     }
     async logs(args) {
         const session = this.host.current();