tapline-host 1.3.0 → 1.4.0

package/dist/tools.js

@@ -6,11 +6,13 @@ import { z } from "zod";
 import { annotateScreenshot } from "./annotate.js";
 import { agentKind, captionFor, personKind, reasonOf } from "./captions.js";
 import { composeFilmstrip, diffImages, imageSize } from "./images.js";
-import { alertNotes, describeElement, filterLogs, formatChanges, formatElement, formatLogAnswer, formatLogs, formatOffScreenAfterList, formatTree } from "./format.js";
+import { alertNotes, networkLine, describeElement, filterLogs, formatChanges, formatElement, formatLogAnswer, formatLogs, formatOffScreenAfterList, formatTree } from "./format.js";
 import { formatInspect, inspectResultSchema } from "./inspect.js";
 import { AUDIT_TYPES, auditResultSchema, auditTitle, formatAudit } from "./audit.js";
 import { NO_CRASH_TEXT, crashNote, disconnectNote, formatCrash } from "./crash.js";
 import { ActionLog, loggedTarget } from "./actionlog.js";
+import { reportFor } from "./report.js";
+import { randomBytes } from "node:crypto";
 import { Confirmations } from "./confirm.js";
 import { DEFAULT_POLICY, elementKey, listsFor, matchWord } from "./policy.js";
 import { readScript, refStep, scriptSteps } from "./script.js";
@@ -250,6 +252,9 @@ export const toolShapes = {
         tap: targetField.optional().describe("Tap this first, then measure what it sets off"),
     },
     wait: { seconds: z.number().min(0.1).max(30).describe("How long to wait, 0.1 to 30 seconds"), screenshot: screenshotField },
+    session_report: {
+        since: z.number().min(0).optional().describe("Epoch milliseconds: report only calls from then on (default: the start of this session)"),
+    },
     run: {
         steps: z
             .array(stepSchema)
@@ -265,6 +270,20 @@ export const toolShapes = {
         screenshot: screenshotField,
     },
 };
+/**
+ * The answer for a call that carries arguments the tool doesn't have (null when all are known). Zod strips unknown
+ * keys silently, so `audit {labels: true}` would run and ignore `labels`; this says so instead. Every way in to a
+ * tool (the MCP server, and through it the bench) goes through here; script steps are checked by `run` itself.
+ */
+export function unknownArgumentError(name, args) {
+    const known = Object.keys(toolShapes[name]);
+    const unknown = Object.keys(args).filter((key) => !known.includes(key));
+    if (unknown.length === 0)
+        return null;
+    // AGENT-TOOLS 1.11 wording, shared with Tapwright: every unknown name in one sentence.
+    const takes = known.length === 0 ? "it takes no arguments" : `it takes ${known.join(", ")}`;
+    return fail(`Error bad_params: ${name} doesn't take ${unknown.join(", ")}; ${takes}.`);
+}
 // ---- compare_screen ---------------------------------------------------------
 const DEFAULT_MATCH_THRESHOLD = 0.5;
 const MAX_REGION_LINES = 8;
@@ -618,7 +637,17 @@ const dryRunResultSchema = z.object({
     dryRun: z.literal(true),
     point: z.object({ x: z.number(), y: z.number() }).optional(),
     value: z.unknown().optional(),
+    /** The element is off screen and the action would scroll it into view first (§16.2); `point` is where it expects to touch after. */
+    scrolls: z.boolean().optional(),
 });
+/** Whether an app's answer says the action scrolled the element into view first (AGENT-TOOLS 1.12 §16.2). */
+function scrolledFirst(result) {
+    return typeof result === "object" && result !== null && "scrolled" in result && result.scrolled === true;
+}
+/** `Scrolled to it, then tapped …` when the action scrolled first: the sentence goes on after a lead-in. */
+function afterScroll(result, sentence) {
+    return scrolledFirst(result) ? `Scrolled to it, then ${sentence.charAt(0).toLowerCase()}${sentence.slice(1)}` : sentence;
+}
 /** 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)
@@ -657,6 +686,34 @@ const CRASH_NOTED_TOOLS = [
     "record", "replay", "tap", "longPress", "typeText", "scroll", "toggle", "appCommand", "waitFor", "swipe", "back",
     "openUrl", "logs", "reload", "performance", "wait",
 ];
+/** Every tool the agent calls, by handler name (the call log numbers these). */
+const CALL_TOOLS = {
+    apps: "apps", openApp: "open_app", pair: "pair", look: "look", run: "run", inspect: "inspect", audit: "audit",
+    checkLayout: "check_layout", viewer: "viewer", compareScreen: "compare_screen", filmstrip: "filmstrip", record: "record",
+    replay: "replay", tap: "tap", longPress: "long_press", typeText: "type_text", scroll: "scroll", toggle: "toggle",
+    appCommand: "app_command", waitFor: "wait_for", swipe: "swipe", back: "back", openUrl: "open_url", logs: "logs",
+    crash: "crash", reload: "reload", performance: "performance", wait: "wait", sessionReport: "session_report",
+};
+/** Calls logged with `"kind": "read"` when they logged no action of their own. */
+const READ_TOOLS = new Set([
+    "apps", "open_app", "pair", "look", "inspect", "audit", "check_layout", "viewer", "compare_screen", "filmstrip", "record",
+    "replay", "wait_for", "logs", "crash", "reload", "performance", "wait", "session_report",
+]);
+/** A look's picture arguments for the call log: booleans and numbers only; undefined when it gave none. */
+function pictureArgs(input) {
+    const out = {};
+    if (typeof input["screenshot"] === "boolean")
+        out.screenshot = input["screenshot"];
+    if (typeof input["width"] === "number" && Number.isFinite(input["width"]))
+        out.width = input["width"];
+    if (typeof input["labels"] === "boolean")
+        out.labels = input["labels"];
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** Tools whose answer carries the changes or the full list unless the call said `look: false`. */
+const LISTING_TOOLS = new Set(["tap", "long_press", "type_text", "scroll", "toggle", "swipe", "back", "open_url", "app_command", "run"]);
+/** Tools that act on one element: after a run of scrolls they log whether the element was already in the list. */
+const ELEMENT_ACTIONS = new Set(["tap", "long_press", "type_text", "toggle"]);
 /** The tool handlers behind the MCP server. They only talk to a TaplineHost, so they are easy to test. */
 export class TaplineTools {
     host;
@@ -670,9 +727,28 @@ export class TaplineTools {
     batch;
     /** Extra fields for the next log line (a dry run, a confirmed touch). */
     logExtra;
+    /** The call log (AGENT-TOOLS 1.11 §16.1): this run's id, when it began, and how many calls the agent has made. */
+    sessionTag = randomBytes(4).toString("hex");
+    startedAt = Date.now();
+    callCount = 0;
+    /** The call in flight (and everything it awaits): its log entries wait here for the size of its answer. */
+    callScope = new AsyncLocalStorage();
+    clientIdFn;
+    /** The tool of the previous call, for scroll runs. */
+    prevCallTool;
+    /**
+     * The latest full element list the agent was given. `stale`: only changes since. `unseen`: an action since then
+     * answered with no list and no changes (`look: false`), so the screen may be another one: neither "in the
+     * list" nor "not in it" can be said until a list is seen again.
+     */
+    listBase;
+    /** The list as it was before the current run of scrolls began. */
+    scrollBase;
     confirmations;
     policy;
     reloadSettleMs;
+    stillGapMs;
+    stillCapMs;
     noScreenshot = new Set();
     shotFiles = [];
     /** Sessions this agent has had an element list for (so later lists can be just the changes). */
@@ -719,6 +795,8 @@ export class TaplineTools {
         this.actionLog = options.logDir !== undefined ? new ActionLog(options.logDir) : null;
         this.actionLog?.open();
         this.reloadSettleMs = options.reloadSettleMs ?? 1500;
+        this.stillGapMs = options.stillGapMs ?? 150;
+        this.stillCapMs = options.stillCapMs ?? 2000;
         // 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.
         host.on("touch", (session) => {
@@ -734,6 +812,120 @@ export class TaplineTools {
             const method = original;
             Reflect.set(this, name, (...args) => this.noting(() => method.apply(this, args)));
         }
+        // Outermost: every call of the agent is numbered and logged (reads too) once its answer is known.
+        for (const [name, tool] of Object.entries(CALL_TOOLS)) {
+            const original = Reflect.get(this, name);
+            if (typeof original !== "function")
+                continue;
+            const method = original;
+            Reflect.set(this, name, (...args) => this.loggedCall(tool, args[0], () => method.apply(this, args)));
+        }
+    }
+    /** The agent's client id for the call log; the MCP server passes the client's name once it is known. */
+    setClientId(read) {
+        this.clientIdFn = read;
+    }
+    /** A call refused before it reached its tool (an unknown argument): numbered and logged like any other, so the report counts it. */
+    rejectedCall(tool, args, answer) {
+        const result = this.loggedCall(tool, args, () => answer);
+        return result instanceof Promise ? answer : result;
+    }
+    /** Numbers a call of the agent and logs it when its answer is known (§16.1). Calls within a call (`run`'s steps) are part of it. */
+    loggedCall(tool, args, run) {
+        if (this.actionLog === null || this.callScope.getStore() !== undefined)
+            return run();
+        const afterScrolls = this.prevCallTool === "scroll";
+        if (tool === "scroll" && !afterScrolls)
+            this.scrollBase = this.listBase;
+        this.prevCallTool = tool;
+        const state = { call: ++this.callCount, tool, afterScrolls, entries: [] };
+        const began = new Date();
+        let result;
+        try {
+            result = this.callScope.run(state, run);
+        }
+        catch (error) {
+            this.flushCall(state, args, began, undefined);
+            throw error;
+        }
+        if (result instanceof Promise) {
+            return result.then((answer) => {
+                this.flushCall(state, args, began, answer);
+                return answer;
+            }, (error) => {
+                this.flushCall(state, args, began, undefined);
+                throw error;
+            });
+        }
+        this.flushCall(state, args, began, result);
+        return result;
+    }
+    flushCall(state, args, began, answer) {
+        if (this.actionLog === null)
+            return;
+        const said = (answer?.content ?? []).map((block) => (block.type === "text" ? block.text : ""));
+        const size = said.reduce((sum, part) => sum + part.length, 0);
+        const failed = answer === undefined || answer.isError === true;
+        const input = typeof args === "object" && args !== null ? args : {};
+        const listed = LISTING_TOOLS.has(state.tool) && !failed && input["look"] !== false && input["dry_run"] !== true && !(state.tool === "app_command" && input["name"] === undefined);
+        const client = (this.clientIdFn ?? this.options.clientId)?.()?.replace(/[^\w .@/-]/g, "").slice(0, 60);
+        const common = {
+            session: this.sessionTag,
+            call: state.call,
+            ...(client !== undefined && client !== "" ? { client } : {}),
+            size,
+        };
+        const code = failed ? /^Error (\w+):/.exec(said.join("\n"))?.[1] : undefined;
+        if (state.entries.length > 0) {
+            // Actions that went through, in a call that failed after them (an expectation that didn't hold): the call's
+            // own outcome goes with them, so the report doesn't count it as a success (Codex review of 1.4.0).
+            const callFailed = failed && state.entries.every(({ entry }) => entry.ok) ? { call_failed: code ?? "internal" } : {};
+            for (const { entry, at } of state.entries)
+                this.actionLog.write({ ...entry, ...common, ...callFailed, ...(listed ? { listed: true } : {}) }, at);
+            return;
+        }
+        // A call that logged no action: a read, or an action refused before it began (then without `kind`).
+        const session = this.host.current();
+        const lookArgs = state.tool === "look" ? pictureArgs(input) : undefined;
+        this.actionLog.write({
+            by: "agent",
+            tool: state.tool,
+            ...(READ_TOOLS.has(state.tool) ? { kind: "read" } : {}),
+            // the target only (as given); typed text, pictures and log text never
+            ...(loggedTarget(args).target !== undefined ? { target: loggedTarget(args).target } : {}),
+            ok: !failed,
+            ...(code !== undefined ? { code } : {}),
+            ms: Date.now() - began.getTime(),
+            ...(session !== undefined ? { app: session.app.id ?? session.app.name } : {}),
+            ...common,
+            ...(listed ? { listed: true } : {}),
+            ...(lookArgs !== undefined ? { look_args: lookArgs } : {}),
+        }, began);
+    }
+    /**
+     * Whether a touch's target was in the list the agent had before its run of scrolls: true (it was), false (it
+     * wasn't), undefined (can't be known: no list, a point, or a list that only changed since).
+     */
+    knownBeforeScrolls(params) {
+        const base = this.scrollBase;
+        const target = typeof params === "object" && params !== null ? params.target : undefined;
+        if (base === undefined || typeof target !== "object" || target === null)
+            return undefined;
+        const t = target;
+        if (!["ref", "testID", "label", "text"].some((key) => typeof t[key] === "string"))
+            return undefined;
+        if (base.unseen)
+            return undefined;
+        if (candidatesFor(target, base.elements).length > 0)
+            return true;
+        return base.stale ? undefined : false;
+    }
+    /** `session_report` (AGENT-TOOLS 1.11 §16.1): where this session's calls went, and the waste in them. */
+    sessionReport(args = {}) {
+        const dir = this.options.logDir;
+        if (dir === undefined)
+            return fail("Error unsupported: the action log is off (--no-log), so there is nothing to report.");
+        return text(reportFor(dir, args.since ?? this.startedAt, this.sessionTag));
     }
     /**
      * Runs a tool call and ends its answer with a note when the app stopped (AGENT-TOOLS 15.2): during this
@@ -749,10 +941,32 @@ export class TaplineTools {
         return this.noteScope.run(true, () => {
             const result = run();
             if (result instanceof Promise)
-                return result.then((answer) => this.withCrashNotes(answer, mark, startedWith));
-            return this.withCrashNotes(result, mark, startedWith);
+                return result.then((answer) => this.withPersonNote(this.withCrashNotes(answer, mark, startedWith)));
+            return this.withPersonNote(this.withCrashNotes(result, mark, startedWith));
         });
     }
+    /** The first call has been answered, so the "needs a person" note has had its turn. */
+    personNoteDone = false;
+    /**
+     * The first answer of the session says what only a person can do, once, when something is pending: the app isn't
+     * connected (open it on the phone, same Wi-Fi), and the phone has never paired. Nothing pending: never.
+     */
+    withPersonNote(answer) {
+        if (this.personNoteDone || this.options.pairedBefore === undefined)
+            return answer;
+        if (this.host.current() !== undefined) {
+            this.personNoteDone = true;
+            return answer;
+        }
+        if (answer.content[0]?.type !== "text")
+            return answer; // nowhere to put it yet: the next answer says it
+        const items = [];
+        if (!this.options.pairedBefore())
+            items.push("the phone isn't paired yet (call `pair`, then the user scans the QR code or taps Connect)");
+        items.push("the app isn't connected (the user opens it on the phone, on the same Wi-Fi as this computer)");
+        this.personNoteDone = true;
+        return appendNote(answer, `Note: needs a person: ${items.join("; ")}.`);
+    }
     /** What was told about this app's crashes so far: the crash events up to this number. */
     notedSeqOf(app) {
         return this.notedCrashSeqs.get(identityOf(app)) ?? this.crashBaseline;
@@ -837,6 +1051,7 @@ export class TaplineTools {
     }
     // -- pair
     async pair(args) {
+        this.personNoteDone = true; // its answer says what the person does; no "call pair" note on it
         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.
@@ -1004,7 +1219,9 @@ export class TaplineTools {
                 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 { tool: _tool, expect: _expect, route: _route, ...given } = step;
+            // §9.1: a step's own look and screenshot are ignored (the batch answers once), whether its tool has them or not.
+            const params = Object.fromEntries(Object.entries(given).filter(([key]) => !(key === "look" || key === "screenshot") || key in shape));
             if (step.tool === "compare_screen" && params.update !== undefined) {
                 return fail(`Error bad_params: step ${i + 1}: update can't be used in run (a step never saves a reference)`);
             }
@@ -1037,6 +1254,12 @@ export class TaplineTools {
                     return fail(`Error bad_params: step ${i + 1} (${describeRunStep(step)}): launch reloads the app and tap taps in it; give one of them.`);
                 }
             }
+            // AGENT-TOOLS 1.11 §4: the shared wording, with the step first.
+            const known = Object.keys(shape);
+            const stray = Object.keys(params).filter((key) => !known.includes(key));
+            if (stray.length > 0) {
+                return fail(`Error bad_params: step ${i + 1}: ${step.tool} doesn't take ${stray.join(", ")}; ${known.length === 0 ? "it takes no arguments" : `it takes ${known.join(", ")}`}.`);
+            }
             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("; ")}`);
@@ -1145,6 +1368,7 @@ export class TaplineTools {
         let response;
         const live = this.host.current();
         if (args.look === false || live === undefined) {
+            this.markListUnseen();
             response = text([first, ...tail].join("\n"));
         }
         else {
@@ -1409,6 +1633,11 @@ export class TaplineTools {
         else
             this.alertOpen.delete(sid);
         const changesText = askChanges ? formatChanges(tree, { alertGone }) : null;
+        // For the call log: the list the agent now has (a change block leaves it as it was, but no longer certain).
+        if (changesText === null)
+            this.listBase = { elements: tree.elements, stale: false, unseen: false };
+        else if (this.listBase !== undefined)
+            this.listBase = { elements: this.listBase.elements, stale: true, unseen: false };
         // A full list gives every ref a fresh meaning, so refs are trustworthy again.
         if (changesText === null)
             this.personActed = false;
@@ -1478,6 +1707,11 @@ export class TaplineTools {
         this.personNotePending = false;
         return ["Note: a person used the app since your last look."];
     }
+    /** An action answered with no list and no changes: the call log can't say what is in the list any more. */
+    markListUnseen() {
+        if (this.listBase !== undefined)
+            this.listBase = { ...this.listBase, unseen: true };
+    }
     /** 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. */
@@ -1525,6 +1759,7 @@ export class TaplineTools {
             ? `Settled in ${(settledMs / 1000).toFixed(2)} s.`
             : undefined;
         if (withLook === false) {
+            this.markListUnseen();
             this.unlistedActions.set(session.id, (this.unlistedActions.get(session.id) ?? 0) + 1);
             response = text([line, ...this.takePersonNote()].join("\n"));
         }
@@ -1643,7 +1878,8 @@ export class TaplineTools {
             ? elementSchema.safeParse(result.element)
             : null;
         const session = this.host.current();
-        this.actionLog.write({
+        const state = by === "agent" ? this.callScope.getStore() : undefined;
+        const entry = {
             by,
             tool,
             ...loggedTarget(params),
@@ -1656,9 +1892,22 @@ export class TaplineTools {
             ...(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;
+        if (state === undefined) {
+            this.actionLog.write(entry);
+            return;
+        }
+        if (state.tool !== tool)
+            entry.of = state.tool;
+        // After scrolls: was the target already in the list before the first one? (a scroll hunt is exact when it was)
+        if (state.afterScrolls && state.tool === tool && ELEMENT_ACTIONS.has(tool)) {
+            const known = this.knownBeforeScrolls(params);
+            if (known !== undefined)
+                entry.in_list = known;
+        }
+        state.entries.push({ entry, at: new Date() });
     }
     showAction(by, method, result, params, code, reason) {
         const onAction = this.options.onAction;
@@ -1914,7 +2163,7 @@ export class TaplineTools {
     async checkAgainstReference(session, name, options) {
         let shot;
         try {
-            shot = await this.takeShot(session.id, options.width, 0.9);
+            shot = await this.stillShot(session.id, options.width, 0.9);
         }
         catch (error) {
             return { kind: "error", line: describeError(error) };
@@ -2062,10 +2311,35 @@ export class TaplineTools {
             // the failure still reads without the picture
         }
     }
+    /**
+     * A picture of the screen once it stopped moving: two in a row about 150 ms apart that agree (under 0.1% changed),
+     * at most 2 s. The app's settle sees React commits, not a native transition, so a screen pushed by the action before
+     * can still be sliding in (found on the phone, 2026-11-12). Past the cap, the last picture.
+     */
+    async stillShot(sessionId, width, quality) {
+        let previous = await this.takeShot(sessionId, width, quality);
+        const started = Date.now();
+        while (Date.now() - started < this.stillCapMs) {
+            await sleep(this.stillGapMs);
+            const next = await this.takeShot(sessionId, width, quality);
+            if (next.data === previous.data)
+                return next;
+            try {
+                const diff = diffImages(previous, next, { mask: [] });
+                if (diff.changedPercent < 0.1)
+                    return next;
+            }
+            catch {
+                return next; // sizes differ (a rotation): nothing to wait for
+            }
+            previous = next;
+        }
+        return previous;
+    }
     /** Takes the screen and saves it as the reference `name` in `dir`. */
     async saveReferenceHere(session, name, width, dir) {
         try {
-            return this.writeReference(dir, name, await this.takeShot(session.id, width, 0.9));
+            return this.writeReference(dir, name, await this.stillShot(session.id, width, 0.9));
         }
         catch (error) {
             return fail(describeError(error));
@@ -2243,7 +2517,7 @@ export class TaplineTools {
         const save = (shot) => this.writeReference(folder, name, shot);
         if (args.update === true) {
             try {
-                return save(await this.takeShot(session.id, width, 0.9));
+                return save(await this.stillShot(session.id, width, 0.9));
             }
             catch (error) {
                 return fail(describeError(error));
@@ -2566,7 +2840,7 @@ export class TaplineTools {
                 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 would = this.wouldLine(tool, shown, resolved.point, resolved.value, resolved.scrolls);
             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"));
@@ -2684,7 +2958,7 @@ export class TaplineTools {
             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"));
+        return text([this.wouldLine(tool, resolved.elements[0], resolved.point, resolved.value, resolved.scrolls), ...this.takePersonNote()].join("\n"));
     }
     /**
      * What a touch would act on. Apps that know dry runs resolve it themselves, with every check; older
@@ -2713,6 +2987,7 @@ export class TaplineTools {
                 elements: parsed.data.element ? [parsed.data.element] : [],
                 ...(parsed.data.point !== undefined ? { point: parsed.data.point } : {}),
                 ...(parsed.data.value !== undefined ? { value: parsed.data.value } : {}),
+                ...(parsed.data.scrolls === true ? { scrolls: true } : {}),
             };
         }
         // An app without dry runs: a swipe is checked by what lies under its start.
@@ -2743,24 +3018,27 @@ export class TaplineTools {
         };
     }
     /** `Would tap e12 button "Delete trip" at 215,640.` */
-    wouldLine(tool, element, point, value) {
-        const name = element !== undefined ? this.shortName(element, true) : "the element";
+    wouldLine(tool, element, point, value, scrolls) {
+        const name = element !== undefined ? this.shortName(element, true, scrolls === true) : "the element";
+        // Off screen (§16.2): `Would scroll to it, then tap e41 button "Save" id=save at 215,640.` The point is the one expected after the scroll.
+        const lead = scrolls === true ? "Would scroll to it, then" : "Would";
         const at = point !== undefined ? ` at ${point.x},${point.y}` : "";
         switch (tool) {
             case "long_press":
-                return `Would long-press ${name}${at}.`;
+                return `${lead} long-press ${name}${at}.`;
             case "toggle":
-                return `Would toggle ${name}${typeof value === "boolean" ? ` to ${String(value)}` : ""}${at}.`;
+                return `${lead} toggle ${name}${typeof value === "boolean" ? ` to ${String(value)}` : ""}${at}.`;
             case "type_text":
-                return `Would type into ${name}.`;
+                return `${lead} type into ${name}${scrolls === true ? at : ""}.`;
             default:
-                return `Would tap ${name}${at}.`;
+                return `${lead} tap ${name}${at}.`;
         }
     }
     /** `e12 button "Delete trip"`: ref (when asked), role and name, nothing else. */
-    shortName(element, withRef) {
+    shortName(element, withRef, withId = false) {
         return formatElement({
             ref: withRef ? element.ref : "",
+            ...(withId ? { testID: element.testID ?? null } : {}),
             role: element.role ?? null,
             type: element.type ?? null,
             label: element.label ?? null,
@@ -2782,12 +3060,12 @@ export class TaplineTools {
     }
     tap(args) {
         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));
+        return this.guarded("tap", "press", params, args.dry_run === true, (preflight) => this.act("press", params, (r) => afterScroll(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) {
         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));
+        return this.guarded("long_press", "longPress", params, args.dry_run === true, (preflight) => this.act("longPress", params, (r) => afterScroll(r, `Long-pressed ${this.elementName(r)}.`), args.look, args.screenshot, undefined, undefined, preflight));
     }
     typeText(args) {
         const params = {
@@ -2807,7 +3085,7 @@ export class TaplineTools {
             // 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}`;
+            return afterScroll(r, `Typed into ${this.elementName(r, "element", shown !== "")}${args.submit ? " and submitted" : ""}.${shown}`);
         }, args.look, args.screenshot);
     }
     scroll(args) {
@@ -2876,8 +3154,8 @@ export class TaplineTools {
         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)}` : ""}.`;
+                return `${scrolledFirst(r) ? "Scrolled to it; " : ""}${this.elementName(r)} is already ${JSON.stringify(value)}.`;
+            return afterScroll(r, `Toggled ${this.elementName(r)}${value !== undefined ? ` to ${JSON.stringify(value)}` : ""}.`);
         }, args.look, args.screenshot, undefined, unchanged, preflight));
     }
     async appCommand(args) {
@@ -2901,8 +3179,28 @@ export class TaplineTools {
                 : `${session.app.name} offers no commands.`);
         }
         const name = args.name.trim();
+        // AGENT-TOOLS 1.11 §16.4: a policy whose block list holds `network` refuses a condition; `normal` always goes.
+        if (name === "network") {
+            const mode = args.args?.mode;
+            const app = this.host.current()?.app;
+            const names = (words) => (words ?? []).some((word) => word.trim().toLowerCase() === "network");
+            const own = app === undefined ? undefined : (this.policy.apps?.[app.id ?? ""] ?? this.policy.apps?.[app.name]);
+            if (mode !== "normal" && names(listsFor(this.policy, app).block)) {
+                const where = own?.block !== undefined && app !== undefined ? `for ${app.name}` : "here";
+                return fail(`Error not_allowed: blocked: the safety policy blocks network ${where}.`);
+            }
+        }
         return this.act("command", { name, args: args.args ?? {} }, (r) => {
             const result = typeof r === "object" && r !== null && "result" in r ? r.result : null;
+            // Built in `network`: the same line every header carries while a condition is on (AGENT-TOOLS §16.4),
+            // then one sentence on what it reaches.
+            if (name === "network" && typeof result === "object" && result !== null && "mode" in result && typeof result.mode === "string") {
+                const covers = "covers" in result && typeof result.covers === "string" ? ` ${result.covers}` : "";
+                return `${networkLine(result.mode)}${covers}`;
+            }
+            // Standard `language`, `region` and `text_size` (AGENT-TOOLS §16.3): the app's own sentence, e.g. `Text size xl (1.12×).`
+            if (typeof result === "object" && result !== null && "say" in result && typeof result.say === "string")
+                return result.say;
             return result === null || result === undefined ? `Ran ${name}.` : `Ran ${name}: ${JSON.stringify(result)}`;
         }, args.look, args.screenshot);
     }
@@ -3022,8 +3320,10 @@ export class TaplineTools {
                 if (!worked)
                     return fail(describeError(error));
             }
-            if (args.look === false)
+            if (args.look === false) {
+                this.markListUnseen();
                 return text("Reload requested.");
+            }
             const deadline = Date.now() + this.reloadWaitMs;
             for (;;) {
                 const now = this.host.current();